Open in
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_idna 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"
}| Pole | Typ | Popis |
|---|---|---|
agent_id | integer | null | Agent, ktorý hovor spracoval, ak bol priradený |
agent_name | string | null | Agent, ktorý hovor spracoval, ak bol priradený |
returning_call | object | Prí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_headers | object | Prí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.
| Pole | Typ | Popis |
|---|---|---|
agent_id | integer | null | Agent, ktorý vybavil hovor, ak bol priradený |
agent_name | string | null | Agent, 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>"}.
| Pole | Typ | Popis |
|---|---|---|
agent_id | integer | null | Agent, ktorý vybavil hovor, ak bol priradený |
agent_name | string | null | Agent, 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"
}| Pole | Typ | Popis |
|---|---|---|
agent_id | integer | null | Agent, ktorý vybavil hovor, ak bol priradený |
agent_name | string | null | Agent, ktorý vybavil hovor, ak bol priradený |
position | integer | Index repliky v histórii hovoru — stabilný identifikátor na určovanie poradia |
role | string | assistant (reč agenta) alebo user (reč volajúceho) |
text | string | Text prepisu repliky, ako je známy v čase odoslania |
entry_type | string | Typ podkladového záznamu histórie: completion (agent) alebo user_turn / span (volajúci) |
start_ms, end_ms | integer | Posuny 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.
| Pole | Typ | Popis |
|---|---|---|
agent_id | integer | null | Agent, ktorý vybavil hovor, ak bol priradený |
agent_name | string | null | Agent, 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".
| Pole | Typ | Popis |
|---|---|---|
agent_id | integer | null | Agent, ktorý vybavil hovor, ak bol priradený |
agent_name | string | null | Agent, ktorý vybavil hovor, ak bol priradený |
web.tool
Ekvivalent telephony.tool pre webový kanál. data obsahuje
origin_domain namiesto from_number / to_number.
| Pole | Typ | Popis |
|---|---|---|
agent_id | integer | null | Agent, ktorý vybavil hovor, ak bol priradený |
agent_name | string | null | Agent, 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.
| Pole | Typ | Popis |
|---|---|---|
agent_id | integer | null | Agent, ktorý vybavil hovor, ak bol priradený |
agent_name | string | null | Agent, 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"
}| Pole | Typ | Popis |
|---|---|---|
call_id | integer | Hovor, ktorý bol prepojený |
agent_id | integer | null | Agent, ktorý spracoval hovor, ak bol priradený |
agent_name | string | null | Agent, ktorý spracoval hovor, ak bol priradený |
transfer_outcome | string | refer_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 |
destination | string | null | Číslo, na ktoré bol hovor prepojený |
sip_status | integer | null | Stav 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_kind | string | null | Len pri bridged: cold_fallback (odmietnuté studené prepojenie, ktoré ThunderPhone pripojil) alebo warm (dve osoby pri teplom prepojení po odchode agenta) |
bridge_seconds | integer | null | Len pri bridged: čas premostenia, ktorý ThunderPhone vyúčtoval, v sekundách |
bridge_total_cents | integer | null | Len 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"
}| Pole | Typ | Popis |
|---|---|---|
call_id | celé číslo | Hovor, ktorý bol účtovaný |
agent_id | celé číslo | null | Agent, ktorý spracoval hovor, ak bol priradený |
agent_name | reťazec | null | Agent, ktorý spracoval hovor, ak bol priradený |
reason | reťazec | settled: platba za hovor. adjusted: údaje o využití prijaté po platbe ju zvýšili (platba sa nikdy neznižuje) |
billing_seq | celé číslo | 1 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_cents | celé číslo | Vš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_cents | celé číslo | null | Iba 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"
}| Pole | Typ | Popis |
|---|---|---|
call_id | celé číslo | Hovor |
agent_id | celé číslo | null | Hlasový agent, ktorý vybavil hovor, ak bol priradený |
agent_name | reťazec | null | Hlasový agent, ktorý vybavil hovor, ak bol priradený |
direction | reťazec | Smer hovoru, ako v objekte hovoru |
status | reťazec | Fáza, ktorú hovor dosiahol; pozrite si tabuľku nižšie |
occurred_at | časová pečiatka | Kedy sa to stalo |
hold_seconds | celé číslo | null | Iba pre off_hold: ako dlho trvalo podržanie v sekundách. null pre každý iný stav |
status | Kedy sa odosiela |
|---|---|
dialing | Odchá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ú |
answered | Odchá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 |
voicemail | Odchá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_hold | Hlasový agent bol prepnutý do podržania a potichu čaká (nástroj wait_on_hold) |
off_hold | Osoba 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.
| Pole | Typ | Popis |
|---|---|---|
id | string | ID naplánovaného odoslania |
type | string | sms alebo call |
status | string | skipped alebo failed |
reason | string | Dôvod, ako je uvedené vyššie; rovnaká hodnota ako status_reason odoslania |
detail | string | Čitateľné vysvetlenie |
source | string | Čo vytvorilo odoslanie: api |
external_id | string | null | Váš kľúč pre odoslanie alebo null |
from_number | string | Odosielajúce číslo |
to | string | Vždy "[REDACTED]" |
agent_id | integer | null | Hovory: agent; textové správy: null |
send_at, expires_at, created_at | timestamp | ISO 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"
}| Pole | Typ | Popis |
|---|---|---|
voice.id | reťazec | Verejné ID vlastného hlasu |
voice.name | reťazec | Hodnota hlasu agenta vo formáte custom:<public_id> |
voice.display_name | reťazec | Názov hlasu viditeľný pre organizáciu |
voice.language | reťazec | Kód jediného jazyka klonu |
voice.gender | reťazec | male, female alebo prázdny reťazec |
voice.status | reťazec | ready pre voice.ready; failed pre voice.failed |
voice.failure_reason | reťazec | Pri úspechu prázdne; pri zlyhaní podrobnosti zlyhania spracovania |
voice.created_at, voice.updated_at | časová pečiatka | Časové pečiatky ISO 8601 |
reason | reťazec | Podrobnosti 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"
}| Pole | Typ | Popis |
|---|---|---|
agent_id | integer | null | Agent, ktorý vybavil hovor, ak bol priradený |
agent_name | string | null | Agent, ktorý vybavil hovor, ak bol priradený |
grade.id | integer | ID hodnotenia |
grade.score | integer | null | 0–100 |
grade.call_outcome | string | success, failure, unknown alebo no_conversation |
grade.summary | string | Jednoparagrafové zhrnutie |
grade.detected_issues | array | Reťazce problémov nájdených hodnotiteľom |
grade.status | string | Vždy completed — udalosti sa odosielajú iba pri dokončených spusteniach |
grade.grader_model | string | Ktorý 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_at | timestamp | |
report | object | null | Sprá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"
}| Pole | Typ | Popis |
|---|---|---|
agent_id | celé číslo | null | Hlasový agent, ktorý vybavil hovor, ak bol priradený |
agent_name | reťazec | null | Hlasový agent, ktorý vybavil hovor, ak bol priradený |
summary | reťazec | null | Dokonč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.status | reťazec | Pre túto udalosť vždy completed |
extracted_data.fields | objekt | Hodnoty kľúčované nakonfigurovanými kľúčmi polí extrakcie; nedostupné hodnoty sú null |
extracted_data.evidence | objekt | Dô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.verification | reťazec | verified 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_reasons | objekt | Dôvody kľúčované poľami, ktoré boli nastavené na null štrukturálnym podložením alebo nezávislým overovačom |
extracted_data.schema_version | reťazec | Haš presnej schémy polí použitej pri tejto extrakcii |
extracted_at | časová pečiatka | Čas dokončenia vo formáte ISO 8601 |
model | reťazec | Vž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"
}| Pole | Typ | Popis |
|---|---|---|
agent_id | integer | null | Hlasový agent, ktorý spracoval hovor, ak bol priradený |
agent_name | string | null | Hlasový agent, ktorý spracoval hovor, ak bol priradený |
issue_report.severity | string | critical, warning alebo info |
issue_report.status | string | open alebo resolved |
issue_report.source | string | user (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"
}| Pole | Typ | Popis |
|---|---|---|
automatic | boolean | true pre automatickú eskaláciu; false pre manuálnu eskaláciu |
cluster_id | UUID | Eskalovaný vzor problému |
escalation_id | UUID | Záznam eskalácie |
status | string | open 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"
}| Pole | Typ | Popis |
|---|---|---|
agent_id | integer | null | Agent, ktorý spracoval hovor, ak bol priradený |
agent_name | string | null | Agent, ktorý spracoval hovor, ak bol priradený |
test_call_run.target_type | string | agent alebo phone_number |
test_call_run.target_id | integer | ID agenta alebo telefónneho čísla, na ktoré bolo spustenie zacielené, podľa target_type |
test_call_run.status | string | completed alebo failed |
test_call_run.call_id | integer | null | null, ak spustenie zlyhalo pred uskutočnením hovoru |
test_call_run.error_message | string | Pri ú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"
}| Pole | Typ | Popis |
|---|---|---|
event_id (v data) | UUID | ID spustenia upozornenia — odlišné od event_id doručenia v obálke |
rule_id, rule_name | UUID, string | Pravidlo, ktoré sa spustilo |
metric | string | success_rate, failure_rate, avg_score, call_volume alebo suite_regression |
comparator | string | lt, lte, gt alebo gte |
metric_value | number | Hodnota metriky v rámci okna, keď sa pravidlo spustilo |
threshold | number | Nakonfigurovaná prahová hodnota |
window_hours | integer | Posuvné vyhodnocovacie okno |
fired_at | timestamp |
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"
}| Pole | Typ | Popis |
|---|---|---|
phone_number | reťazec | Číslo vo formáte E.164 |
phone_number_id | celé číslo | null | Jeho ID v sekcii Telefónne čísla |
spam_risk | reťazec | medium alebo high |
previous_spam_risk | reťazec | null | Riziko pri poslednom meraní, pred prvým meraním null |
spam_category | reťazec | null | Označenie, ktoré môžu zobrazovať operátori, napríklad Telemarketer alebo Survey. Považujte ho za voľný text |
scores | objekt | Kaž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"
}| Pole | Typ | Popis |
|---|---|---|
migration.id | UUID | Migrácia |
migration.routing_id | UUID | Smerovaný hovor, ako bol vrátený pri jeho iniciovaní |
migration.arm | string | ours (inicioval ho ThunderPhone) alebo vendor (iniciovala ho druhá platforma) |
migration.vendor | string | retell, vapi, elevenlabs alebo bland |
migration.vendor_call_id | string | null | ID hovoru druhej platformy; pre ours je null |
migration.metadata | object | Hodnota metadata, ktorú ste odoslali pri iniciovaní hovoru |
migration.vendor_cost_usd | string | null | Náklady na hovor nahlásené druhou platformou, ak ich poskytla |
call_id | integer | null | ID hovoru ThunderPhone; pre vendor je null |
status | string | Pre 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"
}| Pole | Typ | Popis |
|---|---|---|
migration_id | UUID | Migrácia |
vendor | string | retell, vapi, elevenlabs alebo bland |
reason | string | ours_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_percent | integer | Podiel hovorov ThunderPhone pred vrátením späť |
ours_percent | integer | Vždy 0 |
step | integer | null | Krok harmonogramu, na ktorom sa nachádzala (indexované od 0) |
ours / theirs | object | null | Vyhodnotené 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_failed | integer | Neúspešné pripojenia započítané za posledných 15 minút |
dropped | integer | Hovory započítané ako prerušené za posledných 30 minút |
rolled_back_at | timestamp |
Súvisiace
Blokujúci payload prichádzajúceho hovoru, na ktorý musíte odpovedať.
Prepis a metriky po hovore.
Prihláste URL na odber podmnožiny týchto udalostí.
Ako sa generujú udalosti telephony.tool / web.tool.