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

Webhooks

Katalóg udalostí

Všetky typy udalostí webhookov, ktoré ThunderPhone odosiela.

Každé telo webhooku obsahuje pole type, ktorého hodnota je jedným z typov udalostí na tejto stránke. Keď sa prihlásite na odber koncového bodu, pole events musí obsahovať požadované typy udalostí (alebo môže byť prázdne, ak sa chcete prihlásiť na odber všetkých — s výnimkou udalostí pre jednotlivé ťahy telephony.turn / web.turn a udalosti priebežného stavu call.status_changed, ktoré sa doručujú iba koncovým bodom, ktoré ich výslovne uvedú).

Tieto udalosti sa doručujú dvoma spôsobmi:

  • Doručenia endpointu sú vždy neblokujúce oznámenia s opakovaniami: odpovedzte ľubovoľným kódom 2xx; obálka obsahuje event_id na deduplikáciu.
  • Blokujúce výmeny prebiehajú iba v rámci staršieho webhooku s jednou URL: konfiguračná požiadavka telephony.incoming / web.incoming (čísla v režime webhooku: 13 s vrátane jedného opakovania; kľúče widgetu v režime webhooku: 10 s) a odoslanie nástroja v režime webhooku. Vaša odpoveď formuje prebiehajúci hovor.

Ukážkové payloady nižšie zobrazujú obálku koncového bodu v poradí pri prenose (kľúče zoradené abecedne: data, event_id, type); staršie doručenia obsahujú rovnaké data bez event_id.

Udalosti hovorov

telephony.incoming

Odosiela sa, keď prichádzajúci hovor dorazí na jedno z vašich telefónnych čísel. Doručenia na endpoint sú oznámenia bez čakania na odpoveď odoslané pre každý prichádzajúci hovor, bez ohľadu na to, či je číslo nakonfigurované pre agenta alebo webhook. Čísla bez priradeného agenta navyše dostanú blokujúcu požiadavku na konfiguráciu na staršom webhooku — úplnú schému požiadavky a odpovede nájdete v telephony.incoming / web.incoming.

{
  "data": {
    "call_id": 987654321,
    "from_number": "+14155550199",
    "to_number": "+15551234567"
  },
  "event_id": "3f6b2ad0-1c9e-4a57-9f2b-8f6f0f9d2f11",
  "type": "telephony.incoming"
}
PoleTypPopis
agent_idinteger | nullAgent, ktorý hovor spracoval, ak bol priradený
agent_namestring | nullAgent, ktorý hovor spracoval, ak bol priradený
returning_callobjectPrítomné iba vtedy, ak číslo volalo tomuto volajúcemu za posledných 30 dní: call_id, agent_id, started_at a outcome predchádzajúceho hovoru. Pozrite si Spätné volania
sip_headersobjectPrítomné iba vtedy, ak hovor prišiel so SIP hlavičkami X-* alebo User-to-User (SIP adresy a manuálne SIP pripojenia): názov hlavičky malými písmenami → hodnota. Pozrite si SIP hlavičky

telephony.complete

Odosiela sa po skončení prichádzajúceho alebo odchádzajúceho telefonického hovoru. Neblokujúca udalosť. Obsahuje prepis, adresu URL nahrávky, ak je k dispozícii, a súhrn účtovania. Schému payloadu nájdete v telephony.complete / web.complete.

PoleTypPopis
agent_idinteger | nullAgent, ktorý vybavil hovor, ak bol priradený
agent_namestring | nullAgent, ktorý vybavil hovor, ak bol priradený

telephony.tool

Odosiela sa po tom, ako telefonický hovor vyvolá nástroj funkcie. Neblokujúce audítorské oznámenie — nástroj je už vykonaný pri doručení tejto udalosti; zahŕňa vaše vlastné nástroje funkcií a vstavaný nástroj send_sms (nie iné vstavané nástroje, nástroje znalostnej databázy, pripojenia aplikácií ani nástroje MCP). Pre send_sms sú arguments.to aj arguments.body hodnotou [REDACTED]. Prepisy dokončených hovorov ich tiež redigujú; obsah a príjemcu získate zo zdroja SMS na úrovni organizácie pomocou message_id z odpovede.

{
  "data": {
    "arguments": { "date": "2026-04-21" },
    "call_id": 987654321,
    "from_number": "+14155550199",
    "response": {
      "response": { "available_slots": ["9:00 AM", "2:00 PM"] },
      "status": 200
    },
    "to_number": "+15551234567",
    "tool_name": "search_appointments"
  },
  "event_id": "1f0a7c3e-52d4-4a0e-8f4b-b1a6a1c0d9e2",
  "type": "telephony.tool"
}

