Developer cookbook

Spremenljivke za posamezen klic

Prilagodite shranjenega agenta za vsak klic, ne da bi spremenili njegov objavljeni poziv, orodja ali nastavitve.

V poziv shranjenega agenta vstavite ograde, nato pa ob začetku klica posredujte objekt variables. Shranjena konfiguracija in zgodovina različic ostaneta nespremenjeni. ThunderPhone besedilo upodobi, preden pošlje konfiguracijo klica glasovnemu izvajalnemu okolju.

Kadar vrednosti niso potrebne, variables izpustite in ne pošiljajte null (zahteva je zavrnjena s 400).

Ograde in privzete vrednosti#

You are calling {{name|Friend}} about account {{account_id}}.
The available appointment is {{ appointment_slot }}.

Imena razlikujejo med velikimi in malimi črkami ter sledijo vzorcu [A-Za-z_][A-Za-z0-9_]*. Presledki okoli imena so dovoljeni; presledki za | so del privzete vrednosti in se ohranijo. {{name|Friend}} uporabi Friend, kadar name manjka ali je null; prazen niz je izrecno posredovana vrednost. Manjkajoče vrednosti brez privzete vrednosti postanejo prazni nizi, njihova imena pa se prikažejo v unresolved_variables. Besedilo med dvojnimi zavitimi oklepaji, ki ni veljavna ograda, se odstrani. Besedilo v dvojnih zavitih oklepajih znotraj posamezne posredovane vrednosti se odstrani neodvisno; vrednost ne more odstraniti okoliškega besedila poziva ali druge vrednosti. Odstranijo se tudi neusklajeni ločilniki z dvojnimi zavitimi oklepaji. Primeri JSON v pozivih ne smejo uporabljati {{. Vrednosti so navadno besedilo in se nikoli ne ovrednotijo kot koda ali rekurzivno razširijo kot predloge.

Spremenljivke se lahko pojavijo tudi v pozivih za potrditev, odhodnih glasovnih sporočilih in besedilu obvestila o soglasju, kadar je to polje poslano za telefonski klic. Agent nima ločenega polja first_message: uvodna navodila dodajte v poziv. Obstoječi ogradi za glasovno pošto {agent_name} in {org_name} še naprej delujeta.

Vrednosti so lahko nizi, števila, logične vrednosti ali null; logične vrednosti se upodobijo kot true in false. Nadzorni znaki Unicode (Cc) razen nove vrstice (\n), tabulatorja (\t) in vrnitve nosilca (\r), vsi oblikovni znaki (Cf) ter nadomestne (Cs) kodne točke se odstranijo; \r\n se normalizira v \n. Vsaka vrednost je pri upodabljanju omejena na 2.000 znakov. Posredovani nizi se pred shranjevanjem prav tako očistijo in skrajšajo. Izvirni objekt mora biti znotraj 32 KB UTF-8 JSON; večji objekti pri zahtevah za klic/sejo prejmejo 400, medtem ko uvozi kampanj neveljavne vrstice navedejo posamezno. Polja in ugnezdeni objekti niso sprejeti kot vrednosti. Metapodatkovni ključi, ki se ne ujemajo (na primer glava CSV s presledkom), se ohranijo in vrnejo, vendar nanje ni mogoče sklicevati z ogrado.

Od kod prihajajo vrednosti#

Odhodni API#

Pošljite variables skupaj z agent_id v zahtevi 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"
  }
}

Deluje tudi s privzetim odhodnim agentom telefonske številke ali z vgrajenim config.prompt. Ključa idempotentnosti ni mogoče znova uporabiti z različnimi spremenljivkami.

CSV kampanje#

Stolpci CSV, ki niso telefonske številke, so že shranjeni kot spremenljivke stika. Vsako klicanje jih zdaj uporabi samodejno. Uporabite glave, kot so name, account_id in appointment_slot, da se ujemajo z vašimi nadomestnimi oznakami. Obstoječe preslikavanje imena lahko združi stolpca z imenom in priimkom v spremenljivko name.

Spletni kavelj za dinamično konfiguracijo#

Na blokirajoči poti spletnega kavlja za konfiguracijo vrnite shranjenega agenta v vaši organizaciji skupaj z vsemi vrednostmi za posamezen klic:

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

