Open in
Varijable i kontekst po pozivu
Svakom pozivu dodijelite vlastite pojedinosti, kao imenovane varijable za upit ili slobodno oblikovani sažetak, bez promjene agenta.
Svaki poziv može sadržavati dvije vrste unosa po pozivu. Upotrijebite jednu ili obje zajedno:
variables: imenovane vrijednosti koje popunjavaju{{placeholders}}u promptu. Upotrijebite ih za polja na koja se prompt poziva imenom, kao što su ime pozivatelja, broj računa ili termin sastanka.context: tekst slobodnog oblika dodan nakon prompta. Upotrijebite ga za sažetak koji ne odgovara predlošku, kao što je opis zadatka za ovaj poziv ili ranije prikupljene bilješke.
Oboje funkcionira sa spremljenim agentom i s umetnutom konfiguracijom, pri svakom načinu pokretanja poziva opisanom u nastavku. Nijedno ne mijenja spremljenog agenta, njegovu povijest verzija ni ostale postavke.
{
"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."
}Varijable
Postavite rezervirana mjesta u prompt spremljenog agenta, a zatim pri pokretanju poziva navedite objekt variables. ThunderPhone prikazuje tekst prije slanja konfiguracije poziva u glasovno izvođenje.
Kada vrijednosti nisu potrebne, izostavite variables; nemojte slati null (odbijeno s 400).
Rezervirana mjesta i zadane vrijednosti
You are calling {{name|Friend}} about account {{account_id}}.
The available appointment is {{ appointment_slot }}.Nazivi razlikuju velika i mala slova te slijede obrazac [A-Za-z_][A-Za-z0-9_]*. Razmaci oko
naziva su dopušteni; razmak nakon znaka | dio je zadane vrijednosti i
zadržava se. {{name|Friend}} koristi Friend kada name nedostaje ili je
null; prazan niz izričito je navedena vrijednost. Nedostajuće vrijednosti bez
zadane vrijednosti postaju prazni nizovi, a njihovi se nazivi prikazuju u unresolved_variables.
Tekst između dvostrukih vitičastih zagrada koji nije valjano rezervirano mjesto uklanja se. Tekst u dvostrukim vitičastim
zagradama unutar svake navedene vrijednosti uklanja se neovisno; vrijednost ne može ukloniti
okolni tekst prompta ni drugu vrijednost. Uklanjaju se i neupareni razdjelnici s dvostrukim vitičastim zagradama.
Primjeri JSON-a u promptovima ne smiju koristiti {{.
Vrijednosti su običan tekst, nikada se ne izvršavaju
kao kod niti se rekurzivno proširuju kao predlošci.
Varijable se mogu pojaviti i u promptovima za potvrdu, odlaznim porukama govorne pošte
te tekstu obavijesti o pristanku kada se to polje šalje za
telefonski poziv. Agent nema zasebno polje first_message: njegove uvodne
upute stavite u prompt. Postojeća rezervirana mjesta govorne pošte {agent_name} i {org_name}
nastavljaju raditi.
Vrijednosti i ograničenja
Vrijednosti mogu biti nizovi znakova, brojevi, Booleove vrijednosti ili null; Booleove vrijednosti prikazuju se kao true
i false. Upravljački znakovi Unicodea (Cc), osim novog retka (\n), tabulatora (\t)
i povrata retka (\r), znaci oblikovanja (Cf), osim spojnika i nespojnika nulte širine
(U+200C, U+200D, koji tvore riječi u indijskim jezicima i jezicima koji koriste
arapsko pismo), te kodne točke zamjenskog područja (Cs) uklanjaju se; \r\n
normalizira se u \n. Svaka je vrijednost
ograničena na 2.000 znakova pri prikazu. Dostavljeni nizovi znakova također se čiste i
skraćuju prije pohrane. Izvorni objekt mora stati u 32 KB UTF-8 JSON-a; veći
objekti dobivaju 400 u zahtjevima za poziv/sesiju, dok uvozi kampanja pojedinačno prijavljuju
neispravne retke. Nizovi i ugniježđeni objekti nisu
prihvaćeni kao vrijednosti. Metapodaci s ključevima koji ne odgovaraju (primjerice zaglavlje CSV-a s
razmakom) zadržavaju se i vraćaju, ali se ne mogu referencirati zamjenskim mjestom.
Kontekst
context je niz znakova do 20.000 znakova. ThunderPhone ga dodaje nakon
uputa, kada se popune varijable uputa, kao omeđeni 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 čita zajedno sa svojim uputama, stoga ga napišite onako kako biste
prije poziva informirali kolegu. Kontekst nije predložak:
{{name}} unutar njega ostaje kako je napisano. Ako tekst treba vrijednost, sami je unesite
prije slanja.
null, prazan niz ili samo razmaci znače da nema konteksta.- Vrijednost koja nije niz ili je dulja od 20.000 znakova odbija se s kodom
400u zahtjevima za pozive i sesije; iz konfiguracijskog webhooka razmjena ne uspijeva kao i kod nevaljanogvariables(pogledajte u nastavku). - Uklanjaju se početni i završni razmaci te isti kontrolni i oblikovni znakovi kao i u vrijednostima varijabli.
- Kontekst je dio prompta poziva, stoga se uračunava u veličinu prompta.
Kod agenta s koracima, kontekst slijedi nakon uputa svakog agenta u pozivu, a ne nakon uputa svakog koraka.
Odakle dolaze vrijednosti
Izlazni API
Pošaljite variables i context u zahtjevu 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 funkcionira i sa zadanim odlaznim agentom glasovnog broja ili s umetnutim
config.prompt. S umetnutom konfiguracijom, context može biti i unutar config,
što je isto polje koje vraća webhook za konfiguraciju; ako pošaljete oboje, moraju
sadržavati isti tekst. Ključ idempotentnosti ne može se ponovno upotrijebiti s različitim varijablama ili
drukčijim kontekstom.
CSV kampanje
CSV stupci koji nisu telefonski već su pohranjeni kao varijable kontakta. Svako biranje sada ih automatski koristi. Upotrijebite zaglavlja kao što su name, account_id i appointment_slot kako bi odgovarala vašim rezerviranim mjestima. Postojeće mapiranje imena može kombinirati stupce imena i prezimena u varijablu name. Kontakti kampanje nemaju kontekst po kontaktu.
Webhook za dinamičku konfiguraciju
Na putanji blokirajućeg webhooka za konfiguraciju vratite spremljenog agenta u svojoj organizaciji zajedno sa svim vrijednostima po pozivu. Za agenta Full duplex poziv zadržava glas agenta čak i kada započne na drugom podržanom jeziku: mapiranja glasova po jeziku i izvorno prebacivanje glasova ne primjenjuju se na taj poziv.
{
"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."
}Varijable odgovora prepisuju varijable na razini zahtjeva, dok ostali ključevi
zahtjeva ostaju. Vrijednost odgovora null odabire zadanu vrijednost rezerviranog mjesta.
Spojeni objekt također mora stati u 32 KB. Odgovori spremljenog agenta prihvaćaju samo
agent_id, variables, context, language i vremensku zonu po pozivu
timezone; vratite umetnutu konfiguraciju kada trebate
zamijeniti prompt ili druge postavke. Webhook odgovori spremljenog agenta
upotrebljavaju implementiranu A/B podjelu agenta i za telefonske pozive i za pozive putem widgeta;
varijable se prikazuju nakon odabira varijante. Kada odgovor postavi language za
agenta koji nije Full duplex, poziv također koristi vlastiti glas tog jezika ako
agent ima postavljen glas za taj jezik. Odgovor koji sadrži prompt uvijek upotrebljava umetnutu
konfiguraciju: svaki agent_id u tom odgovoru zanemaruje se, uključujući null ili
metapodatke koji nisu cijeli broj. Umetnuti prompt i dalje mora proći uobičajenu provjeru valjanosti.
Umetnuti webhook odgovori također mogu sadržavati variables i context. context
koji nije niz znakova ili je predugačak uzrokuje neuspjeh razmjene: telefonski poziv se
odbija, a zahtjev za sesiju widgeta ne uspijeva s 400. Webhook odgovori spremljenog agenta
upotrebljavaju implementiranu A/B podjelu agenta i za telefonske pozive i za pozive putem widgeta;
varijable se prikazuju nakon odabira varijante. Za dolazne telefonske pozive upotrijebite broj bez dodijeljenog dolaznog
agenta i konfigurirajte webhook njegova telefonskog broja ili organizacije; ključevi widgeta upotrebljavaju
mode="webhook". Dolazne obavijesti sustava krajnjih točaka ne pružaju blokirajuće
konfiguracijske odgovore.
Webhook za postavljanje poziva agenta
Kako bi broj ostao dodijeljen svojem agentu i kako biste popunili samo vrijednosti poziva, agentu dodajte webhook za postavljanje poziva.
Prije svakog dolaznog poziva na broj na koji se agent javlja, webhook prima poziv te ID, naziv i verziju agenta, a odgovara istim vrijednostima variables, context, language i timezone za pojedini poziv kao gore, bez potrebe za agent_id. Agent
čije postavke koriste rezervirano mjesto bez zadane vrijednosti treba ovaj webhook kako bi se javio na telefonski broj: poziv se ne pokreće kada webhook ne uspije. Rezervirana mjesta sa zadanom vrijednošću, poput {{name|there}}, omogućuju agentu da se javi bez njega.
SIP zaglavlja
Pozivi koji dođu do agenta putem SIP-a (SIP adresa ili
broj na ručnoj SIP vezi) mogu prenositi kontekst u zaglavljima X-* i
User-to-User. Svako od njih postaje varijabla sip_, kao što su
{{sip_x_amzn_connectcontactid}} ili {{sip_uui}}, s najnižim
prioritetom: prednost ima vrijednost istog naziva iz API-ja ili webhooka. Pogledajte
Prosljeđivanje konteksta poziva u SIP zaglavljima.
Vrijednosti zaglavlja postavlja pošiljatelj, stoga ih tretirajte kao nepouzdane, kao i svaku
vrijednost koju dostavlja preglednik.
API sesije widgeta
POST /v1/widget/session prihvaća variables i language na najvišoj razini. Njegov javni
ključ odabire spremljenog agenta. Ključevi u načinu rada webhooka prosljeđuju te vrijednosti
webhooku za konfiguraciju i spajaju odgovor kako je gore opisano.
variables widgeta koje isporučuje preglednik pod kontrolom su klijenta, prosljeđuju se
doslovno u web.incoming nakon gore opisane provjere i čišćenja nizova
te se vraćaju u webhookovima dovršetka i povijesti poziva. Nemojte ih tretirati
kao pouzdane podatke za identitet ili autorizaciju.
Vlastito polje preglednika context widgeta razlikuje se: prenosi tekst sa
stranice na kojoj se posjetitelj nalazi, koji agent tretira kao sadržaj web-mjesta (pogledajte
Ugradite web-widget). Kontekst po pozivu za poziv widgeta dolazi
iz webhooka konfiguracije ključa u načinu rada webhooka, kao gore. Kada
poziv ima oba, kontekst po pozivu dolazi prvi, a zatim sadržaj stranice.
API sesije u stvarnom vremenu
POST /v1/realtime/sessions prihvaća variables, context i language na najvišoj razini
uz agent_id ili ugrađeni config:
{
"agent_id": 12,
"variables": {"name": "Ada"},
"context": "Ada is calling from the front desk about a guest's lost key card."
}context se navodi samo na najvišoj razini; ugrađeni config odbija ga kao
nepoznato polje.
Realtime WebSocket
Sa spremljenim agentom, implementirani prompt spremljenog agenta ostaje njegov prompt.
session.instructions postaje kontekst poziva, session.prompt.variables
(ili session.config.variables) postaju njegove varijable, a session.language
postaje jezik za taj poziv. Odaberite agenta pomoću
session.prompt.id u prvom session.update, koji pokreće sesiju čim
to ažuriranje stigne:
{
"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 u URL-u veze pokreće agenta čim se socket poveže, prije bilo
kojeg session.update, pa nema ulaz po pozivu. Dodajte
&wait_for_session_update=1 za čekanje prvog session.update i korištenje
njegovih uputa i varijabli.
U umetnutoj sesiji (bez spremljenog agenta), session.instructions je sam
upit, kao i prije. Pozivi za testiranje mikrofona u alatu Builder i simulirani
testni pozivi razrješavaju zadane vrijednosti i nedostajuće rezervirana mjesta,
ali nemaju varijable ni ulaz konteksta po pozivu.
Nakon poziva
GET /v1/calls, GET /v1/calls/{call_id}, telephony.complete i web.complete uključuju
konačne spojene variables i unresolved_variables. Naslijeđeni tereti dovršetka
koji uključuju data.history također ih uključuju:
{
"variables": {"name": "Ada", "account_id": "A-17"},
"unresolved_variables": ["appointment_slot"]
}prompt_snapshot poziva (GET /v1/calls/{call_id}) prikazuje upit agenta s
popunjenim varijablama i dodanim blokom konteksta.
Spremite svoj CRM ili identifikator zadatka u objekt varijabli da biste dovršeni poziv povezali s izvornim zapisom. Varijable i kontekst čuvaju se uz zapis poziva; šaljite samo informacije koje je primjereno zadržati u povijesti poziva i webhookovima.
Reprize poziva, u skupovima za provjeru, izvršavanjima repriza i istragama, koriste varijable i kontekst tog poziva s upitom koji se testira, pa repriza testira ono što bi agentu u tom pozivu bilo rečeno.
Kompatibilnost s postojećim upitima
Renderiranje se primjenjuje i na postojeće upite spremljenih agenata i A/B varijanti, ugrađene
izlazne konfiguracije i konfiguracije u stvarnom vremenu te upite vraćene putem konfiguracijskih
webhookova. Nepoznati rezervirani dijelovi {{name}} postaju prazan tekst, čak i kada nisu
navedene varijable variables. Provjerite postojeće upite prije uvođenja, uključujući
ugrađene upite i upite webhookova dostavljene iz vanjskih izvora koje ThunderPhone ne može evidentirati.
Pozivi mikrofona u alatu Builder i simulacijski pozivi primjenjuju isto zadano ponašanje za prazne vrijednosti.