ThunderPhone v3 jau veikia.Viską atlikite savarankiškai – nuo 2 ct/min.Skaityti pranešimą

Developer cookbook

Kintamieji ir kontekstas kiekvienam skambučiui

Suteikite kiekvienam skambučiui jo paties informaciją – kaip įvardytus kintamuosius raginimui arba laisvos formos santrauką, nekeisdami agento.

Kiekvienam skambučiui galima pateikti dviejų tipų konkrečiam skambučiui skirtą įvestį. Naudokite vieną iš jų arba abu kartu:

  • variables: įvardytos reikšmės, užpildančios raginime esančius {{placeholders}}. Naudokite jas laukams, kuriuos raginimas nurodo vardu, pavyzdžiui, skambinančiojo vardui, paskyros numeriui ar susitikimo laikui.
  • context: laisvos formos tekstas, pridedamas po raginimo. Naudokite jį trumpam aprašui, kuris netinka šablonui, pavyzdžiui, šio skambučio užduoties aprašymui ar anksčiau surinktoms pastaboms.

Abu veikia su išsaugotu agentu ir su įterptine konfigūracija, naudojant bet kurį toliau aprašytą skambučio pradžios būdą. Nė vienas nekeičia išsaugoto agento, jo versijų istorijos ar kitų nustatymų.

{
  "agent_id": 12,
  "variables": {"name": "Ada", "appointment_slot": "Tuesday at 10 AM"},
  "context": "Ada rescheduled twice last month. She prefers mornings and asked us not to call her work number."
}

Kintamieji

Į išsaugoto agento raginimą įterpkite vietos rezervavimo ženklus, tada pradėdami skambutį pateikite objektą variables. ThunderPhone atvaizduoja tekstą prieš siųsdamas skambučio konfigūraciją į balso vykdymo aplinką.

Kai reikšmių nereikia, praleiskite variables, nesiųskite null (atmetama su 400).

Vietos rezervavimo ženklai ir numatytosios reikšmės

You are calling {{name|Friend}} about account {{account_id}}.
The available appointment is {{ appointment_slot }}.

