Developer cookbook

Proměnné pro jednotlivé hovory

Přizpůsobte uloženého agenta pro každý hovor, aniž byste změnili jeho nasazený prompt, nástroje nebo nastavení.

Vložte do promptu uloženého agenta zástupné symboly a při zahájení hovoru poté dodejte objekt variables. Uložená konfigurace a historie verzí zůstanou beze změny. ThunderPhone text vykreslí před odesláním konfigurace hovoru do hlasového runtime.

Pokud nejsou potřeba žádné hodnoty, variables vynechejte; neposílejte null (bude odmítnuto s 400).

Zástupné symboly 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 mohou být řetězce, čísla, booleovské hodnoty nebo null; booleovské hodnoty se vykreslí jako true a false. Řídicí znaky Unicode (Cc) kromě nového řádku (\n), tabulátoru (\t) a návratu vozíku (\r), všechny formátovací znaky (Cf) a kódové body náhradních znaků (Cs) se odstraní; \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 se musí vejít do 32 KB JSON v UTF-8; větší objekty obdrží 400 v požadavcích na hovor nebo relaci, zatímco importy kampaní hlásí neplatné řádky jednotlivě. Pole a vnořené objekty nejsou jako hodnoty přijímány. Neshodující se klíče metadat (například záhlaví CSV s mezerou) se zachovají a vrátí, ale nelze na ně odkazovat pomocí zástupného symbolu.

Odkud hodnoty pocházejí#

Odchozí API#

Odešlete variables spolu s agent_id v požadavku POST /v1/call:

{
  "from_number": "+15551234567",
  "to_number": "+14155550199",
  "agent_id": 12,
  "variables": {
    "name": "Ada",
    "account_id": "A-17",
    "appointment_slot": "Tuesday at 10 AM"
  }
}

Funguje to také s výchozím odchozím agentem telefonního čísla nebo s vloženým config.prompt. Klíč idempotence nelze znovu použít s jinými proměnnými.

CSV kampaně#

Sloupce CSV, které neobsahují telefonní čísla, jsou již uloženy jako proměnné kontaktu. Každé vytáčení 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. Existující mapování jména může spojit sloupce se jménem a příjmením do proměnné name.

Webhook dynamické konfigurace#

V blokující cestě webhooku konfigurace vraťte uloženého agenta ve vaší organizaci spolu s hodnotami pro jednotlivé hovory:

{"agent_id": 12, "variables": {"name": "Ada", "account_id": "A-17"}}

Klíče odpovědi přepíší proměnné na úrovni požadavku, zatímco ostatní klíče požadavku zůstanou zachovány. Hodnota odpovědi null 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 a variables; pokud potřebujete nahradit prompt nebo nastavení, vraťte vloženou konfiguraci. Odpověď obsahující prompt vždy používá vloženou konfiguraci: jakýkoli agent_id v této odpovědi je ignorován, včetně metadat null nebo neceločíselných metadat. Vložený prompt musí stále projít běžnou validací. Vložené odpovědi webhooku mohou také obsahovat variables. Odpovědi webhooku uloženého agenta používají nasazené A/B rozdělení agenta pro telefonní hovory i hovory 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 webhook daného telefonního čísla nebo organizace; klíče widgetu používají mode="webhook". Příchozí oznámení systému koncových bodů neposkytují blokující odpovědi konfigurace.

API relací widgetu a Realtime#

POST /v1/widget/session přijímá objekt variables na nejvyšší úrovni. Jeho publikovatelný klíč vybere uloženého agenta. Klíče v režimu webhook předávají tyto hodnoty do webhooku konfigurace a sloučí odpověď, jak je popsáno výše. Widgetové/realtime variables dodané prohlížečem jsou ovládány klientem, jsou předány beze změny v web.incoming po výše popsané validaci a vyčištění řetězců a jsou zopakovány ve webhoocích dokončení a historii hovorů. Nepovažujte je za důvěryhodná data identity nebo autorizace.

POST /v1/realtime/sessions přijímá variables spolu s agent_id (nebo vloženým config). Jde o pole API pro vytvoření relace. Most Realtime WebSocket nepředává možnost proměnných; zadejte ji přímo do API pro vytvoření relace. Klienti widgetu musí zahrnout variables do odesílaného datového obsahu relace; předávání pomocí SDK není součástí této změny API. Hovory z mikrofonu v Builderu a simulované testovací hovory vyhodnocují výchozí hodnoty a chybějící zástupné symboly, ale nemají vstup proměnných pro jednotlivé hovory.

Hodnoty vrácené 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"]
}

Uložte identifikátor CRM nebo úkolu do objektu proměnných, abyste mohli dokončený hovor propojit zpět se zdrojovým záznamem. Tato pole se uchovávají se záznamem hovoru; odesílejte pouze informace vhodné k uchování v historii hovorů a webhookách.

Kompatibilita stávajících promptů#

Vykreslování se vztahuje také na existující prompty uložených agentů a variant A/B, vložené odchozí konfigurace a konfigurace v reálném čase i na prompty vrácené konfiguračními webhooky. Neznámé zástupné symboly {{name}} se změní na prázdný text, i když nejsou dodány žádné variables. Před nasazením zkontrolujte existující prompty, včetně externě dodávaných vložených promptů a promptů webhooků, které ThunderPhone nemůže inventarizovat. Hovory z mikrofonu v nástroji Builder a simulační hovory používají stejné výchozí chování s prázdným textem.