Ključi odgovora prepišejo spremenljivke na ravni zahteve, drugi ključi zahteve pa ostanejo. Vrednost null v odgovoru izbere privzeto vrednost nadomestne oznake. Združeni objekt mora biti prav tako manjši od 32 KB. Odgovori shranjenega agenta sprejemajo le agent_id in variables; vrnite vgrajeno konfiguracijo, kadar morate zamenjati poziv ali nastavitve. Odgovor, ki vsebuje prompt, vedno uporablja vgrajeno konfiguracijo: vsak agent_id v tem odgovoru je prezrt, vključno z ničelnimi ali neceloštevilskimi metapodatki. Vgrajeni poziv mora še vedno prestati običajno preverjanje veljavnosti. Vgrajeni odgovori spletnega kavlja lahko vključujejo tudi variables. Odgovori spletnega kavlja shranjenega agenta uporabljajo agentovo uvedeno razdelitev A/B pri telefonskih klicih in klicih iz gradnika; spremenljivke se izrišejo po izbiri različice. Za dohodne telefonske klice uporabite številko brez dodeljenega dohodnega agenta in konfigurirajte njen spletni kavelj telefonske številke ali organizacije; ključi gradnika uporabljajo mode="webhook". Dohodna obvestila sistema končne točke ne zagotavljajo blokirajočih konfiguracijskih odgovorov.

API-ja seje gradnika in Realtime#

POST /v1/widget/session sprejme objekt variables na najvišji ravni. Njegov objavljivi ključ izbere shranjenega agenta. Ključi v načinu spletnega kavlja posredujejo te vrednosti spletnemu kavlju za konfiguracijo in združijo odgovor, kot je opisano zgoraj. Spremenljivke variables gradnika/realtime, ki jih posreduje brskalnik, nadzoruje odjemalec, se posredujejo dobesedno v web.incoming po zgoraj opisanem preverjanju veljavnosti in čiščenju nizov ter se ponovijo v spletnih kavljih ob zaključku in zgodovini klicev. Ne obravnavajte jih kot zaupanja vrednih podatkov o identiteti ali avtorizaciji.

POST /v1/realtime/sessions sprejme variables skupaj z agent_id (ali vgrajenim config). To so polja API-ja za ustvarjanje seje. Most Realtime WebSocket ne posreduje možnosti spremenljivk; posredujte jih neposredno API-ju za ustvarjanje seje. Odjemalci gradnika morajo vključiti variables v poslano koristno vsebino seje; posredovanje prek SDK ni del te spremembe API-ja. Klici mikrofona v graditelju in simulirani testni klici razrešijo privzete in manjkajoče nadomestne oznake, vendar nimajo vnosa spremenljivk za posamezen klic.

Vrednosti, vrnjene po klicu#

GET /v1/calls, GET /v1/calls/{call_id}, telephony.complete in web.complete vključujejo končne združene variables in unresolved_variables. Podedovane koristne vsebine ob zaključku, ki vključujejo data.history, jih prav tako vključujejo:

{
  "variables": {"name": "Ada", "account_id": "A-17"},
  "unresolved_variables": ["appointment_slot"]
}

V objekt spremenljivk shranite identifikator CRM-ja ali opravila, da dokončani klic povežete nazaj z izvornim zapisom. Ta polja se hranijo skupaj z zapisom klica; pošiljajte le informacije, ki jih je primerno hraniti v zgodovini klicev in spletnih kavljih.

Združljivost z obstoječimi pozivi#

Upodabljanje velja tudi za obstoječe pozive shranjenih agentov in različic A/B, vstavljene odhodne konfiguracije in konfiguracije v realnem času ter pozive, vrnjene prek spletnih kljuk konfiguracije. Neznani označevalniki {{name}} postanejo prazno besedilo, tudi če niso navedene nobene spremenljivke variables. Pred uvedbo preverite obstoječe pozive, vključno z zunanje posredovanimi vstavljenimi pozivi in pozivi prek spletnih kljuk, ki jih ThunderPhone ne more evidentirati. Klici z mikrofonom v gradniku in simulacijski klici uporabljajo enako privzeto/prazno vedenje.