Open in
Proměnné a kontext pro jednotlivé hovory
Přidejte každému hovoru vlastní údaje jako pojmenované proměnné pro prompt nebo volně formulované zadání, aniž byste měnili agenta.
Každý hovor může obsahovat dva druhy vstupu pro konkrétní hovor. Použijte jeden z nich nebo oba současně:
variables: pojmenované hodnoty, které vyplní{{placeholders}}v promptu. Použijte je pro pole, na která se prompt odkazuje názvem, například jméno volajícího, číslo účtu nebo termín schůzky.context: volný text přidaný za prompt. Použijte jej pro stručné zadání, které se nevejde do šablony, například popis úkolu pro tento hovor nebo dříve shromážděné poznámky.
Oba fungují s uloženým agentem i s vloženou konfigurací při každém níže popsaném způsobu zahájení hovoru. Ani jeden nemění uloženého agenta, jeho historii verzí ani jeho další nastavení.
{
"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."
}Proměnné
Do výzvy uloženého agenta vložte zástupné symboly a při zahájení hovoru poté předejte objekt variables. ThunderPhone vykreslí text před odesláním konfigurace hovoru do hlasového modulu.
Pokud nejsou potřeba žádné hodnoty, variables vynechejte; neposílejte null (bude odmítnuto s 400).
Zástupné proměnné a výchozí hodnoty
You are calling {{name|Friend}} about account {{account_id}}.
The available appointment is {{ appointment_slot }}.Názvy rozlišují velikost písmen a řídí se vzorem [A-Za-z_][A-Za-z0-9_]*. Mezery kolem názvu jsou povoleny; mezery za | jsou součástí výchozí hodnoty a zachovají se. {{name|Friend}} použije Friend, pokud name chybí nebo má hodnotu null; prázdný řetězec je výslovně dodaná hodnota. Chybějící hodnoty bez výchozí hodnoty se změní na prázdné řetězce a jejich názvy se zobrazí v unresolved_variables. Text mezi dvojitými složenými závorkami, který není platným zástupným symbolem, se odstraní. Text v dvojitých složených závorkách uvnitř každé dodané hodnoty se odstraňuje nezávisle; hodnota nemůže odstranit okolní text promptu ani jinou hodnotu. Odstraní se také nespárované oddělovače dvojitých složených závorek. Příklady JSON v promptech nesmí používat {{. Hodnoty jsou prostý text, nikdy se nevyhodnocují jako kód ani se rekurzivně nerozbalují jako šablony.
Proměnné se mohou objevit také v promptech potvrzení, odchozích hlasových zprávách a textu oznámení o souhlasu, pokud je toto pole odesláno pro telefonní hovor. Agent nemá samostatné pole first_message: jeho úvodní pokyny vložte do promptu. Stávající zástupné symboly hlasové schránky {agent_name} a {org_name} nadále fungují.
Hodnoty a limity
Hodnoty mohou být řetězce, čísla, booleovské hodnoty nebo null; booleovské hodnoty se vykreslují jako true
a false. Řídicí znaky Unicode (Cc) s výjimkou nového řádku (\n), tabulátoru (\t)
a návratu vozíku (\r), formátovací znaky (Cf) s výjimkou spojovníku bez šířky a spojovače (U+200C, U+200D, které tvoří slova v indických jazycích a jazycích psaných
arabským písmem) a body kódu náhradních znaků (Cs) jsou odstraněny; \r\n
se normalizuje na \n. Každá hodnota
je při vykreslení omezena na 2 000 znaků. Dodané řetězce se před uložením také vyčistí a
zkrátí. Původní objekt musí být v rámci 32 KB JSON v UTF-8; větší objekty obdrží 400
v požadavcích na volání nebo relaci, zatímco importy kampaní jednotlivě hlásí neplatné řádky. Pole a vnořené objekty nejsou
jako hodnoty přijímány. Neodpovídající klíče metadat (například hlavička CSV s
mezerou) jsou zachovány a vráceny, ale nelze na ně odkazovat pomocí zástupného symbolu.
Kontext
context je řetězec o délce až 20 000 znaků. ThunderPhone jej přidá za
prompt poté, co jsou vyplněny proměnné promptu, jako oddělený 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 jej čte společně se svými pokyny, proto jej napište tak, jak byste před
voláním informovali kolegu. Kontext není šablona:
{{name}} v něm zůstává tak, jak je napsáno. Pokud text potřebuje hodnotu, doplňte ji
sami před odesláním.
null, prázdný řetězec nebo pouze bílé znaky znamenají, že není k dispozici žádný kontext.- Hodnota, která není řetězcem nebo je delší než 20 000 znaků, je při požadavcích na volání a relace odmítnuta s kódem
400; z konfiguračního webhooku způsobí selhání výměny stejně jako neplatnévariables(viz níže). - Úvodní a koncové bílé znaky jsou oříznuty a jsou odstraněny stejné řídicí a formátovací znaky jako v hodnotách proměnných.
- Kontext je součástí promptu hovoru, takže se započítává do velikosti promptu.
U agenta s kroky následuje kontext za promptem každého agenta ve volání, nikoli za pokyny jednotlivých kroků.
Odkud hodnoty pocházejí
Odchozí API
Odešlete variables a context v požadavku 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."
}Obojí funguje také s výchozím odchozím agentem telefonního čísla nebo s vloženým
config.prompt. Při použití vložené konfigurace může být context také uvnitř config,
tedy ve stejném poli, které vrací webhook konfigurace; pokud odešlete obojí, musí obsahovat
stejný text. Klíč idempotence nelze znovu použít s jinými proměnnými nebo jiným kontextem.
CSV kampaně
Sloupce CSV jiné než telefonní číslo jsou již uloženy jako proměnné kontaktu. Každé volání je nyní používá automaticky. Použijte záhlaví jako name, account_id a appointment_slot, aby odpovídala vašim zástupným symbolům. Stávající mapování jména může zkombinovat sloupce se jménem a příjmením do proměnné name. Kontakty kampaně nemají kontext pro jednotlivé kontakty.
Webhook dynamické konfigurace
Na blokující cestě webhooku konfigurace vraťte uloženého agenta ve své organizaci spolu s hodnotami pro konkrétní hovor. Pro agenta Full duplex si hovor zachová hlas agenta, i když začne v jiném podporovaném jazyce: mapování hlasů pro jednotlivé jazyky ani nativní přepínání hlasu se pro tento hovor nepoužijí.
{
"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."
}Proměnné v odpovědi přepíšou proměnné na úrovni požadavku, zatímco ostatní klíče požadavku zůstanou zachovány. Hodnota null v odpovědi vybere výchozí hodnotu zástupného symbolu. Sloučený objekt se také musí vejít do 32 KB. Odpovědi uloženého agenta přijímají pouze agent_id, variables, context, language a pro jednotlivý hovor
timezone; pokud potřebujete nahradit výzvu nebo jiná nastavení, vraťte vloženou konfiguraci. Odpovědi webhooku uloženého agenta používají nasazené A/B rozdělení agenta při telefonních hovorech i hovorech z widgetu; proměnné se vykreslí po výběru varianty. Když odpověď nastaví language pro agenta, který nepoužívá Full duplex, hovor použije také vlastní hlas daného jazyka, pokud ho má agent pro tento jazyk nastavený. Odpověď obsahující prompt vždy používá vloženou konfiguraci: jakékoli agent_id v této odpovědi se ignoruje, včetně hodnoty null nebo neceločíselných metadat. Vložená výzva stále musí projít běžnou validací. Vložené odpovědi webhooku mohou také obsahovat variables a context. Hodnota context, která není řetězcem nebo je příliš dlouhá, výměnu neprovede: telefonní hovor bude odmítnut a požadavek na relaci widgetu selže s 400. Odpovědi webhooku uloženého agenta používají nasazené A/B rozdělení agenta při telefonních hovorech i hovorech z widgetu; proměnné se vykreslí po výběru varianty. Pro příchozí telefonní hovory použijte číslo bez přiřazeného příchozího agenta a nakonfigurujte jeho webhook telefonního čísla nebo organizace; klíče widgetu používají mode="webhook". Příchozí oznámení systému endpointů neposkytují blokující konfigurační odpovědi.
Webhook nastavení hovoru agenta
Chcete-li ponechat číslo přiřazené k jeho agentovi a vyplňovat pouze hodnoty hovoru, poskytněte agentovi webhook pro nastavení hovoru.
Před každým příchozím hovorem, který agent přijme na daném čísle, webhook obdrží hovor a ID, název a verzi agenta a odpoví stejnými hodnotami variables, context, language a timezone pro konkrétní hovor jako výše, aniž by vyžadoval agent_id. Agent,
jehož nastavení používá zástupný symbol bez výchozí hodnoty, potřebuje tento webhook, aby mohl přijmout hovor na telefonním čísle: při selhání webhooku se hovor nezahájí. Zástupné symboly s výchozí hodnotou, například {{name|there}}, umožňují agentovi přijmout hovor i bez něj.
Hlavičky SIP
Hovory, které se k agentovi dostanou přes SIP (na SIP adresu nebo
na číslo s ručním připojením SIP), mohou přenášet kontext v hlavičkách X-* a
User-to-User. Každá z nich se stane proměnnou sip_, například
{{sip_x_amzn_connectcontactid}} nebo {{sip_uui}}, s nejnižší
prioritou: hodnota se stejným názvem z API nebo webhooku má přednost. Viz
Předávání kontextu hovoru v hlavičkách SIP.
Hodnoty hlaviček nastavuje odesílatel, proto je považujte za nedůvěryhodné,
stejně jako jakoukoli hodnotu poskytnutou prohlížečem.
API relace widgetu
POST /v1/widget/session přijímá variables a language na nejvyšší úrovni. Jeho klíč určený k publikování
vybírá uloženého agenta. Klíče v režimu webhooku předávají tyto hodnoty do
konfiguračního webhooku a slučují odpověď, jak je popsáno výše.
Hodnoty variables widgetu dodané prohlížečem jsou řízené klientem, po výše
popsaném ověření a vyčištění řetězců jsou doslovně předány v web.incoming
a zopakovány ve webhoocích po dokončení a historii hovorů. Nepovažujte je za
důvěryhodné údaje o identitě ani autorizaci.
Vlastní pole context widgetu v prohlížeči je jiné: přenáší text ze
stránky, na které se návštěvník nachází a který agent považuje za obsah webu (viz
Vložení webového widgetu). Kontext konkrétního volání widgetu
pochází z konfiguračního webhooku klíče v režimu webhooku, jak je uvedeno výše. Pokud má
volání oba, nejprve se použije kontext konkrétního volání a poté obsah stránky.
API relace v reálném čase
POST /v1/realtime/sessions přijímá variables, context a language na nejvyšší úrovni
spolu s agent_id nebo vloženým config:
{
"agent_id": 12,
"variables": {"name": "Ada"},
"context": "Ada is calling from the front desk about a guest's lost key card."
}context patří pouze na nejvyšší úroveň; vložený config jej odmítne jako
neznámé pole.
Realtime WebSocket
U uloženého agenta zůstává nasazený prompt uloženého agenta jeho promptem.
session.instructions se stává kontextem hovoru, session.prompt.variables
(nebo session.config.variables) se stávají jeho proměnnými a session.language
se stává jeho jazykem pro daný hovor. Agenta vyberte pomocí
session.prompt.id v první zprávě session.update, která spustí relaci, jakmile
tato aktualizace dorazí:
{
"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 připojení spustí agenta hned po připojení socketu, ještě
před jakýmkoli session.update, takže neobsahuje žádný vstup pro konkrétní hovor. Přidejte
&wait_for_session_update=1, chcete-li počkat na první session.update a použít jeho
instrukce a proměnné.
V inline relaci (bez uloženého agenta) je session.instructions samotná výzva stejně jako dříve. Testovací hovory v prohlížeči a simulace doplní výchozí hodnoty a chybějící zástupné symboly. Chcete-li testovat s hodnotami, uložte u agenta
ukázku nastavení hovoru a vyberte ji při spuštění testu; hovor proběhne, jako by na něj odpověděl váš webhook pro nastavení hovoru.
Po hovoru
GET /v1/calls, GET /v1/calls/{call_id}, telephony.complete a web.complete obsahují
konečné sloučené variables a unresolved_variables. Starší datové obsahy dokončení,
které obsahují data.history, je obsahují také:
{
"variables": {"name": "Ada", "account_id": "A-17"},
"unresolved_variables": ["appointment_slot"]
}prompt_snapshot hovoru (GET /v1/calls/{call_id}) zobrazuje výzvu agenta
s vyplněnými proměnnými a přidaným blokem kontextu.
Uložte identifikátor CRM nebo úkolu do objektu proměnných, abyste dokončený hovor propojili zpět s jeho zdrojovým záznamem. Proměnné a kontext se uchovávají spolu se záznamem hovoru; odesílejte pouze informace, které je vhodné uchovávat v historii hovorů a webhookech.
Přehrání hovoru v ověřovacích sadách, spuštěních přehrávání a šetřeních používají proměnné a kontext daného hovoru spolu s testovanou výzvou, takže přehrání testuje, co by bylo agentovi při daném hovoru sděleno.
Kompatibilita stávajících promptů
Vykreslování se vztahuje také na stávající prompty uložených agentů a variant A/B, vložené konfigurace odchozích a realtime hovorů a prompty vrácené webhooky konfigurace. Neznámé zástupné symboly {{name}} se změní na prázdný text, i když nejsou zadány žádné variables. Před nasazením zkontrolujte stávající prompty, včetně externě dodávaných vložených promptů a promptů webhooků, které ThunderPhone nemůže inventarizovat. Testovací hovory v prohlížeči a simulace používají stejné výchozí chování s prázdným textem, pokud nevyberete uložený vzorek nastavení hovoru.