ThunderPhone v3 je tu.Začnite sami, už od 2 ¢/min.Prečítať oznámenie

Webhooks

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, 408 alebo 429, 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-Signature a rovnakú hlavičku X-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"
  }
}
PoleTypPopis
call_idcelé čísloID hovoru — stabilné vo všetkých udalostiach tohto hovoru
from_numberreťazecČíslo volajúceho vo formáte E.164
to_numberreťazecCieľové číslo vo formáte E.164 (jedno z vašich čísel ThunderPhone)
returning_callobjektPrítomné iba vtedy, keď toto číslo volalo volajúcemu za posledných 30 dní. Pozrite si Spätné volania
sip_headersobjektPrí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"
  }
}
PoleTypPopis
call_idcelé čísloID hovoru
origin_domainreťazecPô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_prefixreťazecPrvé znaky publikovateľného kľúča, ktorý otvoril reláciu
language, primary_languagereťazecPrítomné, keď relácia widgetu požiadala o prepísanie jazyka
voicereťazecPrítomné, keď relácia widgetu požiadala o prepísanie hlasu
website_contextreťazecPrí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":   []
}
PoleTypPovinnéPopis
promptreťazecánoSystémová výzva riadiaca agenta
voicereťazecánoID hlasu z GET /v1/voices, napr. john. voice_name sa akceptuje ako alias. Neznáme hlasy neprejdú validáciou a hovor sa odmietne
productreťazecnieOdoš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_levelreťazecnieminimal, 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_modereťazecniefull (predvolené) alebo reduced
watchdog_enabledbooleanniePovoľte dohľad pre tento hovor. Predvolená hodnota je false
additional_audio_contextboolean | nullnieZahrň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_modereťazecnienone, acknowledgement (predvolené) alebo tick: čo volajúci počuje, kým sa pri audio_tier plus alebo max pripravuje pomalšia odpoveď
languagereťazecnieSkrá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_languagereťazecnieKód jazyka, normalizovaný (predvolené en). Nerozpoznateľné kódy spôsobia odmietnutie hovoru
has_additional_languagesbooleanniePredvolená hodnota je false
additional_languagespole reťazcovnieĎalšie jazyky, do ktorých môže agent prepnúť
native_voice_switchingbooleanniePredvolená 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_switchingreťazec | nullnieask_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_tierreťazec | nullnieIba 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ú
endpointingreťazec | nullniefaster (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ú
eagernessreťazec | nullnieZastarané: názov endpointing do 19. októbra 2026, stále sa načítava. Ignoruje sa, keď je nastavené endpointing
intelligencereťazec | nullniecore 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_repliesboolean | nullnieZrý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_trackreťazec | nullnieID ambientného zvuku alebo null
acknowledgement_prompt_modereťazecnieauto (predvolené) alebo manual (staršie hodnoty produktu -with-ack)
acknowledgement_promptreťazecniePoužíva sa, keď acknowledgement_prompt_mode="manual"
silence_interval_secondscelé číslo | nullnie5–120. Sekundy ticha volajúceho pred overením
silence_max_checkinscelé číslo | nullnie1–10
silence_checkins_enabledbooleanniePredvolená hodnota je true
silence_final_actionreťazecniePo poslednom overení: hang_up (predvolené) alebo transfer do silence_transfer_destination
silence_transfer_destinationreťazecnieNá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_messagereťazecnie≤ 300 znakov, prečíta sa tak, ako je napísané; "" (predvolené) použije predvolenú vetu
connect_tone_enabledbooleanniePredvolená hodnota je false
pronunciation_dictsboolean | nullniePredvolená 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
wordspole | nullnieSpô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_actionreťazecnieprompt (predvolené), hangup alebo message
voicemail_messagereťazecniePoužíva sa, keď voicemail_action="message"
agent_namereťazecnieZobrazovaný názov uvádzaný na ovládacích paneloch a vo widgete
org_namereťazecnieZobrazovaný názov organizácie pre personu agenta
toolspolenieVložené schémy funkčných nástrojov (pozrite si Funkčné nástroje)
transfer_destinationspole objektov | nullnieAž 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
timezonereťazecnieČ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
contextreťazec | nullnieVoľ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_idcelé číslonieVoliteľ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
    }
  }
}
PoleTypPopis
agent.idintegerHlasový agent priradený k číslu
agent.namestringJeho názov
agent.versioninteger | 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_pinnedbooleanČ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_reason inbound_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 zobrazia webhook_failed s 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:

  1. returning_call v 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"
        }
      }
    }
    PoleTypPopis
    call_idcelé čísloPredchádzajúci odchádzajúci hovor
    agent_idcelé číslo | nullAgent, ktorý ho uskutočnil; null pre 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ťazecno_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) alebo answered (hovor bol prijatý; zatiaľ nie je známe, kto ho prijal)
  2. 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.

  3. 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, 408 alebo 429), 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

Python (FastAPI)
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 {}
Node.js (Express)
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é.

PoleHodnotyČo ovplyvňuje
intelligencecore, pro (predvolené)Core je lacnejší a začína odpovedať skôr; Pro spoľahlivejšie sleduje dlhé pokyny
audio_tierlite, standard (predvolené), plus, maxVyšš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ý)
endpointingfaster, fast, normal (predvolené), patientKratšie čakanie vedie k skorším odpovediam a stojí viac
faster_repliestrue (predvolené), falseZvýšenie rýchlosti: odpovede prídu o niečo skôr, za o niečo vyššiu cenu

Súvisiace