Developer cookbook

Varijable po pozivu

Prilagodite spremljenog agenta za svaki poziv bez mijenjanja njegova objavljenog upita, alata ili postavki.

Stavite rezervirana mjesta u prompt svojeg spremljenog agenta, a zatim pri pokretanju poziva navedite objekt variables. Spremljena konfiguracija i povijest verzija ostaju nepromijenjene. ThunderPhone prikazuje tekst prije slanja konfiguracije poziva glasovnom izvršnom okruženju.

Kada vrijednosti nisu potrebne, izostavite variables; nemojte slati null (odbijeno s 400).

Rezervirana mjesta i zadane vrijednosti#

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

Nazivi razlikuju velika i mala slova te slijede obrazac [A-Za-z_][A-Za-z0-9_]*. Razmaci oko naziva su dopušteni; razmak nakon znaka | dio je zadane vrijednosti i zadržava se. {{name|Friend}} koristi Friend kada name nedostaje ili je null; prazan niz izričito je navedena vrijednost. Nedostajuće vrijednosti bez zadane vrijednosti postaju prazni nizovi, a njihovi se nazivi prikazuju u unresolved_variables. Tekst između dvostrukih vitičastih zagrada koji nije valjano rezervirano mjesto uklanja se. Tekst u dvostrukim vitičastim zagradama unutar svake navedene vrijednosti uklanja se neovisno; vrijednost ne može ukloniti okolni tekst prompta ni drugu vrijednost. Uklanjaju se i neupareni razdjelnici s dvostrukim vitičastim zagradama. Primjeri JSON-a u promptovima ne smiju koristiti {{. Vrijednosti su običan tekst, nikada se ne izvršavaju kao kod niti se rekurzivno proširuju kao predlošci.

Varijable se mogu pojaviti i u promptovima za potvrdu, odlaznim porukama govorne pošte te tekstu obavijesti o pristanku kada se to polje šalje za telefonski poziv. Agent nema zasebno polje first_message: njegove uvodne upute stavite u prompt. Postojeća rezervirana mjesta govorne pošte {agent_name} i {org_name} nastavljaju raditi.

Vrijednosti mogu biti nizovi, brojevi, Booleove vrijednosti ili null; Booleove vrijednosti prikazuju se kao true i false. Unicode kontrolni znakovi (Cc) osim novog retka (\n), tabulatora (\t) i povratka na početak retka (\r), svi znakovni formati (Cf) i zamjenske (Cs) kodne točke uklanjaju se; \r\n se normalizira u \n. Svaka vrijednost ograničena je na 2.000 znakova pri prikazu. Navedeni nizovi također se čiste i skraćuju prije pohrane. Izvorni objekt mora stati u 32 KB UTF-8 JSON-a; veći objekti dobivaju 400 u zahtjevima za pozive/sesije, dok uvozi kampanja pojedinačno prijavljuju nevaljane retke. Nizovi i ugniježđeni objekti nisu prihvaćeni kao vrijednosti. Metapodatkovni ključevi koji ne odgovaraju obrascu (na primjer zaglavlje CSV-a s razmakom) zadržavaju se i vraćaju, ali se ne mogu referencirati rezerviranim mjestom.

Odakle dolaze vrijednosti#

Izlazni API#

Pošaljite variables zajedno s agent_id u zahtjevu 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"
  }
}

To funkcionira i s telefonskim brojem čiji je zadani izlazni agent postavljen ili s ugrađenim config.prompt. Ključ idempotentnosti ne može se ponovno upotrijebiti s različitim varijablama.

CSV kampanje#

CSV stupci koji nisu telefonski brojevi već se pohranjuju kao varijable kontakta. Svako biranje sada ih automatski koristi. Upotrijebite zaglavlja poput name, account_id i appointment_slot kako bi odgovarala vašim rezerviranim mjestima. Postojeće mapiranje imena može kombinirati stupce imena i prezimena u varijablu name.

Webhook za dinamičku konfiguraciju#