Pavadinimuose skiriamos didžiosios ir mažosios raidės, jie turi atitikti [A-Za-z_][A-Za-z0-9_]*. Tarpai aplink pavadinimą leidžiami; tarpas po | yra numatytosios reikšmės dalis ir yra išsaugomas. {{name|Friend}} naudoja Friend, kai trūksta name arba jo reikšmė yra null; tuščia eilutė yra aiškiai pateikta reikšmė. Trūkstamos reikšmės be numatytosios reikšmės tampa tuščiomis eilutėmis, o jų pavadinimai rodomi unresolved_variables. Tekstas tarp dvigubų riestinių skliaustų, kuris nėra tinkama vietos žyma, pašalinamas. Tekstas su dvigubais riestiniais skliaustais kiekvienoje pateiktoje reikšmėje pašalinamas atskirai; reikšmė negali pašalinti aplinkinio raginimo teksto ar kitos reikšmės. Nesutampantys dvigubų riestinių skliaustų skyrikliai taip pat pašalinami. JSON pavyzdžiuose raginimuose negalima naudoti {{. Reikšmės yra paprastas tekstas, niekada nevykdomos kaip kodas ir rekursyviai neišplečiamos kaip šablonai.

Kintamieji taip pat gali būti naudojami patvirtinimo raginimuose, siunčiamuose balso pašto pranešimuose ir sutikimo pranešimo tekste, kai šis laukas siunčiamas telefoniniam skambučiui. Agentas neturi atskiro first_message lauko: pradinius jo nurodymus įrašykite į raginimą. Esamos balso pašto vietos žymos {agent_name} ir {org_name} toliau veikia.

Reikšmės ir ribos

Reikšmės gali būti eilutės, skaičiai, loginės reikšmės arba null; loginės reikšmės pateikiamos kaip true ir false. Pašalinami „Unicode“ valdymo (Cc) simboliai, išskyrus naujos eilutės (\n), tabuliacijos (\t) ir eilutės grįžimo (\r) simbolius, formato (Cf) simboliai, išskyrus nulinio pločio nejungiamąjį ir jungiamąjį simbolius (U+200C, U+200D, kurie naudojami žodžiams rašyti indų ir arabų rašto kalbose), bei pakaitiniai (Cs) kodo taškai; \r\n normalizuojamas į \n. Kiekviena reikšmė pateikiant ribojama iki 2 000 simbolių. Pateiktos eilutės taip pat išvalomos ir sutrumpinamos prieš išsaugojimą. Pradinis objektas turi tilpti į 32 KB UTF-8 JSON formato; didesni objektai gauna 400 skambučio ir sesijos užklausose, o kampanijų importavimas atskirai nurodo netinkamas eilutes. Masyvai ir įdėtieji objektai kaip reikšmės nepriimami. Neatitinkantys metaduomenų raktai (pavyzdžiui, CSV antraštė su tarpu) išsaugomi ir grąžinami, tačiau į juos negalima nurodyti vietos rezervavimo ženklu.

Kontekstas

context yra eilutė, kurią sudaro iki 20 000 simbolių. ThunderPhone ją prideda po užklausos, užpildžius užklausos kintamuosius, kaip atskirtą bloką:

<your prompt, with its variables filled in>
 
Details for this call:
<call_context>
Ada rescheduled twice last month. She prefers mornings and asked us not to call her work number.
</call_context>

Agentas jį skaito kartu su savo nurodymais, todėl rašykite jį taip, kaip prieš skambutį informuotumėte kolegą. Kontekstas nėra šablonas: jame esantis {{name}} lieka toks, kaip parašyta. Jei tekstui reikia reikšmės, įrašykite ją patys prieš siųsdami.

  • null, tuščia eilutė arba vien tarpai reiškia, kad konteksto nėra.
  • Reikšmė, kuri nėra eilutė arba yra ilgesnė nei 20 000 simbolių, atmetama su 400 skambučio ir sesijos užklausose; iš konfigūracijos žiniatinklio kablio ji nutraukia apsikeitimą kaip netinkami variables (žr. toliau).
  • Pradiniai ir galiniai tarpai pašalinami, taip pat pašalinami tie patys valdymo ir formato simboliai kaip ir kintamųjų reikšmėse.
  • Kontekstas yra skambučio raginimo dalis, todėl jis įskaičiuojamas į skambučio raginimo dydį.

Žingsnių agente kontekstas pateikiamas po kiekvieno skambučio agento užklausos, o ne po kiekvieno žingsnio nurodymų.

Iš kur gaunamos reikšmės

Išeinančių skambučių API

Siųskite variables ir context naudodami POST /v1/call:

{
  "from_number": "+15551234567",
  "to_number": "+14155552671",
  "agent_id": 12,
  "variables": {
    "name": "Ada",
    "account_id": "A-17",
    "appointment_slot": "Tuesday at 10 AM"
  },
  "context": "Ada asked to be called back about the late fee on her March invoice."
}

Abu taip pat veikia su numatytuoju telefono numerio išeinančių skambučių agentu arba įterptiniu config.prompt. Naudojant įterptinę konfigūraciją, context taip pat gali būti config viduje – tame pačiame lauke, kurį grąžina konfigūracijos žiniatinklio kabliukas; jei siunčiate abu, jų tekstas turi būti vienodas. Idempotentiškumo rakto negalima pakartotinai naudoti su skirtingais kintamaisiais arba kitu kontekstu.

Kampanijos CSV

Ne telefono CSV stulpeliai jau saugomi kaip kontaktų kintamieji. Kiekvienas skambinimas dabar juos naudoja automatiškai. Naudokite antraštes, pvz., name, account_id ir appointment_slot, kad jos atitiktų jūsų vietos žymenis. Esamas vardo susiejimas gali sujungti vardo ir pavardės stulpelius į kintamąjį name. Kampanijos kontaktai neturi konkrečiam kontaktui skirto konteksto.

Dinaminės konfigūracijos žiniatinklio kabliukas

Blokuojančios konfigūracijos žiniatinklio kablio kelyje grąžinkite jūsų organizacijoje išsaugotą agentą ir visas konkretaus skambučio reikšmes. Full duplex agento atveju skambutis išlaiko agento balsą, net jei skambutis pradedamas kita palaikoma kalba: tam skambučiui netaikomi balsų susiejimai pagal kalbą ir vietinis balso perjungimas.

{
  "agent_id": 12,
  "variables": {"name": "Ada", "account_id": "A-17"},
  "context": "[REDACTED_LITERAL]"
}
{
  "agent_id": 12,
  "variables": {"name": "Ada", "account_id": "A-17"},
  "context": "Ada called yesterday about a leak in unit 4B; a plumber is booked for Friday."
}

Atsakymo kintamieji perrašo užklausos lygio kintamuosius, o kiti užklausos raktai išlieka. Atsakymo reikšmė null parenka rezervuotosios vietos numatytąją reikšmę. Sujungtas objektas taip pat turi tilpti į 32 KB. Išsaugoto agento atsakymai priima tik agent_id, variables, context, language ir kiekvienam skambučiui skirtą timezone; grąžinkite įterptąją konfigūraciją, kai reikia pakeisti raginimą ar kitus nustatymus. Išsaugoto agento žiniatinklio kabliuko atsakymai naudoja įdiegtą agento A/B paskirstymą tiek telefono, tiek valdiklio skambučiams; kintamieji pateikiami pasirinkus variantą. Kai atsakymas nustato language ne Full duplex agentui, skambutyje taip pat naudojamas tai kalbai nustatytas balsas, jei agentui jis nustatytas. Atsakymas, kuriame yra prompt, visada naudoja įterptąją konfigūraciją: bet koks tame atsakyme esantis agent_id ignoruojamas, įskaitant null arba nesveikųjų skaičių metaduomenis. Įterptasis raginimas vis tiek turi atitikti įprastą tikrinimą. Įterptieji žiniatinklio kabliuko atsakymai taip pat gali apimti variables ir context. context, kuris nėra eilutė arba yra per ilgas, sutrikdo apsikeitimą: telefono skambutis atmetamas, o valdiklio seanso užklausa nepavyksta su 400. Išsaugoto agento žiniatinklio kabliuko atsakymai naudoja įdiegtą agento A/B paskirstymą tiek telefono, tiek valdiklio skambučiams; kintamieji pateikiami pasirinkus variantą. Įeinantiems telefono skambučiams naudokite numerį, kuriam nepriskirtas įeinančių skambučių agentas, ir sukonfigūruokite jo telefono numerio arba organizacijos žiniatinklio kabliuką; valdiklio raktai naudoja mode="webhook". Galinių sistemų gaunami pranešimai nepateikia blokuojančių konfigūracijos atsakymų.

Agento skambučio nustatymo žiniatinklio kabliukas

Kad numeris liktų priskirtas jo agentui ir būtų užpildytos tik skambučio reikšmės, suteikite agentui skambučio nustatymo žiniatinklio kablį. Prieš kiekvieną įeinantį skambutį, į kurį agentas atsako numeriu, žiniatinklio kablys gauna skambutį ir agento ID, pavadinimą bei versiją ir atsako tais pačiais variables, context, language ir konkretaus skambučio timezone, kaip nurodyta pirmiau, nereikalaudamas agent_id. Agentui, kurio nustatymuose naudojamas vietaženklis be numatytosios reikšmės, reikia šio žiniatinklio kablio, kad galėtų atsakyti telefono numeriu: žiniatinklio kabliui nepavykus, skambutis neprasideda. Vietaženkliai su numatytąja reikšme, pvz., {{name|there}}, leidžia agentui atsakyti ir be jo.

SIP antraštės

Skambučiai, pasiekiantys agentą per SIP (per SIP adresą arba numerį naudojant rankinį SIP ryšį), gali perduoti kontekstą X-* ir User-to-User antraštėse. Kiekviena jų tampa sip_ kintamuoju, pvz., {{sip_x_amzn_connectcontactid}} arba {{sip_uui}}, turinčiu mažiausią prioritetą: laimi tos pačios reikšmės pavadinimas iš API arba žiniatinklio kablio. Žr. Skambučio konteksto perdavimas SIP antraštėse. Antraščių reikšmes nustato siuntėjas, todėl laikykite jas nepatikimomis, kaip ir bet kurią naršyklės pateiktą reikšmę.

Valdiklio sesijos API

POST /v1/widget/session priima aukščiausio lygio variables ir language. Jo viešasis raktas parenka išsaugotą agentą. Webhook režimo raktai perduoda šias reikšmes į konfigūracijos webhook ir sujungia atsakymą, kaip aprašyta pirmiau. Naršyklės pateiktos valdiklio variables yra valdomos kliento, po pirmiau aprašyto patvirtinimo ir eilučių išvalymo pažodžiui perduodamos į web.incoming bei pakartojamos užbaigimo webhookuose ir skambučių istorijoje. Nelaikykite jų patikimais tapatybės ar autorizavimo duomenimis.

Paties valdiklio naršyklės context laukas yra kitoks: jame pateikiamas tekstas iš puslapio, kuriame lankytojas yra, ir agentas jį laiko svetainės turiniu (žr. Žiniatinklio valdiklio įterpimas). Valdiklio skambučio vieno skambučio kontekstas, kaip aprašyta pirmiau, gaunamas iš žiniatinklio kabliuko režimo rakto konfigūracijos žiniatinklio kabliuko. Kai skambutis turi abu, pirmiausia pateikiamas vieno skambučio kontekstas, tada puslapio turinys.

Realaus laiko sesijos API

POST /v1/realtime/sessions priima aukščiausio lygmens variables, context ir language kartu su agent_id arba įterptąja config:

{
  "agent_id": 12,
  "variables": {"name": "Ada"},
  "context": "Ada is calling from the front desk about a guest's lost key card."
}

context nurodomas tik aukščiausiame lygmenyje; įterptinė config jį atmeta kaip nežinomą lauką.

Realaus laiko WebSocket

Naudojant išsaugotą agentą, išsaugoto agento įdiegtas raginimas lieka jo raginimu. session.instructions tampa skambučio kontekstu, session.prompt.variables (arba session.config.variables) tampa jo kintamaisiais, o session.language tampa jo kalba konkrečiam skambučiui. Pasirinkite agentą naudodami session.prompt.id pirmame session.update, kuris pradeda sesiją, kai tik gaunamas tas atnaujinimas:

{
  "type": "session.update",
  "session": {
    "type": "realtime",
    "prompt": {"id": "12", "variables": {"name": "Ada"}},
    "instructions": "Ada asked for a callback about her delivery window."
  }
}

?agent_id=12 ryšio URL paleidžia agentą, kai tik užmezgamas lizdo ryšys, prieš bet kokį session.update, todėl jis neturi konkretaus skambučio įvesties. Pridėkite &wait_for_session_update=1, kad palauktumėte pirmo session.update ir naudotumėte jo instrukcijas bei kintamuosius.

Tiesioginiame seanse (be išsaugoto agento) session.instructions yra pati užklausa, kaip ir anksčiau. Kūrimo priemonės mikrofonas ir imituoti bandomieji skambučiai nustato numatytąsias reikšmes bei užpildo trūkstamus vietos rezervavimo ženklus, tačiau neturi konkretaus skambučio kintamųjų ar konteksto įvesties.

Po skambučio

GET /v1/calls, GET /v1/calls/{call_id}, telephony.complete ir web.complete apima galutinius sujungtus variables ir unresolved_variables. Senesnės užbaigimo apkrovos, kuriose yra data.history, taip pat juos apima:

{
  "variables": {"name": "Ada", "account_id": "A-17"},
  "unresolved_variables": ["appointment_slot"]
}

Skambučio prompt_snapshot (GET /v1/calls/{call_id}) rodo agentui skirtą raginimą su užpildytais kintamaisiais ir pridėtu konteksto bloku.

Išsaugokite savo CRM arba užduoties identifikatorių kintamųjų objekte, kad užbaigtą skambutį susietumėte su jo šaltinio įrašu. Kintamieji ir kontekstas saugomi kartu su skambučio įrašu; siųskite tik tokią informaciją, kurią galima saugoti skambučių istorijoje ir žiniatinklio kabliukuose.

Skambučio pakartojimai tikrinimo rinkiniuose, pakartojimų vykdymuose ir tyrimuose naudoja to skambučio kintamuosius ir kontekstą su tikrinamu raginimu, todėl pakartojimas patikrina, ką tam skambučiui skirtam agentui būtų buvę pateikta.

Suderinamumas su esamais raginimais

Atvaizdavimas taip pat taikomas esamiems išsaugoto agento ir A/B varianto raginimams, tiesioginėms siunčiamųjų skambučių ir realiojo laiko konfigūracijoms bei raginimams, grąžinamiems per konfigūracijos žiniatinklio kabliukus. Nežinomos {{name}} vietos žymos tampa tuščiu tekstu, net kai nepateikiama jokių variables. Prieš diegdami patikrinkite esamus raginimus, įskaitant išoriškai pateiktus tiesioginius / žiniatinklio kabliukų raginimus, kurių ThunderPhone negali inventorizuoti. Kūrimo priemonės mikrofono ir simuliacijos skambučiams taikomas toks pat numatytasis / tuščias elgesys.