Open in
telephony.incoming / web.incoming
Blokujúci webhook, ktorý v reálnom čase formuje konfiguráciu prichádzajúceho hovoru.
Keď prichádzajúci telefonický hovor dorazí na číslo bez priradeného
agenta (volajúcich, ktorí odpovedajú na vaše odchádzajúce hovory, nájdete v časti Spätné volania), alebo sa relácia webového widgetu spustí na publikovateľnom kľúči v režime
mode="webhook", ThunderPhone odošle blokujúcu
požiadavku telephony.incoming / web.incoming na vašu
staršiu URL adresu webhooku
a čaká na konfiguračnú odpoveď: pri telefonickom hovore najviac 13 sekúnd vrátane jedného opakovania a pri relácii widgetu najviac 10 sekúnd (pozrite si časť Časové limity a opakovania). Túto výmenu použite na dynamický výber promptu, hlasu a nástrojov pre každý hovor —
kompletný postup nájdete v návode na dynamickú konfiguráciu hovorov.
Číslo s priradeným agentom prijíma hovory prostredníctvom tohto agenta. Keď má agent vlastný webhook nastavenia hovoru, rovnaká blokujúca výmena sa najprv vykoná na adrese URL agenta, aby sa vyplnili premenné agenta a kontext hovoru.
Časové limity a opakovania
Odpovedzte rýchlo: volajúci čaká na linke, kým sa rozhodujete.
Pre telefónny hovor (telephony.incoming):
- Prvý pokus môže trvať až 10 sekúnd.
- Ak vyprší časový limit, nemožno sa pripojiť alebo príde odpoveď
5xx,408alebo429, ThunderPhone skúsi požiadavku ešte raz. Opakovaný pokus dostane zvyšok z 13-sekundového limitu pre celú výmenu: približne 3 sekundy po prvom pokuse, pri ktorom vypršal časový limit, a takmer všetkých 13 po rýchlom zlyhaní. Opakovanie sa nevykoná, ak by zostali menej ako 2 sekundy. - Akákoľvek iná odpoveď
4xx, odpoveď presahujúca limit veľkosti alebo odpoveď2xx, ktorej telo nie je platnou konfiguráciou, je konečná a neopakuje sa. - Oba pokusy odosielajú rovnaké telo, rovnakú hlavičku
X-ThunderPhone-Signaturea rovnakú hlavičkuX-ThunderPhone-Idempotency-Key(telephony-incoming-<call_id>), takže obslužná rutina, ktorá má vedľajšie účinky, dokáže rozpoznať opakovaný pokus.
Ak nepríde žiadna použiteľná konfigurácia, hovor sa okamžite ukončí
namiesto toho, aby volajúci zostal na tichej linke. V histórii hovorov sa
zobrazí ako neúspešný, nefakturovaný hovor s end_reason
inbound_config_webhook_failed a odošle sa štandardná udalosť
telephony.complete. Stránka hovoru v ovládacom
paneli a položka config_webhook_failure v
GET /v1/calls/{call_id} uvádzajú, čo váš webhook
vykonal: {kind, attempts, http_status, host, source}, kde kind je
http_error, timeout, connection, dns, tls, response_too_large,
blocked_url, other, invalid_json, non_object_json alebo
invalid_config, host je názov hostiteľa vášho webhooku a source je
number (tento webhook) alebo agent_setup (webhook nastavenia hovoru
agenta). Pre invalid_config položka reason uvádza, prečo odpoveď nebolo
možné použiť, a fields uvádza názvy príslušných polí: no_agent (ani
agent_id, ani prompt; fields uvádza ignorované kľúče, napríklad
nesprávne napísané agentId), agent_not_found, agent_id_not_integer,
unexpected_fields (kľúče iné než variables, context, timezone a
language vedľa agent_id), invalid_variables, invalid_context,
invalid_language, unsupported_language, invalid_config_fields alebo
agent_settings_invalid. V opačnom prípade je reason null a fields je
prázdne. Jedinou výnimkou je volajúci, ktorý vracia jeden z vašich
odchádzajúcich hovorov, keď zlyhala samotná výmena: pozrite si
Spätné volania.
Relácia widgetu (web.incoming) dostane jeden pokus trvajúci najviac 10
sekúnd. Ak zlyhá, požiadavka relácie zlyhá s 502 alebo 422.
Telo požiadavky
Pre telefonáty (telephony.incoming):
{
"type": "telephony.incoming",
"data": {
"call_id": 987654321,
"from_number": "+14155550199",
"to_number": "+15551234567"
}
}| Pole | Typ | Popis |
|---|---|---|
call_id | celé číslo | ID hovoru — stabilné vo všetkých udalostiach tohto hovoru |
from_number | reťazec | Číslo volajúceho vo formáte E.164 |
to_number | reťazec | Cieľové číslo vo formáte E.164 (jedno z vašich čísel ThunderPhone) |
returning_call | objekt | Prítomné iba vtedy, keď toto číslo volalo volajúcemu za posledných 30 dní. Pozrite si Spätné volania |
sip_headers | objekt | Prítomné iba vtedy, keď hovor prišiel cez manuálne pripojenie SIP s hlavičkami SIP X-* alebo User-to-User: názov hlavičky malými písmenami → hodnota. Pozrite si Hlavičky SIP |
Pre relácie webového widgetu (web.incoming) identifikuje data
namiesto telefónnych čísel stránku s vloženým widgetom:
{
"type": "web.incoming",
"data": {
"call_id": 987654322,
"origin_domain": "https://example.com",
"publishable_key_prefix": "pk_live_a1b2"
}
}| Pole | Typ | Popis |
|---|---|---|
call_id | celé číslo | ID hovoru |
origin_domain | reťazec | Pôvod stránky hostujúcej widget, tak ako ho odoslal prehliadač. Klient, ktorý nie je prehliadačom, môže odoslať ľubovoľnú hodnotu, preto to nepovažujte za dôkaz pôvodu požiadavky |
publishable_key_prefix | reťazec | Prvé znaky publikovateľného kľúča, ktorý otvoril reláciu |
language, primary_language | reťazec | Prítomné, keď relácia widgetu požiadala o prepísanie jazyka |
voice | reťazec | Prítomné, keď relácia widgetu požiadala o prepísanie hlasu |
website_context | reťazec | Prítomné, keď widget odovzdal kontext stránky pre danú reláciu |
Polia prepísania (language, voice, website_context a ľubovoľné
prehliadačové variables) prichádzajú iba vtedy, keď ich publikovateľný kľúč povoľuje vo svojich
prepísaniach v prehliadači. Požiadavka relácie obsahujúca niektoré z nich, ktoré kľúč nepovoľuje, je zamietnutá pred
volaním tohto webhooku.
Schéma odpovede
Vráťte objekt JSON popisujúci konfiguráciu agenta pre tento hovor.
prompt a voice sú povinné; všetko ostatné je voliteľné.
{
"prompt": "You are a helpful booking assistant for Acme Restaurant.",
"voice": "john",
"product": "spark",
"background_track": null,
"tools": []
}| Pole | Typ | Povinné | Popis |
|---|---|---|---|
prompt | reťazec | áno | Systémová výzva riadiaca agenta |
voice | reťazec | áno | ID hlasu z GET /v1/voices, napr. john. voice_name sa akceptuje ako alias. Neznáme hlasy neprejdú validáciou a hovor sa odmietne |
product | reťazec | nie | Odošlite bolt. Predvolená hodnota je spark, staršia hodnota, ktorá sa stále akceptuje spolu s storm-base, storm-base-with-ack, storm-extra a storm-extra-with-ack |
thinking_level | reťazec | nie | minimal, base (predvolené) alebo extra. Pri starších hodnotách produktu storm-* vynúti storm-extra* hodnotu extra a ostatné storm-* vynútia base |
audio_context_mode | reťazec | nie | full (predvolené) alebo reduced |
watchdog_enabled | boolean | nie | Povoľte dohľad pre tento hovor. Predvolená hodnota je false |
additional_audio_context | boolean | null | nie | Zahrňte posledných niekoľko úsekov zvuku volajúceho namiesto iba najnovšieho úseku, čím sa zlepšia opravy a zhromažďovanie údajov s množstvom hláskovania alebo čísel pri malom zvýšení latencie a nákladov. Predvolene je zapnuté pre prichádzajúce relácie a vypnuté pre odchádzajúce telefonické hovory; null zachová predvolenú hodnotu |
storm_feedback_mode | reťazec | nie | none, acknowledgement (predvolené) alebo tick: čo volajúci počuje, kým sa pri audio_tier plus alebo max pripravuje pomalšia odpoveď |
language | reťazec | nie | Skrátený zápis pre primary_language. Je povolený aj vedľa agent_id, kde určuje jazyk, v ktorom tento hovor začína a ktorým hovorí hlas agenta; pozrite si Nastavenie jazyka pre jednotlivý hovor |
primary_language | reťazec | nie | Kód jazyka, normalizovaný (predvolené en). Nerozpoznateľné kódy spôsobia odmietnutie hovoru |
has_additional_languages | boolean | nie | Predvolená hodnota je false |
additional_languages | pole reťazcov | nie | Ďalšie jazyky, do ktorých môže agent prepnúť |
native_voice_switching | boolean | nie | Predvolená hodnota je false. Keď hovor prepne do iného jazyka, namiesto ponechania nakonfigurovaného hlasu sa použije hlas, ktorý je pre daný jazyk rodený (zhodný podľa rodu) |
language_switching | reťazec | null | nie | ask_first (predvolené) alebo follow_caller; null je rovnaké ako ask_first. Určuje, ako viacjazyčný agent reaguje, keď druhá osoba hovorí iným z jeho jazykov. ask_first prepne okamžite, keď požiada o daný jazyk alebo v ňom povie celú vetu, a po niečom krátkom, napríklad „áno“, sa opýta, či má v ňom pokračovať. follow_caller prepne do ktoréhokoľvek nakonfigurovaného jazyka, ktorým hovoria, aj pri jedinom slove. Platí iba, keď je nastavené additional_languages |
audio_tier | reťazec | null | nie | Iba product: "bolt". Počúvanie: ako pozorne agent počuje volajúceho. standard (predvolené; "" a null znamenajú to isté) je vhodné pre väčšinu hovorov (hovory spracúvajúce PHI používajú iba poskytovateľov krytých BAA). lite je najlacnejšie a častejšie nesprávne počuje. plus pri náročných úsekoch počúva pozornejšie, čo trvá približne o 1–2 sekundy dlhšie. max je určené pre najnáročnejší zvuk a zriedkavé jazyky; každá odpoveď trvá 3–4 sekundy a hovor používa inteligenciu pro (intelligence sa ignoruje). max nie je všeobecne dostupné: pre organizáciu, pre ktorú nebolo povolené, hovor používa plus a vami zadanú hodnotu intelligence (požiadavka na odchádzajúci hovor s touto hodnotou sa odmietne s 400). Staršie hodnoty lean (Lite), hearing (Plus) a deep_hearing (Max) sa stále akceptujú. Ostatné produkty ho ignorujú |
endpointing | reťazec | null | nie | faster (200 ms), fast (300 ms), normal (500 ms, predvolené) alebo patient (800 ms); null je rovnaké ako normal. Určuje, ako dlho agent Bolt v2 po tom, čo volajúci prestane hovoriť, čaká pred požiadaním modelu o odpoveď. Kratšie čakanie môže odpovedať skôr, ale odošle viac požiadaviek, ktoré ďalšie slová volajúceho zastarajú, čo zvyšuje náklady na model. Ostatné produkty ho ignorujú |
eagerness | reťazec | null | nie | Zastarané: názov endpointing do 19. októbra 2026, stále sa načítava. Ignoruje sa, keď je nastavené endpointing |
intelligence | reťazec | null | nie | core alebo pro (predvolené); null je rovnaké ako pro. Určuje, ako spoľahlivo agent bolt v kanáli Bolt v2 dodržiava pokyny. core je približne 700 ms po prvé slovo, je najlacnejšie a o trochu menej spoľahlivé (pri hovoroch spracúvaných ako PHI približne 900 ms a menej spoľahlivé); pro je približne 900 ms; odpovede Core, ktoré by iba zavolali nástroj, sa odovzdajú Pro. Staršie hodnoty lite (Core) a standard (Pro) sa stále akceptujú a vyradené hodnoty plus a max sa spúšťajú na pro. Ignoruje sa, keď je audio_tier max. Ostatné produkty ho ignorujú |
faster_replies | boolean | null | nie | Zrýchlenie. Predvolená hodnota je true. Pri agentovi bolt v kanáli Bolt v2 sa odpovede začnú o trochu skôr za mierne vyššiu cenu. false to vypne. Ostatné produkty ho ignorujú |
background_track | reťazec | null | nie | ID ambientného zvuku alebo null |
acknowledgement_prompt_mode | reťazec | nie | auto (predvolené) alebo manual (staršie hodnoty produktu -with-ack) |
acknowledgement_prompt | reťazec | nie | Používa sa, keď acknowledgement_prompt_mode="manual" |
silence_interval_seconds | celé číslo | null | nie | 5–120. Sekundy ticha volajúceho pred overením |
silence_max_checkins | celé číslo | null | nie | 1–10 |
silence_checkins_enabled | boolean | nie | Predvolená hodnota je true |
silence_final_action | reťazec | nie | Po poslednom overení: hang_up (predvolené) alebo transfer do silence_transfer_destination |
silence_transfer_destination | reťazec | nie | Názov položky v transfer_destinations tejto konfigurácie; vyžaduje sa pri transfer. Bez transfer_destinations nie je možné uskutočniť presmerovanie a agent zloží hovor |
silence_final_message | reťazec | nie | ≤ 300 znakov, prečíta sa tak, ako je napísané; "" (predvolené) použije predvolenú vetu |
connect_tone_enabled | boolean | nie | Predvolená hodnota je false |
pronunciation_dicts | boolean | null | nie | Predvolená hodnota je false; null je rovnaké ako false. Keď je hodnota true, reč Cartesia hovoru používa slovník výslovnosti ThunderPhone pre jazyk hovoru, ak existuje. Funguje pre telefonické hovory aj hovory vo widgete. Platí iba pre vlastné hlasy Cartesia od ThunderPhone, nie pre hlasy na vašom vlastnom kľúči Cartesia API. Nepoužíva sa s agent_id, kde platia nastavenia uloženého agenta |
words | pole | null | nie | Spôsob, akým agent vyslovuje konkrétne slová, rovnaké položky ako words agenta bez support. Položka bez language prevezme jazyk tejto konfigurácie. null a [] znamenajú žiadne. Nepoužíva sa s agent_id, kde platia slová uloženého agenta |
voicemail_action | reťazec | nie | prompt (predvolené), hangup alebo message |
voicemail_message | reťazec | nie | Používa sa, keď voicemail_action="message" |
agent_name | reťazec | nie | Zobrazovaný názov uvádzaný na ovládacích paneloch a vo widgete |
org_name | reťazec | nie | Zobrazovaný názov organizácie pre personu agenta |
tools | pole | nie | Vložené schémy funkčných nástrojov (pozrite si Funkčné nástroje) |
transfer_destinations | pole objektov | null | nie | Až 50 položiek {name, number}, do ktorých môže tento hovor presmerovať, validovaných rovnako ako čísla na presmerovanie agenta. Agent presmerúva podľa názvu a iba na tieto položky; [] znamená žiadne presmerovania. Vynechajte túto hodnotu alebo odošlite null, aby agent mohol presmerovať na číslo, ktoré vyberie |
timezone | reťazec | nie | Časové pásmo IANA pre tento hovor, napríklad America/Chicago. Agent v ňom uvádza dátum a čas pred vlastným časovým pásmom agenta. Je povolené aj vedľa agent_id. Hodnoty, ktoré nie sú pásmami IANA, sa ignorujú. Pozrite si Nastavenie časového pásma pre jednotlivý hovor |
context | reťazec | null | nie | Voľný text pre tento hovor, napríklad poznámky zhromaždené vaším systémom, až do 20 000 znakov. Pridá sa za výzvu v oddelenom bloku a nevykresľuje sa ako šablóna. Je povolený aj vedľa agent_id. Hodnota, ktorá nie je reťazcom alebo je dlhšia, spôsobí odmietnutie hovoru. Pozrite si premenné hovoru a kontext |
call_id | celé číslo | nie | Voliteľné zopakovanie ID hovoru požiadavky; ignoruje sa |
Keďže sa vyžadujú prompt a voice, vrátenie {} alebo akejkoľvek
odpovede, ktorá neprejde overením, hovor odmietne: telefonický hovor sa ukončí
podľa popisu v časti Časové limity a opakovania a požiadavka na reláciu
widgetu zlyhá s kódom 422. Platí to aj pre vracajúcich sa volajúcich: akýkoľvek objekt JSON, ktorý váš webhook vráti, je jeho odpoveďou a
{} je spôsob, ako hovor odmietnuť.
Webhook nastavenia hovoru agenta
Hlasový agent môže mať vlastný webhook nastavenia hovoru: pole Webhook nastavenia hovoru
v jeho nastaveniach alebo call_setup_webhook_url
v rozhraní API. Priraďte hlasového agenta k číslu a pred každým prichádzajúcim hovorom
na toto číslo, ktorý hlasový agent spracuje, ThunderPhone požiada webhook o premenné
a kontext daného hovoru. Číslo si zachová svojho hlasového agenta, takže na stránke
telefónnych čísel aj na stránke hlasového agenta sa zobrazuje, ktorý hlasový agent ho spracúva.
Ide o nastavenie ako ostatné nastavenia hlasového agenta: pripravuje sa ako koncept,
publikuje sa pri nasadení a uchováva sa v histórii verzií. Číslo
pripnuté na staršiu verziu
požaduje adresu URL danej verzie. Požiadavky sú podpísané vlastným
call_setup_webhook_signing_secret hlasového agenta (nie tajným kľúčom webhooku
organizácie) s rovnakou hlavičkou X-ThunderPhone-Signature, časovými limitmi,
opakovaním a kľúčom idempotencie ako vyššie. Tajný kľúč je
iba na zápis: nastavte taký, ktorý váš endpoint kontroluje (v nastaveniach hlasového
agenta alebo pomocou PATCH /v1/agents/{id}); žiadne čítanie ho nikdy nevráti a
call_setup_webhook_signing_secret_set uvádza, či je nastavený.
Požiadavka je vyššie uvedený payload telephony.incoming doplnený o hlasového agenta,
ktorého vypĺňa:
{
"type": "telephony.incoming",
"data": {
"call_id": 987654321,
"from_number": "+14155550199",
"to_number": "+15551234567",
"variables": null,
"agent": {
"id": 12,
"name": "Front desk",
"version": 7,
"version_pinned": false
}
}
}| Pole | Typ | Popis |
|---|---|---|
agent.id | integer | Hlasový agent priradený k číslu |
agent.name | string | Jeho názov |
agent.version | integer | null | Číslo verzie, ktorá bude hovor spracúvať: pripnutá verzia čísla, inak najnovšia publikovaná verzia hlasového agenta (null, ak žiadnu nemá) |
agent.version_pinned | boolean | Či je číslo pripnuté na danú verziu |
Odpovedzte údajmi, ktoré hovor potrebuje. Ktorákoľvek z týchto možností doplní priradeného hlasového agenta vo verzii čísla:
{"variables": {...}},{"context": "..."}alebo oboje- to isté s
"agent_id"nastaveným na identifikátor priradeného hlasového agenta {}: hlasový agent spracuje hovor bez doplnených údajov
Povolené sú aj timezone a language, rovnako ako pri
agent_id. Premenné vyplnia
{{placeholders}} hlasového agenta; kontext sa pridá za prompt.
Alebo o hovore rozhodnite sami. agent_id iného hlasového agenta alebo úplná
konfigurácia s prompt spracuje tento jeden hovor namiesto priradeného hlasového
agenta (a jeho pripnutej verzie). Podrobnosti hovoru označujú každý prípad v
call_setup_webhook: assigned_agent,
other_agent alebo inline_config. Odpoveď, ktorú nemožno použiť (neznámy
agent_id, ďalšie kľúče vedľa variables, konfigurácia, ktorá neprejde validáciou),
ukončí hovor rovnako ako webhook čísla.
Kedy musí webhook odpovedať. Hlasový agent potrebuje svoj webhook, keď jeho
nastavenia používajú {{variable}} bez predvolenej hodnoty: jeho prompt alebo
opakovane použiteľné pokyny, pokyny alebo riadky kroku, výzvu na potvrdenie, správu
hlasovej schránky, oznámenie o súhlase alebo číslo na presmerovanie {{variable}}.
call_setup_webhook_variables hlasového agenta ich uvádza.
- Potrebuje webhook: keď webhook prekročí časový limit, nie je dostupný alebo
odpovie chybou či telom, ktoré nie je objekt JSON, hovor sa nezačne, aj keď už
obsahuje hodnotu jednej z týchto premenných. Ukončí sa a zaznamená presne podľa
popisu v Časové limity a opakovania (
end_reasoninbound_config_webhook_failed, nefakturovaný). - Nič nepotrebuje (žiadne premenné alebo každá z nich má predvolenú hodnotu ako
{{first_name|there}}): webhook sa stále spustí, ale keď zlyhá, hlasový agent spracuje hovor bez neho a podrobnosti hovoru zobraziawebhook_faileds informáciou o tom, čo sa pokazilo.
Samotný kontext hovoru nikdy nespôsobí, že webhook je povinný: nič v nastaveniach agenta neuvádza, že potrebuje kontext. Ak sa hovor nesmie začať bez odpovede vášho webhooku, použite premennú bez predvolenej hodnoty.
Priradenie a nasadenie. Agenta, ktorý potrebuje svoj webhook, nemožno
priradiť k číslu bez webhooku: priradenie sa odmietne so správou
uvádzajúcou názvy premenných. Rovnaká kontrola sa vykoná pri zmene verzie
čísla vrátane prípadu, keď sa pripnuté číslo vráti späť na Najnovšiu verziu. Kým agent odpovedá na čísle so svojimi
publikovanými nastaveniami, nasadenie, ktoré pridá takúto premennú bez webhooku
(alebo webhook odstráni), sa rovnakým spôsobom odmietne. Uloženie konceptu je
vždy povolené a warnings agenta obsahuje
call_setup_webhook_needed, kým sa problém neodstráni.
Webhook agenta sa spúšťa iba pri prichádzajúcich telefonických hovoroch na číslach, ku ktorým je priradený. Odchádzajúce hovory, relácie webového widgetu, adresy SIP, simulácie a testovacie konverzácie v paneli ho nevolajú; svoje premenné naďalej preberajú z požiadavky.
Testovanie s uloženými vzorkami. Ak chcete otestovať, čo váš agent urobí s danou odpoveďou (opakovaný volajúci, nenájdený záznam, španielsky hovoriaci volajúci), uložte túto odpoveď pri agentovi ako vzorku: jej variables, context a voliteľne language, zadané ručne alebo skopírované z predchádzajúceho hovoru. Vyberte ju pri spustení testovacej konverzácie na ovládacom paneli, testovacieho hovoru na váš telefón alebo simulácie s agentom a hovor prebehne, akoby na ňu odpovedal váš webhook. Vzorky sú spoločné pre všetky verzie agenta. Úpravou vzorky zachováte jej predchádzajúce verzie: ak zmena agenta vyžaduje premennú, ktorú vzorka nenastavuje, pridajte ju do vzorky a staršie verzie agenta budú naďalej používať vzorku v jej pôvodnej podobe. Simulácie, ktoré vytáčajú telefónne číslo, namiesto toho spúšťajú váš skutočný webhook.
Čísla bez priradeného agenta naďalej používajú webhook čísla alebo organizácie presne podľa vyššie uvedeného popisu.
Spätné volania
Ľudia často zavolajú späť na číslo, z ktorého im niekto volal, napríklad po tom, čo váš agent zanechal hlasovú správu. Keď príde telefonický hovor od osoby, ktorej rovnaké číslo volalo počas posledných 30 dní, ThunderPhone nájde najnovší taký odchádzajúci hovor (taký, pri ktorom zvonil jej telefón) a použije ho tromi spôsobmi:
-
returning_callv požiadavke. Obsahuje ho uvedená blokujúca požiadavka aj oznámenie koncového bodu, takže váš obslužný program môže smerovať volajúceho:{ "type": "telephony.incoming", "data": { "call_id": 987654321, "from_number": "+14155550199", "to_number": "+15551234567", "returning_call": { "call_id": 987650001, "agent_id": 13, "started_at": "2026-10-21T19:05:12.402Z", "outcome": "voicemail" } } }Pole Typ Popis call_idcelé číslo Predchádzajúci odchádzajúci hovor agent_idcelé číslo | null Agent, ktorý ho uskutočnil; nullpre hovor uskutočnený s vloženou konfiguráciou alebo ak bol jeho agent odstránenýstarted_atreťazec Čas začatia hovoru (ISO 8601, UTC) outcomereťazec no_answer(zvonil bez odpovede, linka bola obsadená alebo bol odmietnutý),voicemail(hovor prijala hlasová schránka alebo s agentom nikto nehovoril),conversation(niekto hovoril s agentom) aleboanswered(hovor bol prijatý; zatiaľ nie je známe, kto ho prijal) -
Kontext pre agenta. Ktorýkoľvek agent hovor prijme, dostane na koniec svojej výzvy krátku poznámku: kedy bol predchádzajúci hovor uskutočnený, ktorý agent ho vykonal a aký bol jeho výsledok. Agent dostane pokyn, aby ju nečítal nahlas a aby vzhľadom na možnosť falšovania identifikácie volajúceho nezdieľal nič o tomto hovore okrem toho, že na dané číslo už predtým volal.
-
Záložný agent. Ak číslo nemá agenta pre prichádzajúce hovory a nepríde žiadna konfigurácia, pretože neexistuje URL webhooku alebo váš webhook neodpovedal (vypršal časový limit, nebolo ho možné dosiahnuť alebo pri oboch pokusoch odpovedal
5xx,408alebo429), hovor namiesto ukončenia prejde na agenta, ktorý uskutočnil predchádzajúci hovor, pokiaľ tento agent stále existuje vo vašej organizácii. Spustí sa s nasadenými nastaveniami tohto agenta. Naďalej rozhoduje akákoľvek odpoveď vášho webhooku: ďalšia odpoveď4xx, telo, ktoré nie je objekt JSON,{}alebo konfigurácia, ktorá neprejde overením, ukončí hovor rovnako ako predtým. Agent pre prichádzajúce hovory priradený k číslu vždy hovor prijme.
Zdieľanie podrobností o predchádzajúcom hovore. Identifikáciu volajúceho je
možné falšovať, preto sa do nového hovoru predvolene neprenáša nič z obsahu
predchádzajúceho hovoru. Správca organizácie môže zapnúť možnosť Zdieľať
podrobnosti o predchádzajúcom hovore v časti Organizácia → Všeobecné →
Spätné volania (alebo nastaviť
callback_context_details_enabled).
Keď je táto možnosť zapnutá, poznámka agenta obsahuje aj súhrn predchádzajúceho
hovoru a hovor smerovaný agentovi, ktorý uskutočnil predchádzajúci hovor, sa
spustí s variables daného hovoru (napríklad s menom kontaktu). Zapnite ju len
vtedy, ak je bezpečné zdieľať tieto podrobnosti s kýmkoľvek, kto volá z daného
čísla. Aj keď je zapnutá, hovor, ktorý môže obsahovať chránené zdravotné
informácie, nikdy neprenesie svoj súhrn ani premenné do hovoru, ktorý nie je
určený na spracúvanie PHI.
V podrobnostiach hovoru. Prichádzajúci hovor, ktorý sa zhoduje so skorším hovorom, obsahuje objekt callback v GET /v1/calls/{call_id}:
vyššie uvedený returning_call, routed_as_callback (či ho prijala záložná možnosť)
a config_webhook_failure ({kind, attempts, http_status, host} keď váš webhook neodpovedal a záložná možnosť prevzala
hovor, inak null), takže výpadok webhooku zostane viditeľný, aj keď bol
hovor prijatý.
Limit veľkosti odpovede
Príklad obslužnej funkcie
import hashlib
import hmac
import json
import os
from fastapi import FastAPI, HTTPException, Request
app = FastAPI()
WEBHOOK_SECRET = os.environ["THUNDERPHONE_WEBHOOK_SECRET"]
def verify(body: bytes, signature: str) -> bool:
expected = hmac.new(WEBHOOK_SECRET.encode(), body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, signature or "")
@app.post("/thunderphone-webhook")
async def webhook(request: Request):
body = await request.body()
if not verify(body, request.headers.get("X-ThunderPhone-Signature", "")):
raise HTTPException(status_code=401)
event = json.loads(body)
if event["type"] == "telephony.incoming":
caller = event["data"]["from_number"]
prompt = (
"Greet the caller as a San Francisco local…"
if caller.startswith("+1415")
else "You are a friendly customer support agent…"
)
return {
"prompt": prompt,
"voice": "john",
"product": "spark",
}
if event["type"] == "web.incoming":
return {
"prompt": "You are the website's helpful voice assistant…",
"voice": "john",
"product": "spark",
}
return {}import crypto from "node:crypto";
import express from "express";
const app = express();
const SECRET = process.env.THUNDERPHONE_WEBHOOK_SECRET;
function verify(body, signature) {
const expected = crypto
.createHmac("sha256", SECRET)
.update(body)
.digest("hex");
return signature &&
crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}
app.post(
"/thunderphone-webhook",
express.raw({ type: "application/json" }),
(req, res) => {
if (!verify(req.body, req.header("X-ThunderPhone-Signature"))) {
return res.sendStatus(401);
}
const event = JSON.parse(req.body.toString("utf8"));
if (event.type === "telephony.incoming" || event.type === "web.incoming") {
const caller = event.data.from_number || "web";
const prompt = caller.startsWith("+1415")
? "Greet the caller as a San Francisco local…"
: "You are a friendly customer support agent…";
return res.json({
prompt,
voice: "john",
product: "spark",
});
}
res.json({});
},
);Odpoveď s funkčnými nástrojmi
Pripojte nástroje, aby AI mohla počas konverzácie volať vaše API:
{
"prompt": "You are a booking assistant. Use the available tools to help customers schedule appointments.",
"voice": "john",
"product": "spark",
"tools": [
{
"type": "function",
"function": {
"name": "search_appointments",
"description": "Find available appointment slots",
"parameters": {
"type": "object",
"properties": {
"date": { "type": "string", "description": "YYYY-MM-DD" },
"service": { "type": "string" }
},
"required": ["date"]
}
},
"endpoint": {
"url": "https://api.example.com/appointments/search",
"method": "POST",
"headers": {
"X-Api-Key": "your-key"
}
}
}
]
}Prehľad nastavení
Odošlite product: "bolt" a dolaďte hovor pomocou týchto polí. Staršie
hodnoty product (spark a hodnoty storm-*) sú stále podporované.
| Pole | Hodnoty | Čo ovplyvňuje |
|---|---|---|
intelligence | core, pro (predvolené) | Core je lacnejší a začína odpovedať skôr; Pro spoľahlivejšie sleduje dlhé pokyny |
audio_tier | lite, standard (predvolené), plus, max | Vyššie úrovne lepšie počujú a stoja viac; Plus pri niektorých ťahoch pridáva 1–2 s, každá odpoveď Max trvá 3–4 s (Max nie je všeobecne dostupný) |
endpointing | faster, fast, normal (predvolené), patient | Kratšie čakanie vedie k skorším odpovediam a stojí viac |
faster_replies | true (predvolené), false | Zvýšenie rýchlosti: odpovede prídu o niečo skôr, za o niečo vyššiu cenu |
Súvisiace
Neblokujúca udalosť ukončenia hovoru.
Úplná schéma JSON pre tools[] a kontrakt podpisovaného koncového bodu.
Prihláste viacero adries URL na odber udalostí telephony.incoming / web.incoming.
Vzory pre výzvy, nástroje a A/B testy pre jednotlivých volajúcich.