Na putanji blokirajućeg webhooka za konfiguraciju vratite spremljenog agenta u svojoj organizaciji zajedno sa svim vrijednostima za pojedini poziv:

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

Ključevi odgovora prepisuju varijable na razini zahtjeva, dok ostali ključevi zahtjeva ostaju. Vrijednost null u odgovoru odabire zadanu vrijednost rezerviranog mjesta. Spojeni objekt također mora stati u 32 KB. Odgovori sa spremljenim agentom prihvaćaju samo agent_id i variables; vratite ugrađenu konfiguraciju kada trebate zamijeniti prompt ili postavke. Odgovor koji sadrži prompt uvijek koristi ugrađenu konfiguraciju: svaki agent_id u tom odgovoru zanemaruje se, uključujući null ili metapodatke koji nisu cijeli broj. Ugrađeni prompt i dalje mora proći uobičajenu provjeru valjanosti. Ugrađeni odgovori webhooka mogu također sadržavati variables. Odgovori webhooka sa spremljenim agentom koriste implementiranu A/B podjelu agenta i za telefonske pozive i za pozive widgeta; varijable se prikazuju nakon odabira varijante. Za dolazne telefonske pozive upotrijebite broj bez dodijeljenog dolaznog agenta i konfigurirajte njegov webhook za telefonski broj ili organizaciju; ključevi widgeta koriste mode="webhook". Dolazne obavijesti sustava krajnjih točaka ne pružaju blokirajuće odgovore konfiguracije.

API-ji sesija widgeta i Realtimea#

POST /v1/widget/session prihvaća objekt variables najviše razine. Njegov objavljivi ključ odabire spremljenog agenta. Ključevi u načinu webhooka prosljeđuju te vrijednosti webhooku za konfiguraciju i spajaju odgovor kako je opisano iznad. Varijable variables widgeta/realtimea koje dostavlja preglednik pod kontrolom su klijenta, prosljeđuju se doslovno u web.incoming nakon gore opisane provjere valjanosti i čišćenja nizova te se ponavljaju u webhookovima dovršetka i povijesti poziva. Ne smatrajte ih pouzdanim podacima o identitetu ili autorizaciji.

POST /v1/realtime/sessions prihvaća variables zajedno s agent_id (ili ugrađenim config). To su polja API-ja za stvaranje sesije. Most Realtime WebSocket ne prosljeđuje opciju varijabli; navedite je izravno u API-ju za stvaranje sesije. Klijenti widgeta moraju uključiti variables u poslani teret sesije; prosljeđivanje putem SDK-a nije dio ove izmjene API-ja. Pozivi za testiranje mikrofona u Builderu i simulirani pozivi razrješavaju zadane vrijednosti i nedostajuća rezervirana mjesta, ali nemaju unos varijabli za pojedini poziv.

Vrijednosti vraćene nakon poziva#

GET /v1/calls, GET /v1/calls/{call_id}, telephony.complete i web.complete uključuju konačne spojene variables i unresolved_variables. Naslijeđeni tereti dovršetka koji uključuju data.history također ih uključuju:

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

Pohranite identifikator svojeg CRM-a ili zadatka u objekt varijabli kako biste dovršeni poziv povezali s njegovim izvornim zapisom. Ta se polja zadržavaju uz zapis poziva; šaljite samo informacije koje je primjereno zadržati u povijesti poziva i webhookovima.

Kompatibilnost s postojećim upitima#

Renderiranje se primjenjuje i na postojeće upite spremljenih agenata i A/B varijanti, ugrađene izlazne konfiguracije i konfiguracije u stvarnom vremenu te upite vraćene putem konfiguracijskih webhookova. Nepoznati rezervirani dijelovi {{name}} postaju prazan tekst, čak i kada nisu navedene varijable variables. Provjerite postojeće upite prije uvođenja, uključujući ugrađene upite i upite webhookova dostavljene iz vanjskih izvora koje ThunderPhone ne može evidentirati. Pozivi mikrofona u alatu Builder i simulacijski pozivi primjenjuju isto zadano ponašanje za prazne vrijednosti.