Open in
Spremenljivke in kontekst za posamezen klic
Vsakemu klicu dodajte lastne podrobnosti kot poimenovane spremenljivke za poziv ali kratko besedilo proste oblike, ne da bi spremenili agenta.
Vsak klic lahko vsebuje dve vrsti vnosa za posamezen klic. Uporabite eno ali obe skupaj:
variables: poimenovane vrednosti, ki v pozivu izpolnijo{{placeholders}}. Uporabite jih za polja, na katera se poziv sklicuje po imenu, na primer ime klicatelja, številko računa ali termin sestanka.context: besedilo proste oblike, dodano za pozivom. Uporabite ga za povzetek, ki ne ustreza predlogi, na primer opis naloge za ta klic ali prej zbrane opombe.
Obe možnosti delujeta s shranjenim agentom in z vstavljeno konfiguracijo pri vseh spodaj opisanih načinih za začetek klica. Nobena ne spremeni shranjenega agenta, njegove zgodovine različic ali drugih nastavitev.
{
"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."
}Spremenljivke
V poziv shranjenega agenta vstavite označbe mest, nato pa ob začetku klica posredujte objekt variables. ThunderPhone besedilo upodobi, preden konfiguracijo klica pošlje v izvajalno okolje glasovnega agenta.
Kadar vrednosti niso potrebne, variables izpustite in ne pošiljajte null (zahteva je zavrnjena s 400).
Nadomestne spremenljivke in privzete vrednosti
You are calling {{name|Friend}} about account {{account_id}}.
The available appointment is {{ appointment_slot }}.Imena razlikujejo med velikimi in malimi črkami ter sledijo vzorcu [A-Za-z_][A-Za-z0-9_]*. Presledki okoli
imena so dovoljeni; presledki za | so del privzete vrednosti in se
ohranijo. {{name|Friend}} uporabi Friend, kadar name manjka ali je
null; prazen niz je izrecno posredovana vrednost. Manjkajoče vrednosti brez
privzete vrednosti postanejo prazni nizi, njihova imena pa se prikažejo v unresolved_variables.
Besedilo med dvojnimi zavitimi oklepaji, ki ni veljavna ograda, se odstrani. Besedilo v dvojnih zavitih
oklepajih znotraj posamezne posredovane vrednosti se odstrani neodvisno; vrednost ne more odstraniti
okoliškega besedila poziva ali druge vrednosti. Odstranijo se tudi neusklajeni ločilniki z dvojnimi zavitimi oklepaji.
Primeri JSON v pozivih ne smejo uporabljati {{.
Vrednosti so navadno besedilo in se nikoli ne ovrednotijo
kot koda ali rekurzivno razširijo kot predloge.
Spremenljivke se lahko pojavijo tudi v pozivih za potrditev, odhodnih glasovnih sporočilih
in besedilu obvestila o soglasju, kadar je to polje poslano za
telefonski klic. Agent nima ločenega polja first_message: uvodna
navodila dodajte v poziv. Obstoječi ogradi za glasovno pošto {agent_name} in {org_name}
še naprej delujeta.
Vrednosti in omejitve
Vrednosti so lahko nizi, števila, logične vrednosti ali null; logične vrednosti se izpišejo kot true
in false. Nadzorni znaki Unicode (Cc) razen nove vrstice (\n), tabulatorja (\t)
in povratka nosilca (\r), znaki oblikovanja (Cf) razen ničširinskega
nezdruževalnika in združevalnika (U+200C, U+200D, ki zapisujeta besede v indijskih
jezikih in jezikih z arabsko pisavo) ter kodne točke nadomestkov (Cs) so odstranjeni; \r\n
se normalizira v \n. Vsaka vrednost
je ob izpisu omejena na 2.000 znakov. Posredovani nizi se pred shranjevanjem prav tako očistijo in
okrajšajo. Izvirni objekt mora ustrezati omejitvi 32 KB JSON-a UTF-8; večji objekti prejmejo 400
pri zahtevah za klic/sejo, medtem ko uvozi kampanj posamezno poročajo o neveljavnih vrsticah. Polja in ugnezdeni objekti niso
sprejeti kot vrednosti. Metapodatkovni ključi, ki ne ustrezajo zahtevam (na primer glava CSV s
presledkom), se ohranijo in vrnejo, vendar jih ni mogoče uporabiti v nadomestnem označevalniku.
Kontekst
context je niz z največ 20.000 znaki. ThunderPhone ga doda za
poziv, ko so spremenljivke poziva zapolnjene, kot razmejen 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>Agent ga prebere skupaj z navodili, zato ga napišite tako, kot bi pred klicem
poučili sodelavca. Kontekst ni predloga:
{{name}} v njem ostane zapisan tako, kot je. Če besedilo potrebuje vrednost, jo
vstavite sami pred pošiljanjem.
null, prazen niz ali samo presledki pomenijo, da ni konteksta.- Vrednost, ki ni niz ali je daljša od 20.000 znakov, je pri zahtevah za klic in sejo zavrnjena s kodo
400; iz konfiguracijskega webhooka izmenjava ne uspe enako kot pri neveljavnihvariables(glejte spodaj). - Vodilni in končni presledki so odstranjeni, prav tako pa so odstranjeni enaki nadzorni in oblikovni znaki kot pri vrednostih spremenljivk.
- Kontekst je del poziva klica, zato se všteva v velikost poziva klica.
Pri agentu s koraki kontekst sledi pozivu vsakega agenta v klicu, ne navodilom posameznega koraka.
Od kod prihajajo vrednosti
Odhodni API
Pošljite variables in context v 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."
}Oboje deluje tudi s privzetim odhodnim agentom telefonske številke ali z vdelanim
config.prompt. Pri vdelani konfiguraciji je lahko context tudi znotraj config,
v istem polju, ki ga vrne konfiguracijski webhook; če pošljete oboje, mora biti
besedilo enako. Ključa za idempotentnost ni mogoče znova uporabiti z drugačnimi spremenljivkami ali drugačnim kontekstom.
CSV kampanje
Stolpci CSV, ki niso telefonske številke, so že shranjeni kot spremenljivke stika. Vsako klicanje jih zdaj uporablja samodejno. Za ujemanje z vašimi ogradami uporabite glave, kot so name, account_id in appointment_slot. Obstoječe preslikavanje imen lahko združi stolpca z imenom in priimkom v spremenljivko name. Stiki v kampanji nimajo konteksta za posamezen stik.
Spletni kavelj za dinamično konfiguracijo
Na poti blokirajočega webhooka za konfiguracijo vrnite shranjenega agenta v svoji organizaciji skupaj z vsemi vrednostmi za posamezen klic. Pri agentu Full duplex klic ohrani glas agenta tudi, če se začne v drugem podprtem jeziku: preslikave glasov po jezikih in izvorno preklapljanje glasov se za ta klic ne uporabljajo.
{
"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."
}Spremenljivke iz odgovora prepišejo spremenljivke na ravni zahteve, drugi ključi
zahteve pa ostanejo. Vrednost null v odgovoru izbere privzeto vrednost nadomestnega mesta.
Tudi združeni objekt mora biti velik največ 32 KB. Odgovori shranjenega agenta sprejemajo le
agent_id, variables, context, language in časovni pas za posamezen klic
timezone; kadar morate
zamenjati poziv ali druge nastavitve, vrnite vdelano konfiguracijo. Odgovori webhooka
shranjenega agenta uporabljajo uvedeno razdelitev A/B agenta za klice prek telefona in pripomočka;
spremenljivke se izrišejo po izbiri različice. Ko odgovor nastavi language za
agenta, ki ni Full duplex, klic uporabi tudi lasten glas tega jezika, če ga
ima agent nastavljenega zanj. Odgovor, ki vsebuje prompt, vedno uporablja vdelano
konfiguracijo: vsak agent_id v tem odgovoru se prezre, vključno z metapodatki null ali
necelimi števili. Vdelani poziv mora še vedno uspešno prestati običajno preverjanje veljavnosti.
Vdelani odgovori webhooka lahko vključujejo tudi variables in context. context,
ki ni niz ali je predolg, povzroči neuspeh izmenjave: telefonski klic je
zavrnjen, zahteva za sejo pripomočka pa ne uspe s kodo 400. Odgovori webhooka
shranjenega agenta uporabljajo uvedeno razdelitev A/B agenta za klice prek telefona in pripomočka;
spremenljivke se izrišejo po izbiri različice. Pri dohodnih telefonskih klicih uporabite številko brez dodeljenega dohodnega
agenta in konfigurirajte webhook telefonske številke ali organizacije; ključi pripomočka uporabljajo
mode="webhook". Dohodna obvestila sistema končnih točk ne zagotavljajo blokirajočih
konfiguracijskih odgovorov.
Spletna kljuka za nastavitev klica agenta
Če želite številko ohraniti dodeljeno njenemu agentu in izpolniti samo vrednosti klica, agentu dodajte spletni kavelj za nastavitev klica.
Pred vsakim dohodnim klicem, na katerega agent odgovori na številki, spletni kavelj prejme klic ter ID, ime in različico agenta ter odgovori z enakimi vrednostmi variables, context, language in timezone za posamezen klic kot zgoraj, ne da bi potreboval agent_id. Agent, katerega nastavitve uporabljajo ogrado brez privzete vrednosti, potrebuje ta spletni kavelj za odgovor na telefonsko številko: klic se ne začne, če spletni kavelj ne uspe. Ograde s privzeto vrednostjo, kot je {{name|there}}, agentu omogočajo odgovor tudi brez njega.
Glave SIP
Klici, ki dosežejo agenta prek SIP (prek naslova SIP ali
številke pri ročni povezavi SIP), lahko nosijo kontekst v glavah X-* in
User-to-User. Vsaka postane spremenljivka sip_, kot sta
{{sip_x_amzn_connectcontactid}} ali {{sip_uui}}, z najnižjo
prednostjo: vrednost z enakim imenom iz API-ja ali webhooka ima prednost. Oglejte si
Posredovanje konteksta klica v glavah SIP.
Vrednosti glav nastavi pošiljatelj, zato jih obravnavajte kot nezaupanja vredne,
tako kot katero koli vrednost, ki jo posreduje brskalnik.
API seje pripomočka
POST /v1/widget/session sprejema variables in language na najvišji ravni. Njegov objavljivi
ključ izbere shranjenega agenta. Ključi v načinu webhook te vrednosti posredujejo
konfiguracijskemu webhooku in odgovor združijo, kot je opisano zgoraj.
variables gradnika, ki jih posreduje brskalnik, nadzoruje odjemalec in se
dobesedno posredujejo v web.incoming po zgoraj opisanem preverjanju in
čiščenju nizov ter odražajo v webhookih ob zaključku in zgodovini klicev. Ne obravnavajte jih
kot zaupanja vredne podatke za identifikacijo ali avtorizacijo.
Lastno polje context pripomočka v brskalniku je drugačno: prenaša besedilo s
strani, ki jo obiskovalec gleda in ki jo agent obravnava kot vsebino spletnega mesta (glejte
Vdelajte spletni pripomoček). Kontekst posameznega klica pripomočka
prihaja iz konfiguracijskega spletnega kavlja ključa v načinu spletnega kavlja, kot je opisano zgoraj. Kadar ima
klic oba, je najprej kontekst posameznega klica, nato vsebina strani.
API seje v realnem času
POST /v1/realtime/sessions sprejema variables, context in language na najvišji ravni
skupaj z agent_id ali vdelano konfiguracijo config:
{
"agent_id": 12,
"variables": {"name": "Ada"},
"context": "Ada is calling from the front desk about a guest's lost key card."
}context je dovoljen samo na najvišji ravni; vdelana config ga zavrne kot
neznano polje.
Realtime WebSocket
S shranjenim agentom uvedeni poziv shranjenega agenta ostane njegov poziv.
session.instructions postane kontekst klica, session.prompt.variables
(ali session.config.variables) postanejo njegove spremenljivke, session.language
pa postane jezik posameznega klica. Agenta izberite s
session.prompt.id v prvi posodobitvi session.update, ki zažene sejo, ko
prispe ta posodobitev:
{
"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 v URL-ju povezave zažene agenta takoj, ko se vtičnica
poveže, še pred katerim koli session.update, zato ne vsebuje vnosa za posamezni klic. Dodajte
&wait_for_session_update=1, da počakate na prvi session.update in uporabite njegova
navodila in spremenljivke.
V vdelani seji (brez shranjenega agenta) je session.instructions sam poziv,
kot prej. Klici s mikrofonom v gradniku in simulirani preskusni klici razrešijo privzete vrednosti in
manjkajoče označbe mest, vendar nimajo spremenljivk ali vnosa konteksta za posamezni klic.
Po klicu
GET /v1/calls, GET /v1/calls/{call_id}, telephony.complete in web.complete vključujejo končne
združene variables in unresolved_variables. Podedovane koristne vsebine ob zaključku,
ki vključujejo data.history, jih prav tako vključujejo:
{
"variables": {"name": "Ada", "account_id": "A-17"},
"unresolved_variables": ["appointment_slot"]
}prompt_snapshot klica (GET /v1/calls/{call_id}) prikazuje poziv agenta z
izpolnjenimi spremenljivkami in dodanim blokom konteksta.
Identifikator CRM-ja ali opravila shranite v objekt spremenljivk, da dokončani klic povežete nazaj z izvornim zapisom. Spremenljivke in kontekst se ohranijo z zapisom klica; pošiljajte le informacije, ki jih je primerno hraniti v zgodovini klicev in spletnih kavljih.
Ponovitve klica v naborih za preverjanje, izvajanjih ponovitev in preiskavah uporabljajo spremenljivke in kontekst tega klica s pozivom, ki se preskuša, zato ponovitev preveri, kaj bi bilo agentu v tem klicu sporočeno.
Združljivost z obstoječimi pozivi
Upodabljanje velja tudi za obstoječe pozive shranjenih agentov in različic A/B, vstavljene odhodne konfiguracije in konfiguracije v realnem času ter pozive, vrnjene prek spletnih kljuk konfiguracije. Neznani označevalniki {{name}} postanejo prazno besedilo, tudi če niso navedene nobene spremenljivke variables. Pred uvedbo preverite obstoječe pozive, vključno z zunanje posredovanimi vstavljenimi pozivi in pozivi prek spletnih kljuk, ki jih ThunderPhone ne more evidentirati. Klici z mikrofonom v gradniku in simulacijski klici uporabljajo enako privzeto/prazno vedenje.