response je výsledok vykonania: pri úspechu {"status": <http status>, "response": <your endpoint's JSON>} alebo pri zlyhaní {"status": <status>, "error": "<message>"}.

PoleTypPopis
agent_idinteger | nullAgent, ktorý vybavil hovor, ak bol priradený
agent_namestring | nullAgent, ktorý vybavil hovor, ak bol priradený

telephony.turn

Odosiela sa počas prebiehajúceho telefonického hovoru, raz pre každý úsek obsahujúci reč v okamihu jeho vzniku — hovorené odpovede agenta a prepísané repliky volajúceho. Umožňuje sledovať živú konverzáciu prostredníctvom bežných webhookov namiesto pravidelného zisťovania stavu GET /v1/calls/{call_id}/transcript. Neblokujúca udalosť.

{
  "data": {
    "call_id": 987654321,
    "entry_type": "completion",
    "from_number": "+14155550199",
    "position": 7,
    "role": "assistant",
    "start_ms": 15200,
    "text": "How many employees does your company have?",
    "to_number": "+15551234567"
  },
  "event_id": "8d3f5a2c-7b1e-4c9a-b6d0-2e4f6a8c0d1e",
  "type": "telephony.turn"
}
PoleTypPopis
agent_idinteger | nullAgent, ktorý vybavil hovor, ak bol priradený
agent_namestring | nullAgent, ktorý vybavil hovor, ak bol priradený
positionintegerIndex repliky v histórii hovoru — stabilný identifikátor na určovanie poradia
rolestringassistant (reč agenta) alebo user (reč volajúceho)
textstringText prepisu repliky, ako je známy v čase odoslania
entry_typestringTyp podkladového záznamu histórie: completion (agent) alebo user_turn / span (volajúci)
start_ms, end_msintegerPosuny zvuku v ms od začiatku hovoru; sú prítomné iba vtedy, keď bolo načasovanie prehrávania v čase odoslania už známe

web.incoming

Ekvivalent telephony.incoming pre webový kanál, odoslaný pri spustení relácie webového widgetu alebo testovacieho hovoru mikrofónu v nástroji na tvorbu. Doručenia na endpoint sú oznámenia bez čakania na odpoveď pre každú webovú reláciu. Publikovateľné kľúče v režime mode="webhook" navyše dostanú blokujúcu požiadavku na konfiguráciu na staršom webhooku — táto blokujúca požiadavka má odlišnú štruktúru (origin_domain, publishable_key_prefix; bez telefónnych čísel). Pozrite si telephony.incoming / web.incoming.

{
  "data": {
    "call_id": 987654322,
    "from_number": "web",
    "origin_domain": "https://example.com",
    "publishable_key_prefix": "pk_live_a1b2",
    "to_number": "+15551234567"
  },
  "event_id": "9a2b4c6d-8e0f-4a1b-9c2d-3e4f5a6b7c8d",
  "type": "web.incoming"
}

from_number má vždy doslovnú hodnotu "web". Pre relácie widgetu v režime webhook je to_number prázdne (číslo agenta relácie sa priradí po konfigurácii); pre testovacie hovory mikrofónu v nástroji na tvorbu sú origin_domain a publishable_key_prefix prázdne.

PoleTypPopis
agent_idinteger | nullAgent, ktorý vybavil hovor, ak bol priradený
agent_namestring | nullAgent, ktorý vybavil hovor, ak bol priradený

web.complete

Ekvivalent telephony.complete pre webový kanál, ktorý zahŕňa hovory webového widgetu (direction: "web") a testovacie hovory mikrofónu v nástroji na tvorbu (direction: "test"). Neblokujúca udalosť. Má rovnakú štruktúru payloadu ako telephony.complete, navyše s origin_domain, pričom from_number je nastavené na "web".

PoleTypPopis
agent_idinteger | nullAgent, ktorý vybavil hovor, ak bol priradený
agent_namestring | nullAgent, ktorý vybavil hovor, ak bol priradený

web.tool

Ekvivalent telephony.tool pre webový kanál. data obsahuje origin_domain namiesto from_number / to_number.

PoleTypPopis
agent_idinteger | nullAgent, ktorý vybavil hovor, ak bol priradený
agent_namestring | nullAgent, ktorý vybavil hovor, ak bol priradený

web.turn

Ekvivalent telephony.turn pre webový kanál, ktorý zahŕňa hovory webového widgetu a testovacie hovory mikrofónu v nástroji na tvorbu. Má rovnakú štruktúru payloadu, pričom obsahuje origin_domain namiesto from_number / to_number. Rovnako ako telephony.turn vyžaduje explicitné prihlásenie na odber — nikdy sa nedoručuje prostredníctvom prázdneho poľa events.

PoleTypPopis
agent_idinteger | nullAgent, ktorý vybavil hovor, ak bol priradený
agent_namestring | nullAgent, ktorý vybavil hovor, ak bol priradený

call.transfer_completed

Odosiela sa raz za hovor s konečným výsledkom prepojenia hovoru: studeného prepojenia alebo premostenia medzi ľuďmi, ktoré zostane po teplom prepojení, keď agent hovor opustí. Je neblokujúca a doručuje sa len do endpointov (nikdy do staršieho webhooku s jednou URL). Prichádza po udalosti hovoru telephony.complete: keď poskytovateľ prevezme hovor alebo prepojenie zlyhá, alebo keď ThunderPhone hovor premostil, po ukončení premostenia.

{
  "data": {
    "agent_id": 12,
    "agent_name": "Front desk",
    "bridge_kind": "cold_fallback",
    "bridge_seconds": 255,
    "bridge_total_cents": 5,
    "call_id": 987654321,
    "destination": "+15555550102",
    "sip_status": 403,
    "transfer_outcome": "bridged"
  },
  "event_id": "5b0f6c1e-9d2a-5e7b-8c4d-1a2b3c4d5e6f",
  "type": "call.transfer_completed"
}
PoleTypPopis
call_idintegerHovor, ktorý bol prepojený
agent_idinteger | nullAgent, ktorý spracoval hovor, ak bol priradený
agent_namestring | nullAgent, ktorý spracoval hovor, ak bol priradený
transfer_outcomestringrefer_accepted: poskytovateľ prevzal hovor. bridged: ThunderPhone sám udržal volajúceho a cieľ pripojených, buď preto, že poskytovateľ odmietol studené prepojenie, alebo preto, že agent pri teplom prepojení hovor opustil. bridge_unanswered: poskytovateľ odmietol studené prepojenie a cieľ neodpovedal na vlastný hovor ThunderPhone. failed: prepojenie neprebehlo a hovor sa skončil
destinationstring | nullČíslo, na ktoré bol hovor prepojený
sip_statusinteger | nullStav SIP poskytovateľa pri odmietnutí studeného prepojenia: 403 (napríklad trunk Twilio bez prepojenia hovorov), 405 alebo 501. null, ak ho poskytovateľ neodmietol
bridge_kindstring | nullLen pri bridged: cold_fallback (odmietnuté studené prepojenie, ktoré ThunderPhone pripojil) alebo warm (dve osoby pri teplom prepojení po odchode agenta)
bridge_secondsinteger | nullLen pri bridged: čas premostenia, ktorý ThunderPhone vyúčtoval, v sekundách
bridge_total_centsinteger | nullLen pri bridged: cena premostenia v centoch USD po odpočítaní prípadného bezplatného kreditu na hovory, účtovaná samostatne od billing_total_cents hovoru

Rovnaké hodnoty sú v objekte hovoru ako transfer_outcome, transfer_destination, transfer_sip_status, transfer_bridge_kind, transfer_bridge_seconds a transfer_bridge_total_cents. event_id je pri každom doručení pre hovor rovnaké, takže opakované hlásenie nikdy nevytvorí druhú udalosť.

call.billed

Odosiela sa pre hovor účtovaný podľa meranej spotreby: keď sa jeho platba vyrovná, niekoľko minút po skončení hovoru po prijatí údajov o využití, a znova vždy, keď neskôr prijaté údaje o využití zvýšia platbu. Udalosť hovoru telephony.complete / web.complete obsahuje billing_pending: true a účtovacie polia null. Je neblokujúca a doručuje sa iba na koncové body (nikdy do staršieho webhooku s jednou adresou URL). Hovory účtované pri skončení obsahujú účtovanie v udalosti dokončenia a nedostanú call.billed.

Poradie nie je zaručené: platba zvyčajne čaká na udalosť dokončenia, ale call.billed môže prísť pred ňou (udalosť dokončenia zdržaná na hodinu alebo doručenia opakované v rôznych časoch) a dve udalosti call.billed môžu prísť v nesprávnom poradí. Pre každý call_id uchovajte udalosť s najvyšším billing_seq.

{
  "data": {
    "adjustment_cents": null,
    "agent_id": 12,
    "agent_name": "Front desk",
    "billable_minutes": 3.0,
    "billing_seq": 1,
    "billing_total_cents": 10,
    "call_id": 987654321,
    "reason": "settled"
  },
  "event_id": "7c1d2e3f-4a5b-5c6d-8e7f-9a0b1c2d3e4f",
  "type": "call.billed"
}
PoleTypPopis
call_idcelé čísloHovor, ktorý bol účtovaný
agent_idcelé číslo | nullAgent, ktorý spracoval hovor, ak bol priradený
agent_namereťazec | nullAgent, ktorý spracoval hovor, ak bol priradený
reasonreťazecsettled: platba za hovor. adjusted: údaje o využití prijaté po platbe ju zvýšili (platba sa nikdy neznižuje)
billing_seqcelé číslo1 pre platbu, potom 2, 3, ... pre každé zvýšenie. Najvyššia prijatá hodnota predstavuje aktuálne účtovanie hovoru
billable_minutesčísloÚčtované minúty, zaokrúhlené na najbližšiu štvrťminútu
billing_total_centscelé čísloVšetko, čo bolo za hovor doteraz účtované v centoch USD, po odpočítaní prípadného kreditu za bezplatný hovor, vrátane zvýšení adjusted
adjustment_centscelé číslo | nullIba adjusted: toto zvýšenie v centoch USD po odpočítaní prípadného kreditu za bezplatný hovor

Rovnaké súčty sú v objekte hovoru ako billable_minutes a billing_total_cents. event_id je rovnaké pri každom doručení jedného billing_seq, takže opakované hlásenie nikdy nevytvorí druhú udalosť.

call.status_changed

Odosiela sa, keď hovor prebieha, pri každom dosiahnutí novej fázy: ThunderPhone začne vytáčať, osoba alebo jej telefón prijme hovor, hlasový agent sa dovolá do hlasovej schránky alebo je prepnutý do podržania a následne z neho uvoľnený. Použite ju na zobrazenie priebehu živého hovoru, napríklad „Vytáčanie…“, „Prijaté“, „Podržané“ a „Uvoľnené z podržania po 4 minútach“ vo vlákne chatu, ktoré sleduje hovor. Neblokuje spracovanie a doručuje sa iba do koncových bodov (nikdy do staršieho webhooku s jednou adresou URL).

{
  "data": {
    "agent_id": 12,
    "agent_name": "Front desk",
    "call_id": 987654321,
    "direction": "outbound",
    "hold_seconds": 240,
    "occurred_at": "2026-11-07T17:04:12.418Z",
    "status": "off_hold"
  },
  "event_id": "2f6a1c9e-3b7d-5e8f-9a0b-4c5d6e7f8a9b",
  "type": "call.status_changed"
}
PoleTypPopis
call_idcelé čísloHovor
agent_idcelé číslo | nullHlasový agent, ktorý vybavil hovor, ak bol priradený
agent_namereťazec | nullHlasový agent, ktorý vybavil hovor, ak bol priradený
directionreťazecSmer hovoru, ako v objekte hovoru
statusreťazecFáza, ktorú hovor dosiahol; pozrite si tabuľku nižšie
occurred_atčasová pečiatkaKedy sa to stalo
hold_secondscelé číslo | nullIba pre off_hold: ako dlho trvalo podržanie v sekundách. null pre každý iný stav
statusKedy sa odosiela
dialingOdchádzajúce hovory: ThunderPhone uskutočňuje hovor. Odosiela sa tesne pred odovzdaním vytáčania poskytovateľovi siete, po úspešnom dokončení všetkých kontrol, ktoré by mohli hovor odmietnuť. Skúšobné hovory spustené z ovládacieho panela sa neodosielajú
answeredOdchádzajúce hovory: poskytovateľ siete nahlásil prijatie hovoru. Započítava sa aj prijatie hlasovou schránkou alebo systémom filtrovania hovorov, takže môže nasledovať voicemail. Keď sa ThunderPhone o prijatí dozvie až zo správy po skončení hovoru, answered sa odošle pri ukončení hovoru
voicemailOdchádzajúce hovory: hlasový agent sa dovolal do hlasovej schránky a zanecháva správu alebo ukončuje hovor podľa nastavenia voicemail_action hlasového agenta. Odosiela sa po potvrdení schránky (jej pípnutím alebo žiadnou odpoveďou), nie pri prvom odhade
on_holdHlasový agent bol prepnutý do podržania a potichu čaká (nástroj wait_on_hold)
off_holdOsoba sa vrátila k hovoru a hlasový agent opäť hovorí. hold_seconds udáva, ako dlho trvalo podržanie

Každý hovor odošle každý stav najviac raz, s výnimkou on_hold a off_hold, ktoré sa odosielajú raz pri každom podržaní. Typický odchádzajúci hovor, ktorý čaká v podržaní, odošle dialing, answered, on_hold, off_hold a následne telephony.complete pri svojom ukončení.

Vyzváňanie sa neoznamuje: to, či operátor signalizuje vyzváňanie, sa príliš líši na to, aby sa naň dalo spoľahnúť. Pri niekoľkých volaniach s voicemail_action: "prompt", pri ktorých o tom, čo sa má urobiť v hlasovej schránke, rozhoduje výzva agenta namiesto ThunderPhone, sa stav voicemail neodosiela; answered_by v telephony.complete stále uvádza voicemail. Údaje neobsahujú prepis, telefónne čísla ani premenné, takže call.status_changed sa odosiela aj pri volaniach s vypnutým nahrávaním.


Udalosti SMS

Udalosti SMS opisujú správy odoslané prostredníctvom pripojeného účtu Twilio alebo Telnyx organizácie. Telo správy sa neuvádza a hodnota to je redigovaná. Správu v rozsahu organizácie získajte pomocou GET /v1/sms/{message_id}, keď potrebujete jej obsah alebo príjemcu. Hodnota source je api, agent_tool, followup alebo pre_call (text kampane pred volaním), rovnako ako pri objekte správy.

Každá udalosť SMS obsahuje scheduled_send_id: identifikátor naplánovaného odoslania, pre ktoré bola správa odoslaná, alebo null pre správu, ktorá nebola naplánovaná. Naplánované správy majú source "scheduled".

sms.sent

Odošle sa, keď operátor zákazníka prijme požiadavku na odoslanie SMS. Nejde o potvrdenie doručenia do telefónu.

{
  "data": {
    "accepted_at": "2026-09-19T15:42:10.113Z",
    "agent_id": 12,
    "call_id": 987654321,
    "created_at": "2026-09-19T15:42:09.901Z",
    "direction": "outbound",
    "error_code": null,
    "error_message": null,
    "from_number": "+15551234567",
    "id": "313a3117-827b-46e9-a01a-ac1493838724",
    "provider": "twilio",
    "provider_id": "SM0123456789abcdef0123456789abcdef",
    "scheduled_send_id": null,
    "segment_count": 1,
    "source": "agent_tool",
    "status": "accepted",
    "to": "[REDACTED]"
  },
  "event_id": "0ae347b4-1716-45bb-9a0e-b52373586e37",
  "type": "sms.sent"
}

sms.failed

Odošle sa po trvalom odmietnutí operátorom, po vyčerpaní dočasných opakovaných pokusov, keď je výsledok terminálne neznámy alebo keď Twilio nahlási prijatú správu ako nedoručenú alebo neúspešnú. V poslednom prípade už bolo odoslané sms.sent správy a status zostáva "accepted". error_code je stabilný kód ThunderPhone a error_message uvádza akciu zákazníka, ak je k dispozícii. status: "unknown" znamená, že operátor mohol SMS prijať; overte ju v zázname operátora, pretože ThunderPhone ju automaticky znova neodošle.

sms.received

Vyhradené pre podporu prichádzajúcich SMS. V aktuálnom vydaní sa nevysielajú žiadne udalosti sms.received. Konfigurácia webhooku prichádzajúcich správ od operátora a overovanie podpisu budú dodané samostatne.


Naplánované udalosti

Naplánované odoslania, ktoré sa neuskutočnia, vyvolajú jednu z týchto udalostí. Odoslanie, ktoré sa uskutoční, namiesto toho vyvolá bežné udalosti: udalosti sms.* s nastaveným scheduled_send_id pre správu, udalosti hovoru pre hovor s scheduled_send_id v jeho telephony.complete. Obe sú neblokujúce. Keď má odoslanie agenta, dostanú ich aj koncové body viazané na daného agenta.

Payload obsahuje iba ID, stav a časy: nikdy nie telo správy ani premenné či kontext hovoru a údaj to je redigovaný. Zvyšné údaje získate pomocou GET /v1/scheduled/{id}.

scheduled.skipped

Odosiela sa, keď sa odoslanie zámerne neodošle. Hodnota reason je expired (odoslanie sa nemohlo uskutočniť pred expires_at), opted_out (číslo je v zozname odhlásení, vrátane čísla pridaného po vytvorení odoslania), quiet_hours (čas odoslania nastal mimo 8:00 až 21:00 v časovom pásme príjemcu), sender_not_ready (číslo správy už nemôže odosielať) alebo outbound_tcpa_unconfirmed (čas hovoru nastal pred zaznamenaním potvrdenia TCPA organizácie).

{
  "data": {
    "agent_id": null,
    "created_at": "2026-11-01T18:02:11.204Z",
    "detail": "The send could not go out before its expires_at, so it was not sent late.",
    "expires_at": "2026-11-03T17:30:00Z",
    "external_id": "appointment-4815",
    "from_number": "+15551234567",
    "id": "6f1c0b8e-3a52-4c1f-9a0b-2f4f7d8a91c3",
    "reason": "expired",
    "send_at": "2026-11-03T17:00:00Z",
    "source": "api",
    "status": "skipped",
    "to": "[REDACTED]",
    "type": "sms"
  },
  "event_id": "2b0f6c43-74c9-4d43-a1f4-0d6a2f8e51a7",
  "type": "scheduled.skipped"
}

scheduled.failed

Odoslané, keď sa ThunderPhone pokúsil správu odoslať, ale nebola doručená. reason je vlastná chyba odoslania: chybový kód SMS, napríklad carrier_rejected pre textovú správu, alebo dôvod odmietnutia či zlyhania hovoru, napríklad pravidlo blokovanej cieľovej destinácie (premium_rate, napríklad) alebo agent_deleted. Užitočné zaťaženie má rovnaké polia ako scheduled.skipped.

PoleTypPopis
idstringID naplánovaného odoslania
typestringsms alebo call
statusstringskipped alebo failed
reasonstringDôvod, ako je uvedené vyššie; rovnaká hodnota ako status_reason odoslania
detailstringČitateľné vysvetlenie
sourcestringČo vytvorilo odoslanie: api
external_idstring | nullVáš kľúč pre odoslanie alebo null
from_numberstringOdosielajúce číslo
tostringVždy "[REDACTED]"
agent_idinteger | nullHovory: agent; textové správy: null
send_at, expires_at, created_attimestampISO 8601

Hlasové udalosti

Vytvorenie vlastného hlasu je asynchrónne. Tieto neblokujúce udalosti vám umožňujú reagovať na konečný výsledok namiesto pravidelného dopytovania koncového bodu podrobností klonu.

voice.ready a voice.failed sa doručujú len na koncový bod platný pre celú organizáciu s events: []. Nemožno ich vybrať ako explicitné filtre udalostí.

voice.ready

Odošle sa, keď sa spracovanie vlastného hlasu dokončí a hlas možno priradiť hlasovému agentovi.

{
  "data": {
    "voice": {
      "created_at": "2026-07-30T14:12:08.317Z",
      "display_name": "Support voice",
      "failure_reason": "",
      "gender": "female",
      "id": "cv_2f6f90b0e9a34ee8b39be7d1",
      "language": "en",
      "name": "custom:cv_2f6f90b0e9a34ee8b39be7d1",
      "status": "ready",
      "updated_at": "2026-07-30T14:13:31.605Z"
    }
  },
  "event_id": "2d5f0a61-e9b5-4a3c-b684-29d7d9e4b214",
  "type": "voice.ready"
}

voice.failed

Odošle sa, keď spracovanie vlastného hlasu skončí trvalým zlyhaním.

{
  "data": {
    "reason": "audio sample could not be processed",
    "voice": {
      "created_at": "2026-07-30T14:12:08.317Z",
      "display_name": "Support voice",
      "failure_reason": "audio sample could not be processed",
      "gender": "female",
      "id": "cv_2f6f90b0e9a34ee8b39be7d1",
      "language": "en",
      "name": "custom:cv_2f6f90b0e9a34ee8b39be7d1",
      "status": "failed",
      "updated_at": "2026-07-30T14:13:31.605Z"
    }
  },
  "event_id": "3493e985-1a75-4f77-a10a-e74af440cd31",
  "type": "voice.failed"
}
PoleTypPopis
voice.idreťazecVerejné ID vlastného hlasu
voice.namereťazecHodnota hlasu agenta vo formáte custom:<public_id>
voice.display_namereťazecNázov hlasu viditeľný pre organizáciu
voice.languagereťazecKód jediného jazyka klonu
voice.genderreťazecmale, female alebo prázdny reťazec
voice.statusreťazecready pre voice.ready; failed pre voice.failed
voice.failure_reasonreťazecPri úspechu prázdne; pri zlyhaní podrobnosti zlyhania spracovania
voice.created_at, voice.updated_atčasová pečiatkaČasové pečiatky ISO 8601
reasonreťazecPodrobnosti zlyhania; prítomné len pri voice.failed

Udalosti kvality

call.graded

Odosiela sa vždy, keď sa pre hovor dokončí beh hodnotenia AI. Neblokujúce.

{
  "data": {
    "call_id": 987654321,
    "grade": {
      "call_outcome": "success",
      "created_at": "2026-04-20T18:25:11.002Z",
      "detected_issues": [],
      "graded_at": "2026-04-20T18:25:11.002Z",
      "grader_model": "heuristic-v1",
      "id": 5512,
      "score": 92,
      "status": "completed",
      "summary": "Caller asked about their policy and got a full answer…"
    },
    "report": null
  },
  "event_id": "7c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
  "type": "call.graded"
}
PoleTypPopis
agent_idinteger | nullAgent, ktorý vybavil hovor, ak bol priradený
agent_namestring | nullAgent, ktorý vybavil hovor, ak bol priradený
grade.idintegerID hodnotenia
grade.scoreinteger | null0–100
grade.call_outcomestringsuccess, failure, unknown alebo no_conversation
grade.summarystringJednoparagrafové zhrnutie
grade.detected_issuesarrayReťazce problémov nájdených hodnotiteľom
grade.statusstringVždy completed — udalosti sa odosielajú iba pri dokončených spusteniach
grade.grader_modelstringKtorý hodnotiteľ vytvoril výsledok: heuristic-v1 (alebo iný hodnotiteľ ThunderPhone založený na pravidlách) pre rýchle predbežné hodnotenie, thunderphone-grader pre úplné hodnotenie. Ide o označenie ThunderPhone, nie o názov modelu AI
grade.graded_at, grade.created_attimestamp
reportobject | nullSpráva o hovore určená pre zákazníka: štítok výsledku, príznak a dôvod vyžadujúci pozornosť, volajúci, jednoriadkové zhrnutie, skúsenosť volajúceho. Pri skorom heuristickom hodnotení je null alebo správa pending, ktorej polia sú zástupné; udalosť úplného hodnotenia obsahuje dokončenú správu

call.data_extracted

Odosiela sa vždy, keď sa úspešne dokončí extrakcia štruktúrovaných údajov vrátane neskoršieho opakovaného pokusu po telephony.complete / web.complete alebo manuálneho opätovného spustenia cez POST /v1/calls/{call_id}/extract. Neblokujúce.

V režime blokujúcej extrakcie udalosť dokončenia zvyčajne čaká najviac na 75-sekundový rozpočet extrakcie. Ak sa proces extrakčného pracovníka stratí, produkčné dokončovacie vyprázdňovanie frontu (každých päť minút) uvoľní dokončenie, ktorého blocking_deadline_at uplynul, pred spustením ďalšieho pokusu o extrakciu. Neskorší úspech sa doručí samostatne ako táto udalosť.

{
  "data": {
    "call_id": 987654321,
    "agent_id": 12,
    "agent_name": "Acme intake",
    "extracted_data": {
      "status": "completed",
      "fields": {
        "customer_name": "Alex Morgan",
        "appointment_date": "2026-04-23"
      },
      "evidence": {
        "customer_name": {
          "quote": "My name is Alex Morgan",
          "speaker_role": "caller",
          "turn_index": 4
        },
        "appointment_date": {
          "quote": "April 23 works for me",
          "speaker_role": "caller",
          "turn_index": 7
        }
      },
      "verification": "verified",
      "field_reasons": {},
      "schema_version": "92850758e231a3c95a..."
    },
    "extracted_at": "2026-04-20T18:25:11.002Z",
    "model": "thunderphone-extractor",
    "summary": "Alex Morgan called to book a follow-up visit and confirmed Thursday, April 23."
  },
  "event_id": "4d79ef1d-c2b1-4ed6-85b8-8326bd2895ef",
  "type": "call.data_extracted"
}
PoleTypPopis
agent_idcelé číslo | nullHlasový agent, ktorý vybavil hovor, ak bol priradený
agent_namereťazec | nullHlasový agent, ktorý vybavil hovor, ak bol priradený
summaryreťazec | nullDokončený súhrn hovoru, keď má agent zapnuté Generovať súhrn hovoru, takže udalosť neskorej extrakcie doručí aj súhrn, ktorý nestihol okno dokončenia; inak null. Agenti so súhrnom, ale bez polí extrakcie, túto udalosť nikdy nevysielajú: neskorý súhrn načítajte z GET /v1/calls/{call_id}
extracted_data.statusreťazecPre túto udalosť vždy completed
extracted_data.fieldsobjektHodnoty kľúčované nakonfigurovanými kľúčmi polí extrakcie; nedostupné hodnoty sú null
extracted_data.evidenceobjektDôkazy kľúčované poľom extrakcie. Hodnota iná než null obsahuje presnú štrukturálne overenú citáciu (najviac 1 000 znakov), speaker_role (caller alebo agent) a turn_index; dlhšie citácie vrátené modelom sa namiesto skrátenia zamietnu a dôkaz je null vždy, keď je jeho pole null
extracted_data.verificationreťazecverified iba vtedy, keď nezávislé overenie dôkazov vrátilo presne jeden platný verdikt pre každé kandidátne pole. unavailable znamená, že overenie zlyhalo, vypršal mu čas, nemalo dostatočný rozpočet alebo vrátilo nesprávne formátovaný či neúplný výstup. Úplne nedostupné overenie zachová hodnoty štrukturálne podložené dôkazmi na kontrolu zákazníkom. Pri čiastočnom výstupe sa použijú platné verdikty a každé kandidátne pole bez presne jedného platného verdiktu sa nastaví na null
extracted_data.field_reasonsobjektDôvody kľúčované poľami, ktoré boli nastavené na null štrukturálnym podložením alebo nezávislým overovačom
extracted_data.schema_versionreťazecHaš presnej schémy polí použitej pri tejto extrakcii
extracted_atčasová pečiatkaČas dokončenia vo formáte ISO 8601
modelreťazecVždy thunderphone-extractor: označenie ThunderPhone pre extrakčný model, nie názov modelu AI

campaign.completed

Odosiela sa raz, keď sa kampaň presunie zo stavu running do stavu completed, či už sa jej harmonogram skončil alebo všetky kontakty dosiahli konečné stavy. Opakovania pracovníka neodosielajú ďalšiu udalosť. Táto udalosť životného cyklu na úrovni organizácie sa doručuje iba koncovým bodom s rozsahom organizácie, nie koncovým bodom s rozsahom hlasového agenta. Neblokujúce.

{
  "data": {
    "campaign_id": "3f6b2c9e-2a0d-4c63-b6d6-a708dc98f403",
    "name": "May win-back",
    "agent_id": 12,
    "status": "completed",
    "started_at": "2026-04-20T17:00:00Z",
    "completed_at": "2026-04-20T18:25:11Z",
    "counts": {
      "contacts_total": 150,
      "completed": 121,
      "failed": 11,
      "no_answer": 18,
      "skipped": 4,
      "remaining": 0
    }
  },
  "event_id": "8d8f52ce-6b46-423f-9dde-cea0b91ec135",
  "type": "campaign.completed"
}

Štyri počty výsledkov sa navzájom neprekrývajú a ich súčet sa rovná contacts_total: completed obsahuje úspešné kontakty; no_answer obsahuje kontakty v konečnom stave zlyhania alebo vyčerpania, ktorých konečným výsledkom bolo nezodpovedanie; failed obsahuje všetky ostatné kontakty v konečnom stave zlyhania alebo vyčerpania; a remaining obsahuje čakajúce, naplánované alebo práve vytáčané kontakty. Kontakt čakajúci na opakovaný pokus je remaining, aj keď jeho posledný pokus skončil nezodpovedaním. Prebiehajúce hovory sa zosúladia pred jednorazovým snímkom dokončenia. started_at je nakonfigurovaný začiatok kampane alebo čas vytvorenia kampane, ak nebol nakonfigurovaný začiatok. skipped nie je piata kategória: počíta kontakty v rámci failed, ktoré filter typu čísla ukončil bez hovoru.

issue.reported

Odosiela sa pri vytvorení hlásenia problému — buď ho používateľ odošle z ovládacieho panela (source: "user"), alebo ho automaticky vytvorí hodnotenie hovoru (source: "system"). Neblokujúce.

{
  "data": {
    "call_id": 987654321,
    "issue_report": {
      "created_at": "2026-04-20T18:25:11.002Z",
      "description": "Five-second silence before responding to the main question.",
      "id": 4321,
      "severity": "warning",
      "source": "system",
      "status": "open",
      "title": "Agent paused too long"
    }
  },
  "event_id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b",
  "type": "issue.reported"
}
PoleTypPopis
agent_idinteger | nullHlasový agent, ktorý spracoval hovor, ak bol priradený
agent_namestring | nullHlasový agent, ktorý spracoval hovor, ak bol priradený
issue_report.severitystringcritical, warning alebo info
issue_report.statusstringopen alebo resolved
issue_report.sourcestringuser (odoslané z ovládacieho panela) alebo system (vytvorené hodnotením)

issue.escalated

Odosiela sa, keď je vzor problému odoslaný do ThunderPhone na kontrolu tímom: po výbere možnosti Nahlásiť ThunderPhone, alebo keď funkcia Opraviť pomocou AI nemôže potvrdiť opravu na strane zákazníka a problém automaticky presmeruje. Túto udalosť dostávajú iba koncové body pre celú organizáciu.

{
  "data": {
    "automatic": false,
    "cluster_id": "7ac2844c-2df0-4fa8-a560-7378da649e19",
    "escalation_id": "ec99f52b-c8c0-41dd-a4f2-dd8a07b10894",
    "status": "open"
  },
  "event_id": "d8f8f420-7a42-45ba-bcf1-b747f9bbecda",
  "type": "issue.escalated"
}
PoleTypPopis
automaticbooleantrue pre automatickú eskaláciu; false pre manuálnu eskaláciu
cluster_idUUIDEskalovaný vzor problému
escalation_idUUIDZáznam eskalácie
statusstringopen pri odoslaní udalosti

Ide o upozornenie, nie o balík dôkazov. Pomocou cluster_id ho prepojte so vzorom problému. Pozrite si Nahlásiť ThunderPhone.


Udalosti testovacích hovorov

test-call.completed

Odosiela sa, keď spustenie testovacieho hovoru dosiahne koncový stav — completed alebo failed, vrátane spustení, ktoré zlyhali pri spustení a nikdy nevytvorili hovor. Neblokujúce. Užitočné na prepojenie dávkových spustení CI so systémami chatu alebo notifikácií.

{
  "data": {
    "test_call_run": {
      "call_id": 987654321,
      "completed_at": "2026-04-20T18:25:04.822Z",
      "error_message": "",
      "id": 7110,
      "status": "completed",
      "target_id": 12,
      "target_type": "agent"
    }
  },
  "event_id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
  "type": "test-call.completed"
}
PoleTypPopis
agent_idinteger | nullAgent, ktorý spracoval hovor, ak bol priradený
agent_namestring | nullAgent, ktorý spracoval hovor, ak bol priradený
test_call_run.target_typestringagent alebo phone_number
test_call_run.target_idintegerID agenta alebo telefónneho čísla, na ktoré bolo spustenie zacielené, podľa target_type
test_call_run.statusstringcompleted alebo failed
test_call_run.call_idinteger | nullnull, ak spustenie zlyhalo pred uskutočnením hovoru
test_call_run.error_messagestringPri úspechu je prázdne

Udalosti upozornení

alert.triggered

Odosiela sa, keď pravidlo upozornenia so zapnutým kanálom Doručiť do webhookov vývojára prekročí svoju prahovú hodnotu. Neblokujúce. Pravidlo sa spustí raz a potom rešpektuje čas ochladenia, takže trvajúce prekročenie vytvorí jednu udalosť na každé okno ochladenia.

{
  "data": {
    "comparator": "lt",
    "event_id": "b8e6a1d4-2c3f-4a5b-9c8d-7e6f5a4b3c2d",
    "fired_at": "2026-04-20T18:00:00+00:00",
    "metric": "success_rate",
    "metric_value": 71.4,
    "rule_id": "d2c3b4a5-6f7e-4d8c-9b0a-1c2d3e4f5a6b",
    "rule_name": "Success rate below 80%",
    "threshold": 80.0,
    "window_hours": 24
  },
  "event_id": "4d5e6f7a-8b9c-4d0e-9f1a-2b3c4d5e6f7a",
  "type": "alert.triggered"
}
PoleTypPopis
event_id (v data)UUIDID spustenia upozornenia — odlišné od event_id doručenia v obálke
rule_id, rule_nameUUID, stringPravidlo, ktoré sa spustilo
metricstringsuccess_rate, failure_rate, avg_score, call_volume alebo suite_regression
comparatorstringlt, lte, gt alebo gte
metric_valuenumberHodnota metriky v rámci okna, keď sa pravidlo spustilo
thresholdnumberNakonfigurovaná prahová hodnota
window_hoursintegerPosuvné vyhodnocovacie okno
fired_attimestamp

Informácie o vytváraní pravidiel, metrikách, časoch ochladenia a kanáloch e-mailu / Slack nájdete v príručke upozornení.


Udalosti telefónneho čísla

phone_number.spam_risk_changed

Odosiela sa, keď monitorovanie označení spamu (platený doplnok dostupný na požiadanie prostredníctvom podpory) zistí, že riziko spamu monitorovaného čísla vzrástlo na medium alebo high (z low, ak ešte neexistuje žiadne meranie, alebo z medium na high). Nejde o blokujúcu udalosť. Číslo, ktoré zostane označené, sa znova neodošle; číslo, ktorého riziko klesne na low a neskôr je opäť označené, sa odošle. Udalosť nemá kontext agenta, preto ju prijímajú iba koncové body pre celú organizáciu. Vlastníci a administrátori organizácie dostanú aj e-mail.

{
  "data": {
    "checked_at": "2026-10-21T14:41:07+00:00",
    "phone_number": "+13125550100",
    "phone_number_id": 412,
    "previous_spam_risk": "low",
    "scores": {
      "connection": 31,
      "engagement": 40,
      "maturity": 82,
      "sentiment": 22
    },
    "spam_category": "Telemarketer",
    "spam_risk": "high"
  },
  "event_id": "6f1c2d3e-4b5a-4c6d-8e7f-9a0b1c2d3e4f",
  "type": "phone_number.spam_risk_changed"
}
PoleTypPopis
phone_numberreťazecČíslo vo formáte E.164
phone_number_idcelé číslo | nullJeho ID v sekcii Telefónne čísla
spam_riskreťazecmedium alebo high
previous_spam_riskreťazec | nullRiziko pri poslednom meraní, pred prvým meraním null
spam_categoryreťazec | nullOznačenie, ktoré môžu zobrazovať operátori, napríklad Telemarketer alebo Survey. Považujte ho za voľný text
scoresobjektKaždé skóre je od 0 do 100 alebo null, kým nie je dostatočný objem hovorov: maturity (ako dlho je číslo zavedené), connection (či ľudia odpovedajú), engagement (či zostávajú na linke), sentiment (či ho blokujú alebo nahlasujú)
checked_atčasová pečiatkaČas, keď ThunderPhone načítal výsledok

Udalosti migrácie

migration.call.complete

Odosiela sa po skončení hovoru uskutočneného prostredníctvom POST /v1/migrations/{id}/calls, bez ohľadu na to, ktorá platforma hovor prijala. Neblokuje vykonávanie. Doručí sa približne do 5 minút po skončení hovoru. data obsahuje všetky polia z telephony.complete a blok migration. Hovor uskutočnený službou ThunderPhone tiež ako zvyčajne odošle telephony.complete s rovnakým call_id. Pre hovor prijatý druhou platformou má answered_by hodnotu null. Hovor na druhej platforme, ktorý sa neskončil ani po 2 hodinách alebo ktorého migrácia sa dokončila či najprv stratila kľúč, sa odošle so status: "unknown" a bez prepisu.

{
  "data": {
    "agent_id": 42,
    "agent_name": "Front desk",
    "answered_by": null,
    "billable_minutes": null,
    "billing_total_cents": null,
    "call_id": null,
    "direction": "outbound",
    "duration_seconds": 94,
    "end_reason": "user_hangup",
    "end_time": "2026-10-06T17:01:34+00:00",
    "extracted_data": null,
    "from_number": "+15551234567",
    "migration": {
      "arm": "vendor",
      "id": "5f0c2a9e-7b1d-4c3e-8a6f-2d9e1b4c7a30",
      "metadata": {
        "lead_id": "8812"
      },
      "routing_id": "9b2f8c1e-4d3a-4f6b-8e2d-1a7c5b9e0f34",
      "vendor": "retell",
      "vendor_call_id": "call_6a1f0e",
      "vendor_cost_usd": "0.1240"
    },
    "product": "",
    "recording_mode": "vendor",
    "recording_url": "https://…",
    "start_time": "2026-10-06T17:00:00+00:00",
    "status": "completed",
    "summary": "The callee booked a table for two on Thursday.",
    "thunderphone_retained_call_content": true,
    "to_number": "+14155552671",
    "transcripts": [
      {
        "content": "Hi Ada, this is Rosa's calling about your booking.",
        "role": "agent"
      },
      {
        "content": "Yes, Thursday works.",
        "role": "user"
      }
    ],
    "transfer_number": null,
    "unresolved_variables": [],
    "variables": {
      "first_name": "Ada"
    },
    "voice": ""
  },
  "event_id": "7c1e2f3a-4b5c-4d6e-8f7a-9b0c1d2e3f4a",
  "type": "migration.call.complete"
}
PoleTypPopis
migration.idUUIDMigrácia
migration.routing_idUUIDSmerovaný hovor, ako bol vrátený pri jeho iniciovaní
migration.armstringours (inicioval ho ThunderPhone) alebo vendor (iniciovala ho druhá platforma)
migration.vendorstringretell, vapi, elevenlabs alebo bland
migration.vendor_call_idstring | nullID hovoru druhej platformy; pre ours je null
migration.metadataobjectHodnota metadata, ktorú ste odoslali pri iniciovaní hovoru
migration.vendor_cost_usdstring | nullNáklady na hovor nahlásené druhou platformou, ak ich poskytla
call_idinteger | nullID hovoru ThunderPhone; pre vendor je null
statusstringPre vendor: completed, keď volaný hovoril, failed, keď nehovoril, unknown podľa vyššie uvedeného. Pre ours: ako v telephony.complete

Pre hovor vendor ThunderPhone nemá údaje o účtovaní ani extrakcii: billable_minutes, billing_total_cents a extracted_data sú null, product a voice sú prázdne, recording_mode je vendor a recording_url je odkaz druhej platformy, ak ho poskytla.

migration.rollback

Odosiela sa, keď postupné prepínanie migrácie samo presmeruje všetky hovory späť na druhú platformu: 3 hovory sa nedokázali pripojiť k ThunderPhone do 15 minút, 2 hovory odoslané do ThunderPhone sa skončili pred odpoveďou agenta alebo miera úspešnosti výsledkov úloh ThunderPhone klesla voči druhej platforme o viac než nakonfigurovaný rozdiel. Neblokujúce, raz pri každom vrátení späť. Potom je podiel ThunderPhone 0 % a migrácia je pozastavená, kým ju niekto neobnoví na karte Migrácia agenta. Údaje neobsahujú telefónne čísla, prepisy ani ID hovorov.

{
  "data": {
    "agent_id": 42,
    "agent_name": "Front desk",
    "dropped": 0,
    "migration_id": "5f0c2a9e-7b1d-4c3e-8a6f-2d9e1b4c7a30",
    "ours": {
      "graded": 20,
      "success_rate": 0.8
    },
    "ours_failed": 3,
    "ours_percent": 0,
    "previous_percent": 25,
    "reason": "ours_failed_burst",
    "rolled_back_at": "2026-10-10T12:05:00+00:00",
    "step": 1,
    "theirs": {
      "graded": 20,
      "success_rate": 0.8
    },
    "vendor": "retell"
  },
  "event_id": "3d1f6b2a-8c4e-5a7b-9d0e-2f1a3b4c5d6e",
  "type": "migration.rollback"
}
PoleTypPopis
migration_idUUIDMigrácia
vendorstringretell, vapi, elevenlabs alebo bland
reasonstringours_failed_burst (3 neúspešné pripojenia za 15 minút), dropped_calls (2 hovory sa skončili pred odpoveďou agenta do 30 minút) alebo rate_gap (rozdiel v miere výsledkov úloh pri aspoň rollback_min_calls vyhodnotených hovoroch na každej strane)
previous_percentintegerPodiel hovorov ThunderPhone pred vrátením späť
ours_percentintegerVždy 0
stepinteger | nullKrok harmonogramu, na ktorom sa nachádzala (indexované od 0)
ours / theirsobject | nullVyhodnotené hovory v aktuálnom kroku a ich miera úspešnosti; theirs môže obsahovať údaje za posledných 30 dní, keď má krok príliš málo hovorov. null, keď žiadne neboli
ours_failedintegerNeúspešné pripojenia započítané za posledných 15 minút
droppedintegerHovory započítané ako prerušené za posledných 30 minút
rolled_back_attimestamp

Súvisiace