Open in
Premenné a kontext pre jednotlivé hovory
Poskytnite každému hovoru vlastné údaje ako pomenované premenné pre prompt alebo stručné zadanie vo voľnom formáte bez zmeny agenta.
Každý hovor môže obsahovať dva typy vstupu pre konkrétny hovor. Použite jeden z nich alebo oba spoločne:
variables: pomenované hodnoty, ktoré vyplnia{{placeholders}}v prompte. Použite ich pre polia, na ktoré sa prompt odkazuje podľa názvu, napríklad meno volajúceho, číslo účtu alebo termín stretnutia.context: voľný text pridaný za prompt. Použite ho pre zadanie, ktoré sa nezmestí do šablóny, napríklad opis úlohy pre tento hovor alebo poznámky zhromaždené skôr.
Oba fungujú s uloženým agentom aj s vloženou konfiguráciou pri každom spôsobe spustenia hovoru opísanom nižšie. Ani jeden nemení uloženého agenta, jeho históriu verzií ani ostatné nastavenia.
{
"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."
}Premenné
Do výzvy uloženého agenta vložte zástupné symboly a pri spustení hovoru potom zadajte objekt variables. ThunderPhone vykreslí text pred odoslaním konfigurácie hovoru do hlasového runtime.
Ak nie sú potrebné žiadne hodnoty, variables vynechajte, neposielajte null (odmietnuté s 400).
Zástupné premenné a predvolené hodnoty
You are calling {{name|Friend}} about account {{account_id}}.
The available appointment is {{ appointment_slot }}.Názvy rozlišujú veľkosť písmen a riadia sa vzorom [A-Za-z_][A-Za-z0-9_]*. Medzery okolo
názvu sú povolené; medzery za znakom | sú súčasťou predvolenej hodnoty a
zachovajú sa. {{name|Friend}} použije Friend, keď name chýba alebo má hodnotu
null; prázdny reťazec je explicitne zadaná hodnota. Chýbajúce hodnoty bez
predvolenej hodnoty sa zmenia na prázdne reťazce a ich názvy sa zobrazia v unresolved_variables.
Text medzi dvojitými zloženými zátvorkami, ktorý nie je platným zástupným symbolom, sa odstráni. Text v dvojitých zložených
zátvorkách v každej zadanej hodnote sa odstraňuje nezávisle; hodnota nemôže odstrániť
okolité texty výzvy ani inú hodnotu. Odstránia sa aj nespárované oddeľovače dvojitých zložených zátvoriek.
Príklady JSON vo výzvach nesmú používať {{.
Hodnoty sú obyčajný text a nikdy sa nevyhodnocujú
ako kód ani sa rekurzívne nerozbaľujú ako šablóny.
Premenné sa môžu zobrazovať aj vo výzvach na potvrdenie, v odchádzajúcich hlasových správach
a v texte oznámenia o súhlase, keď sa toto pole odosiela pre
telefónny hovor. Agent nemá samostatné pole first_message: úvodné pokyny vložte do výzvy. Existujúce zástupné symboly hlasovej správy {agent_name} a {org_name}
naďalej fungujú.
Hodnoty a limity
Hodnoty môžu byť reťazce, čísla, booleovské hodnoty alebo null; booleovské hodnoty sa vykresľujú ako true
a false. Riadiace znaky Unicode (Cc) s výnimkou nového riadka (\n), tabulátora (\t)
a návratu vozíka (\r), formátovacie znaky (Cf) s výnimkou spojovníka
a spojovača s nulovou šírkou (U+200C, U+200D, ktoré tvoria slová v jazykoch s indickým
a arabským písmom) a kódové body náhradných znakov (Cs) sa odstránia; \r\n
sa normalizuje na \n. Každá hodnota
je pri vykreslení obmedzená na 2 000 znakov. Dodané reťazce sa pred uložením tiež vyčistia a
skrátiia. Pôvodný objekt musí mať maximálne 32 KB JSON v UTF-8; väčšie objekty dostanú
400 v požiadavkách na hovory alebo relácie, zatiaľ čo importy kampaní nahlásia neplatné riadky samostatne. Polia a vnorené objekty nie sú
ako hodnoty prijímané. Nezhodné kľúče metadát (napríklad hlavička CSV s
medzerou) sa zachovajú a vrátia, ale nemožno na ne odkazovať pomocou zástupného symbolu.
Kontext
context je reťazec s dĺžkou najviac 20 000 znakov. ThunderPhone ho pridá za
prompt po doplnení premenných promptu ako oddelený 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 ho číta spolu so svojimi pokynmi, preto ho napíšte tak, ako by ste
pred hovorom informovali kolegu. Kontext nie je šablóna:
{{name}} v ňom zostane napísané tak, ako je. Ak text potrebuje hodnotu, vložte ju
sami pred odoslaním.
null, prázdny reťazec alebo iba medzery znamenajú, že kontext nie je k dispozícii.- Hodnota, ktorá nie je reťazec alebo je dlhšia než 20 000 znakov, sa pri požiadavkách na hovor a reláciu odmietne s kódom
400; z konfiguračného webhooku zlyhá výmena rovnako ako pri neplatnýchvariables(pozrite nižšie). - Úvodné a koncové medzery sa odstránia a odstránia sa aj rovnaké riadiace a formátovacie znaky ako pri hodnotách premenných.
- Kontext je súčasťou výzvy hovoru, takže sa započítava do veľkosti výzvy.
Pri agentovi s krokmi nasleduje kontext za promptom každého agenta v hovore, nie za pokynmi jednotlivých krokov.
Odkiaľ pochádzajú hodnoty
Odchádzajúce API
Odošlite variables a context v požiadavke 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."
}Obe možnosti fungujú aj s predvoleným odchádzajúcim agentom telefónneho čísla alebo s vloženým config.prompt. Pri vloženej konfigurácii môže byť context aj v rámci config, teda v rovnakom poli, aké vracia konfiguračný webhook; ak odošlete obe, musia obsahovať rovnaký text. Kľúč idempotencie nemožno znovu použiť s odlišnými premennými alebo odlišným kontextom.
CSV kampane
Stĺpce CSV iné než telefónne číslo sa už ukladajú ako premenné kontaktu. Každé volanie ich teraz používa automaticky. Použite hlavičky ako name, account_id a appointment_slot, aby zodpovedali vašim zástupným symbolom. Existujúce mapovanie mena môže skombinovať stĺpce s menom a priezviskom do premennej name. Kontakty kampane nemajú kontext pre jednotlivé kontakty.
Webhook dynamickej konfigurácie
V ceste webhooku blokujúcej konfigurácie vráťte uloženého agenta vo svojej organizácii spolu s ľubovoľnými hodnotami pre konkrétny hovor. Pri agentovi Full duplex si hovor zachová hlas agenta aj vtedy, keď sa začne v inom podporovanom jazyku: mapovania hlasov podľa jazyka a natívne prepínanie hlasov sa na tento hovor nevzťahujú.
{
"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."
}Premenné v odpovedi prepíšu premenné na úrovni požiadavky, ostatné kľúče požiadavky však zostanú zachované. Hodnota odpovede null vyberie predvolenú hodnotu zástupného prvku.
Zlúčený objekt sa tiež musí zmestiť do 32 KB. Odpovede uloženého agenta prijímajú iba
agent_id, variables, context, language a časové pásmo pre jednotlivý hovor
timezone; ak potrebujete
nahradiť výzvu alebo iné nastavenia, vráťte vloženú konfiguráciu. Odpovede webhooku
uloženého agenta používajú nasadené A/B rozdelenie agenta pri telefonických hovoroch aj hovoroch vo widgete;
premenné sa vyhodnotia po výbere variantu. Keď odpoveď nastaví language pre
agenta, ktorý nepoužíva Full duplex, hovor použije aj hlas daného jazyka, ak ho
preň agent má nastavený. Odpoveď obsahujúca prompt vždy používa vloženú
konfiguráciu: každý agent_id v tejto odpovedi sa ignoruje vrátane hodnoty null alebo
neceločíselných metadát. Vložená výzva musí stále prejsť bežnou validáciou.
Vložené odpovede webhooku môžu obsahovať aj variables a context. Hodnota context,
ktorá nie je reťazcom alebo je príliš dlhá, spôsobí zlyhanie výmeny: telefonický hovor sa
odmietne a požiadavka na reláciu widgetu zlyhá s kódom 400. Odpovede webhooku
uloženého agenta používajú nasadené A/B rozdelenie agenta pri telefonických hovoroch aj hovoroch vo widgete;
premenné sa vyhodnotia po výbere variantu. Pri prichádzajúcich telefonických hovoroch použite číslo bez priradeného prichádzajúceho
agenta a nakonfigurujte webhook jeho telefónneho čísla alebo organizácie; kľúče widgetu používajú
mode="webhook". Prichádzajúce oznámenia systému endpointov neposkytujú blokujúce
odpovede konfigurácie.
Webhook nastavenia hovoru agenta
Ak chcete ponechať číslo priradené k hlasovému agentovi a vyplniť iba hodnoty hovoru,
priraďte hlasovému agentovi webhook nastavenia hovoru.
Pred každým prichádzajúcim hovorom, ktorý hlasový agent prijme na čísle, webhook dostane
hovor a ID, názov a verziu hlasového agenta a odpovie rovnakými hodnotami
variables, context, language a časového pásma timezone pre konkrétny hovor ako vyššie, bez potreby agent_id. Hlasový agent,
ktorého nastavenia používajú zástupný symbol bez predvolenej hodnoty, potrebuje tento webhook na prijatie
hovoru na telefónne číslo: ak webhook zlyhá, hovor sa nezačne. Zástupné symboly s predvolenou hodnotou,
napríklad {{name|there}}, umožňujú hlasovému agentovi prijať hovor aj bez neho.
Hlavičky SIP
Hovory, ktoré sa k agentovi dostanú cez SIP (na adrese SIP alebo
na čísle pri manuálnom pripojení SIP), môžu prenášať kontext v hlavičkách X-* a
User-to-User. Každá z nich sa zmení na premennú sip_, napríklad
{{sip_x_amzn_connectcontactid}} alebo {{sip_uui}}, s najnižšou
prioritou: prednosť má hodnota s rovnakým názvom z API alebo webhooku. Pozrite si
Odovzdanie kontextu hovoru v hlavičkách SIP.
Hodnoty hlavičiek nastavuje odosielateľ, preto ich považujte za nedôveryhodné, rovnako ako každú
hodnotu poskytnutú prehliadačom.
API relácie widgetu
POST /v1/widget/session prijíma variables a language na najvyššej úrovni. Jeho publikovateľný
kľúč vyberá uloženého agenta. Kľúče v režime webhooku posielajú tieto hodnoty do
konfiguračného webhooku a zlúčia odpoveď podľa vyššie uvedeného popisu.
variables widgetu dodané prehliadačom riadi klient, po overení a vyčistení reťazcov opísaných
vyššie sa doslovne posielajú ďalej v web.incoming a odrážajú sa vo webhookoch po dokončení
a v histórii hovorov. Nepovažujte ich za dôveryhodné údaje o identite ani autorizácii.
Vlastné pole context widgetu v prehliadači je odlišné: prenáša text zo
stránky, na ktorej sa návštevník nachádza a ktorý agent považuje za obsah webovej stránky (pozrite
Vloženie webového widgetu). Kontext widgetového hovoru pre konkrétny hovor
pochádza z konfiguračného webhooku kľúča v režime webhooku, ako je uvedené vyššie. Ak má
hovor oboje, najprv sa použije kontext pre konkrétny hovor a potom obsah stránky.
API relácie v reálnom čase
POST /v1/realtime/sessions prijíma variables, context a language na najvyššej úrovni spolu s agent_id alebo vloženou konfiguráciou config:
{
"agent_id": 12,
"variables": {"name": "Ada"},
"context": "Ada is calling from the front desk about a guest's lost key card."
}context patrí iba na najvyššiu úroveň; vložený config ho odmietne ako
neznáme pole.
Realtime WebSocket
Pri uloženom agentovi zostáva nasadený prompt uloženého agenta jeho promptom.
session.instructions sa stáva kontextom hovoru, session.prompt.variables
(alebo session.config.variables) sa stávajú jeho premennými a session.language
sa stáva jeho jazykom pre daný hovor. Agenta vyberte pomocou
session.prompt.id v prvej aktualizácii session.update, ktorá spustí reláciu po
doručení tejto aktualizácie:
{
"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 adrese URL pripojenia spustí agenta hneď po pripojení socketu,
pred akýmkoľvek session.update, takže neprenáša žiadne vstupy pre konkrétny hovor. Pridajte
&wait_for_session_update=1, aby sa počkalo na prvú správu session.update a použili sa jej
inštrukcie a premenné.
V inline relácii (bez uloženého agenta) je session.instructions samotný prompt,
rovnako ako predtým. Testovacie hovory cez mikrofón v nástroji Builder a simulované hovory vyriešia predvolené hodnoty a
chýbajúce zástupné symboly, no nemajú premenné ani vstup kontextu pre konkrétny hovor.
Po hovore
GET /v1/calls, GET /v1/calls/{call_id}, telephony.complete a web.complete obsahujú
konečné zlúčené variables a unresolved_variables. Staršie dátové štruktúry dokončenia,
ktoré obsahujú data.history, ich obsahujú tiež:
{
"variables": {"name": "Ada", "account_id": "A-17"},
"unresolved_variables": ["appointment_slot"]
}prompt_snapshot hovoru (GET /v1/calls/{call_id}) zobrazuje výzvu agenta
s vyplnenými premennými a pridaným blokom kontextu.
Uložte identifikátor CRM alebo úlohy do objektu premenných, aby ste dokončený hovor prepojili späť so zdrojovým záznamom. Premenné a kontext sa uchovávajú so záznamom hovoru; odosielajte iba informácie, ktoré je vhodné uchovávať v histórii hovorov a webhookoch.
Prehrania hovoru v validačných sadách, spusteniach prehrávania a vyšetrovaniach používajú premenné a kontext daného hovoru spolu s testovanou výzvou, takže prehranie testuje, čo by bolo agentovi v danom hovore povedané.
Kompatibilita existujúcich promptov
Vykresľovanie sa vzťahuje aj na existujúce prompty uložených agentov a variantov A/B, vložené odchádzajúce konfigurácie a konfigurácie v reálnom čase, ako aj na prompty vrátené konfiguračnými webhookmi. Neznáme zástupné symboly {{name}} sa zmenia na prázdny text, aj keď nie sú poskytnuté žiadne variables. Pred nasadením skontrolujte existujúce prompty vrátane externe dodávaných vložených promptov a promptov webhookov, ktoré ThunderPhone nedokáže evidovať. Volania mikrofónu v nástroji Builder a simulačné volania používajú rovnaké predvolené správanie so zadanou hodnotou alebo prázdnym textom.