Developer cookbook

Premenné pre jednotlivé hovory

Prispôsobte uloženého agenta pre každý hovor bez zmeny jeho nasadeného promptu, nástrojov alebo nastavení.

Vložte zástupné symboly do výzvy uloženého agenta a potom pri začatí hovoru zadajte objekt variables. Uložená konfigurácia a história verzií zostanú nezmenené. 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é symboly 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 môžu byť reťazce, čísla, booleovské hodnoty alebo null; booleovské hodnoty sa vykreslia ako true a false. Riadiace znaky Unicode (Cc) okrem nového riadka (\n), tabulátora (\t) a návratu vozíka (\r), všetky formátovacie znaky (Cf) a kódové body náhradných párov (Cs) sa odstránia; \r\n sa normalizuje na \n. Každá hodnota je pri vykreslení obmedzená na 2 000 znakov. Zadané reťazce sa pred uložením tiež vyčistia a skráti. Pôvodný objekt sa musí zmestiť do 32 KB JSON v UTF-8; väčšie objekty dostanú 400 pri požiadavkách na hovor alebo reláciu, zatiaľ čo importy kampaní nahlásia neplatné riadky jednotlivo. Polia a vnorené objekty sa ako hodnoty neprijímajú. Kľúče metadát, ktoré nezodpovedajú vzoru (napríklad hlavička CSV s medzerou), sa zachovajú a vrátia, ale nie je možné na ne odkazovať zástupným symbolom.

Odkiaľ pochádzajú hodnoty#

Odchádzajúce API#

Odošlite variables spolu s agent_id v požiadavke 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 aj s predvoleným odchádzajúcim agentom telefónneho čísla alebo s vloženým config.prompt. Kľúč idempotentnosti nemožno opätovne použiť s odlišnými premennými.

CSV kampane#

Stĺpce CSV, ktoré neobsahujú telefónne čísla, sú už uložené ako kontaktné premenné. Každé volanie ich teraz používa automaticky. Použite hlavičky, napríklad name, account_id a appointment_slot, aby sa zhodovali s vašimi zástupnými symbolmi. Existujúce mapovanie mena môže skombinovať stĺpce s krstným menom a priezviskom do premennej name.

Webhook dynamickej konfigurácie#

V blokujúcej ceste webhooku konfigurácie vráťte uloženého agenta vo vašej organizácii spolu s ľubovoľnými hodnotami pre konkrétne volanie:

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

Kľúče odpovede prepíšu premenné na úrovni požiadavky, zatiaľ čo ostatné kľúče požiadavky zostanú zachované. Hodnota odpovede null vyberie predvolenú hodnotu zástupného symbolu. Zlúčený objekt sa musí tiež zmestiť do 32 KB. Odpovede uloženého agenta prijímajú iba agent_id a variables; ak potrebujete nahradiť výzvu alebo nastavenia, vráťte vloženú konfiguráciu. Odpoveď obsahujúca prompt vždy používa vloženú konfiguráciu: každé agent_id v tejto odpovedi sa ignoruje vrátane metadát s hodnotou null alebo necelým číslom. Vložená výzva musí aj naďalej prejsť bežnou validáciou. Vložené odpovede webhooku môžu obsahovať aj variables. Odpovede webhooku uloženého agenta používajú nasadené A/B rozdelenie agenta pri telefónnych aj widgetových volaniach; premenné sa vykreslia po výbere variantu. Pri prichádzajúcich telefónnych hovoroch použite číslo bez priradeného prichádzajúceho agenta a nakonfigurujte jeho webhook telefónneho čísla alebo organizácie; kľúče widgetu používajú mode="webhook". Prichádzajúce oznámenia systému koncových bodov neposkytujú blokujúce odpovede konfigurácie.

API relácií widgetu a Realtime#

POST /v1/widget/session prijíma objekt variables na najvyššej úrovni. Jeho publikovateľný kľúč vyberá uloženého agenta. Kľúče v režime webhooku preposielajú tieto hodnoty do webhooku konfigurácie a zlúčia odpoveď podľa vyššie uvedeného popisu. Widgetové/realtime variables dodané prehliadačom riadi klient, po validácii a vyčistení reťazcov opísaných vyššie sa doslovne preposielajú v web.incoming a kopírujú sa do webhookov dokončenia a histórie volaní. Nepovažujte ich za dôveryhodné údaje identity ani autorizácie.

POST /v1/realtime/sessions prijíma variables spolu s agent_id (alebo vloženým config). Ide o polia API na vytvorenie relácie. Most Realtime WebSocket nepreposiela možnosť variables; zadajte ju priamo do API na vytvorenie relácie. Klienti widgetu musia zahrnúť variables do odoslaného údaja relácie; preposielanie cez SDK nie je súčasťou tejto zmeny API. Testovacie hovory mikrofónu v nástroji Builder a simulované testovacie hovory vyriešia predvolené hodnoty a chýbajúce zástupné symboly, ale nemajú vstup pre premenné konkrétneho volania.

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

Uložte identifikátor CRM alebo úlohy do objektu premenných, aby ste dokončený hovor prepojili späť s jeho zdrojovým záznamom. Tieto polia sa uchovávajú so záznamom hovoru; odosielajte iba informácie vhodné na uchovávanie v histórii volaní a webhookoch.

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.