Developer cookbook

Hívásonkénti változók

Személyre szabhat egy mentett ügynököt minden híváshoz anélkül, hogy módosítaná a telepített promptját, eszközeit vagy beállításait.

Adjon helyőrzőket a mentett ügynök promptjához, majd hívásindításkor adjon meg egy variables objektumot. A mentett konfiguráció és a verzióelőzmények változatlanok maradnak. A ThunderPhone a híváskonfiguráció hangalapú futtatókörnyezetnek való elküldése előtt rendereli a szöveget.

Ha nincs szükség értékekre, hagyja el a variables mezőt, ne küldjön null értéket (400 hibával elutasítva).

Helyőrzők és alapértelmezett értékek#

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

A nevek kis- és nagybetűérzékenyek, és a következő mintát követik: [A-Za-z_][A-Za-z0-9_]*. A név körüli szóközök megengedettek; a | utáni szóköz az alapértelmezett érték része, és megmarad. A {{name|Friend}} a Friend értéket használja, ha a name hiányzik vagy null; az üres karakterlánc kifejezetten megadott érték. Az alapértelmezett érték nélküli hiányzó értékek üres karakterlánccá válnak, és a nevük megjelenik az unresolved_variables mezőben. A dupla kapcsos zárójelek közötti, nem érvényes helyőrzőnek minősülő szöveg eltávolításra kerül. Az egyes megadott értékeken belüli dupla kapcsos zárójeles szöveg ettől függetlenül eltávolításra kerül; egy érték nem távolíthat el környező promptszöveget vagy másik értéket. A pár nélküli dupla kapcsos zárójeles elválasztók szintén eltávolításra kerülnek. A promptokban szereplő JSON-példák nem használhatnak {{ karaktereket. Az értékek egyszerű szövegek, soha nem kerülnek kódként kiértékelésre, és nem bővülnek rekurzívan sablonként.

A változók megjelenhetnek a visszaigazoló promptokban, a kimenő hangpostaüzenetekben, valamint a hozzájárulási közlemény szövegében is, amikor ezt a mezőt telefonhíváshoz küldik. Az ügynöknek nincs külön first_message mezője: a nyitó utasításokat a promptba írja. A meglévő hangposta {agent_name} és {org_name} helyőrzők továbbra is működnek.

Az értékek lehetnek karakterláncok, számok, logikai értékek vagy null; a logikai értékek true és false formában jelennek meg. Az újsor (\n), a tabulátor (\t) és a kocsivissza (\r) kivételével minden Unicode vezérlő (Cc) karakter, minden formázó (Cf) karakter, valamint minden helyettesítő (Cs) kódpont eltávolításra kerül; a \r\n normalizálása \n értékre történik. Minden érték rendereléskor legfeljebb 2 000 karakter hosszú lehet. A megadott karakterláncok tisztítása és csonkolása tárolás előtt is megtörténik. Az eredeti objektumnak bele kell férnie 32 KB UTF-8 JSON-adatba; a nagyobb objektumok 400 hibát kapnak hívás-/munkamenet-kéréseknél, míg a kampányimportok az érvénytelen sorokat egyenként jelzik. Tömbök és beágyazott objektumok nem fogadhatók el értékként. A nem egyező metaadatkulcsok (például szóközt tartalmazó CSV-fejlécek) megmaradnak és visszhangzásra kerülnek, de helyőrzővel nem hivatkozhatók.

Honnan származnak az értékek#

Kimenő API#

Küldje el a variables értéket az agent_id mellett a POST /v1/call kérésben:

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

Ez a telefonszám alapértelmezett kimenő ügynökével vagy beágyazott config.prompt használatával is működik. Az idempotenciakulcs nem használható újra eltérő változókkal.

Kampány CSV#

A nem telefonszámot tartalmazó CSV-oszlopok már kapcsolati változóként vannak tárolva. Minden tárcsázás automatikusan használja őket. A helyőrzőknek megfelelő fejléceket használjon, például name, account_id és appointment_slot. A meglévő névleképezés az utónév- és vezetéknévoszlopokat a name változóba kombinálhatja.

Dinamikus konfigurációs webhook#

A blokkoló konfigurációs webhook útvonalán adjon vissza egy, a szervezetében mentett ügynököt, valamint hívásonkénti értékeket:

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

A válasz kulcsai felülírják a kérési szintű változókat, míg a kérés többi kulcsa megmarad. A null válaszérték a helyőrző alapértelmezett értékét választja. Az egyesített objektumnak is bele kell férnie 32 KB-ba. A mentett ügynök válaszai csak az agent_id és a variables értékeket fogadják el; beágyazott konfigurációt adjon vissza, ha le kell cserélnie a promptot vagy a beállításokat. A prompt értéket tartalmazó válasz mindig beágyazott konfigurációt használ: az ilyen válaszban szereplő bármely agent_id figyelmen kívül marad, beleértve a null vagy nem egész szám típusú metaadatokat is. A beágyazott promptnak továbbra is át kell mennie a szokásos ellenőrzésen. A beágyazott webhookválaszok variables értékeket is tartalmazhatnak. A mentett ügynök webhookválaszai az ügynök telepített A/B megosztását használják telefonos és widgethívások esetén is; a változók a variáns kiválasztása után jelennek meg. Bejövő telefonhívások esetén olyan számot használjon, amelyhez nincs hozzárendelve bejövő ügynök, és konfigurálja annak telefonszám- vagy szervezeti webhookját; a widgetkulcsok mode="webhook" értéket használnak. A végpontrendszer bejövő értesítései nem biztosítanak blokkoló konfigurációs válaszokat.

Widget- és Realtime-munkamenet API-k#

A POST /v1/widget/session felső szintű variables objektumot fogad el. A közzétehető kulcsa választja ki a mentett ügynököt. A webhook módú kulcsok ezeket az értékeket továbbítják a konfigurációs webhooknak, és a választ a fent leírtak szerint egyesítik. A böngésző által megadott widget/realtime variables értékek kliens által vezéreltek, a fent leírt ellenőrzés és karakterlánc-tisztítás után változatlanul továbbítódnak a web.incoming eseményben, valamint visszakerülnek a befejezési webhookokba és a híváselőzményekbe. Ne kezelje őket megbízható azonosítási vagy jogosultsági adatként.

A POST /v1/realtime/sessions a variables értéket az agent_id (vagy beágyazott config) mellett fogadja el. Ezek a munkamenet-létrehozó API mezői. A Realtime WebSocket bridge nem továbbít változóbeállítást; közvetlenül a munkamenet-létrehozó API-nak adja meg. A widgetklienseknek a variables értéket a beküldött munkamenet-adatcsomagban kell megadniuk; az SDK általi továbbítás nem része ennek az API-módosításnak. A Builder mikrofonos és szimulált teszthívásai feloldják az alapértelmezéseket és a hiányzó helyőrzőket, de nem rendelkeznek hívásonkénti változóbemenettel.

A hívás után visszaadott értékek#

A GET /v1/calls, GET /v1/calls/{call_id}, telephony.complete és web.complete tartalmazza a végső egyesített variables és unresolved_variables értékeket. Az örökölt befejezési adatcsomagok, amelyek tartalmazzák a data.history értéket, ezeket is tartalmazzák:

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

Tárolja CRM- vagy feladatazonosítóját a változóobjektumban, hogy a befejezett hívást visszakapcsolhassa a forrásrekordjához. Ezek a mezők a hívásrekorddal együtt megőrződnek; csak olyan információt küldjön, amelyet helyénvaló a híváselőzményekben és webhookokban megőrizni.

Kompatibilitás meglévő promptokkal#

A renderelés a meglévő mentett ügynök- és A/B-változatpromptokra, a beágyazott kimenő és valós idejű konfigurációkra, valamint a konfigurációs webhookok által visszaadott promptokra is vonatkozik. Az ismeretlen {{name}} helyőrzők üres szöveggé válnak, még akkor is, ha nincsenek megadva variables értékek. Élesítés előtt ellenőrizze a meglévő promptokat, beleértve a külső forrásból származó beágyazott/webhook promptokat is, amelyeket a ThunderPhone nem tud leltározni. A Builder mikrofon- és szimulációs hívásai ugyanezt az alapértelmezett/üres viselkedést alkalmazzák.