Open in
Katalog dogodkov
Vse vrste dogodkov spletnih kavljev, ki jih oddaja ThunderPhone.
Vsako telo spletne kljuke ima polje type, katerega vrednost je ena od vrst
dogodkov na tej strani. Ko se naročite na
končno točko, mora polje events vsebovati želene
vrste dogodkov (ali pa biti prazno za naročanje na vse —
razen dogodkov za posamezen korak telephony.turn /
web.turn in dogodka napredka v živo
call.status_changed, ki se dostavljajo samo
končnim točkam, ki jih izrecno navedejo).
Te dogodke prenašata dva načina dostave:
- Dostave končni točki so vedno neblokirajoča obvestila
s ponovnimi poskusi: odgovorite s
katerim koli odgovorom 2xx; ovojnica vsebuje
event_idza odstranjevanje podvojenih dogodkov. - Blokirajoče izmenjave se izvajajo samo prek
podedovanega webhooka z enim URL-jem: zahteva za
konfiguracijo
telephony.incoming/web.incoming(številke v načinu webhook: 13 s, vključno z enim ponovnim poskusom; ključi gradnika v načinu webhook: 10 s) in odprema orodja v načinu webhook. Vaš odgovor oblikuje klic v živo.
Spodnji primeri koristnih podatkov prikazujejo ovojnico končne točke v vrstnem redu prenosa (ključi so razvrščeni po abecedi: data, event_id, type); podedovane dostave vsebujejo enake data brez event_id.
Dogodki klicev
telephony.incoming
Poslano, ko dohodni klic doseže eno od vaših
telefonskih številk. Dostave na končno točko so
obvestila »fire-and-forget«, poslana za vsak dohodni klic, ne glede na to,
ali je številka konfigurirana za agenta ali webhook. Številke brez
dodeljenega agenta dodatno prejmejo blokirajočo zahtevo za konfiguracijo
na podedovanem webhooku — za celotno shemo zahteve/odgovora glejte
telephony.incoming / web.incoming.
{
"data": {
"call_id": 987654321,
"from_number": "+14155550199",
"to_number": "+15551234567"
},
"event_id": "3f6b2ad0-1c9e-4a57-9f2b-8f6f0f9d2f11",
"type": "telephony.incoming"
}| Polje | Vrsta | Opis |
|---|---|---|
agent_id | celo število | null | Agent, ki je obravnaval klic, kadar je bil dodeljen |
agent_name | niz | null | Agent, ki je obravnaval klic, kadar je bil dodeljen |
returning_call | objekt | Prisotno samo, kadar je številka tega klicatelja poklicala v zadnjih 30 dneh: call_id, agent_id, started_at in outcome prejšnjega klica. Glejte Povratni klici |
sip_headers | objekt | Prisotno samo, kadar je klic prispel z glavami SIP X-* ali User-to-User (naslovi SIP in ročne povezave SIP): ime glave z malimi črkami → vrednost. Glejte glave SIP |
telephony.complete
Poslano ob koncu dohodnega ali odhodnega telefonskega klica. Neblokirajoče.
Vključuje prepis, URL posnetka, kadar je na voljo, in povzetek obračunavanja. Za
shemo koristnega tovora glejte
telephony.complete / web.complete.
| Polje | Vrsta | Opis |
|---|---|---|
agent_id | integer | null | Agent, ki je obravnaval klic, kadar je bil dodeljen |
agent_name | string | null | Agent, ki je obravnaval klic, kadar je bil dodeljen |
telephony.tool
Poslano, ko telefonski klic prikliče
orodje funkcije. Neblokirajoče obvestilo za revizijo —
orodje je že izvedeno, ko je ta dogodek dostavljen; zajema
vaša lastna orodja funkcij in vgrajeno orodje send_sms (ne drugih vgrajenih
orodij, orodij zbirke znanja, povezav aplikacij ali orodij MCP). Za send_sms
sta arguments.to in arguments.body oba [REDACTED]. Tudi prepisi ob
zaključku ju prikrijejo; vsebino in prejemnika pridobite iz vira SMS na ravni
organizacije z uporabo message_id iz odgovora.
{
"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 rezultat izvedbe: {"status": <http status>, "response": <your endpoint's JSON>} ob uspehu ali
{"status": <status>, "error": "<message>"} ob napaki.
| Polje | Vrsta | Opis |
|---|---|---|
agent_id | integer | null | Agent, ki je obravnaval klic, kadar je bil dodeljen |
agent_name | string | null | Agent, ki je obravnaval klic, kadar je bil dodeljen |
telephony.turn
Poslano med potekajočim telefonskim klicem, enkrat za vsak
govorni obrat, ko se zgodi — izgovorjeni zaključki agenta in
prepisani obrati klicatelja. Omogoča spremljanje pogovora v živo prek
navadnih webhookov namesto anketiranja
GET /v1/calls/{call_id}/transcript.
Neblokirajoče.
{
"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"
}| Polje | Vrsta | Opis |
|---|---|---|
agent_id | integer | null | Agent, ki je obravnaval klic, kadar je bil dodeljen |
agent_name | string | null | Agent, ki je obravnaval klic, kadar je bil dodeljen |
position | integer | Indeks obrata v zgodovini klica — stabilna identiteta za razvrščanje |
role | string | assistant (govor agenta) ali user (govor klicatelja) |
text | string | Besedilo prepisa obrata, kot je znano ob času pošiljanja |
entry_type | string | Vrsta osnovnega vnosa v zgodovini: completion (agent) ali user_turn / span (klicatelj) |
start_ms, end_ms | integer | Zvočni odmiki v ms od začetka klica; prisotni le, kadar je bil čas predvajanja ob času pošiljanja že znan |
web.incoming
Ekvivalent telephony.incoming za spletni kanal, poslan ob začetku seje
spletnega gradnika ali preskusnega klica z mikrofonom v gradniku.
Dostave na končno točko so obvestila »fire-and-forget« za vsako spletno sejo.
Objavljivi ključi v mode="webhook" dodatno prejmejo
blokirajočo zahtevo za konfiguracijo na podedovanem webhooku — ta
blokirajoča zahteva ima drugačno obliko (origin_domain,
publishable_key_prefix; brez telefonskih številk). Glejte
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 je vedno dobesedna vrednost "web". Za seje gradnika v načinu
webhook je to_number prazen (številka agenta seje se dodeli po
konfiguraciji); za preskusne klice z mikrofonom v gradniku sta origin_domain
in publishable_key_prefix prazna.
| Polje | Vrsta | Opis |
|---|---|---|
agent_id | integer | null | Agent, ki je obravnaval klic, kadar je bil dodeljen |
agent_name | string | null | Agent, ki je obravnaval klic, kadar je bil dodeljen |
web.complete
Ekvivalent telephony.complete za spletni kanal, ki zajema klice
spletnega gradnika (direction: "web") in preskusne klice z mikrofonom v gradniku
(direction: "test"). Neblokirajoče. Enaka oblika koristnega tovora kot pri
telephony.complete, dodatno z origin_domain
in z from_number, nastavljenim na "web".
| Polje | Vrsta | Opis |
|---|---|---|
agent_id | integer | null | Agent, ki je obravnaval klic, kadar je bil dodeljen |
agent_name | string | null | Agent, ki je obravnaval klic, kadar je bil dodeljen |
web.tool
Ekvivalent telephony.tool za spletni kanal. data vsebuje
origin_domain namesto from_number / to_number.
| Polje | Vrsta | Opis |
|---|---|---|
agent_id | integer | null | Agent, ki je obravnaval klic, kadar je bil dodeljen |
agent_name | string | null | Agent, ki je obravnaval klic, kadar je bil dodeljen |
web.turn
Ekvivalent telephony.turn za spletni kanal, ki zajema
klice spletnega gradnika in preskusne klice z mikrofonom v gradniku. Enaka
oblika koristnega tovora, z origin_domain namesto from_number / to_number.
Tako kot telephony.turn zahteva izrecno naročnino — nikoli ni
dostavljen prek praznega polja events.
| Polje | Vrsta | Opis |
|---|---|---|
agent_id | integer | null | Agent, ki je obravnaval klic, kadar je bil dodeljen |
agent_name | string | null | Agent, ki je obravnaval klic, kadar je bil dodeljen |
call.transfer_completed
Pošlje se enkrat za vsak klic s končnim izidom
prenosa klica: hladnega prenosa ali povezave med osebama,
ki po toplem prenosu ostane, ko agent zapusti klic.
Neblokirajoče in dostavljeno samo končnim točkam (nikoli starejšemu
webhooku z enim URL-jem). Prispe po telephony.complete klica:
ko ponudnik prevzame klic ali prenos ne uspe oziroma, ko
ThunderPhone vzpostavi povezavo, po njenem koncu.
{
"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"
}| Polje | Vrsta | Opis |
|---|---|---|
call_id | integer | Klic, ki je bil preusmerjen |
agent_id | integer | null | Agent, ki je obravnaval klic, če je bil dodeljen |
agent_name | string | null | Agent, ki je obravnaval klic, če je bil dodeljen |
transfer_outcome | string | refer_accepted: ponudnik je prevzel klic. bridged: ThunderPhone je sam ohranil povezavo med klicateljem in ciljno številko, ker je ponudnik zavrnil hladni prenos ali ker je agent pri toplem prenosu zapustil klic. bridge_unanswered: ponudnik je zavrnil hladni prenos, ciljna številka pa se ni oglasila na klic, ki ga je vzpostavil ThunderPhone. failed: prenos ni uspel in klic se je končal |
destination | string | null | Številka, na katero je bil klic preusmerjen |
sip_status | integer | null | SIP-stanje ponudnika, ko je zavrnil hladni prenos: 403 (na primer povezava Twilio brez prenosa klicev), 405 ali 501. null, kadar ga ponudnik ni zavrnil |
bridge_kind | string | null | Samo za bridged: cold_fallback (zavrnjeni hladni prenos, ki ga je povezal ThunderPhone) ali warm (dve osebi pri toplem prenosu po odhodu agenta) |
bridge_seconds | integer | null | Samo za bridged: čas povezave, ki ga je ThunderPhone zaračunal, v sekundah |
bridge_total_cents | integer | null | Samo za bridged: strošek povezave v ameriških centih po upoštevanju morebitnega brezplačnega dobroimetja za klice, zaračunan ločeno od billing_total_cents klica |
Iste vrednosti so v objektu klica
kot transfer_outcome, transfer_destination, transfer_sip_status,
transfer_bridge_kind, transfer_bridge_seconds in
transfer_bridge_total_cents. event_id je enak pri vsaki dostavi
za klic, zato ponovljeno poročilo nikoli ne ustvari drugega dogodka.
call.billed
Poslano za klic, zaračunan glede na merjeno porabo: ko je njegov strošek
dokončno obračunan, nekaj minut po koncu klica, ko je poraba prejeto, in znova
vsakič, ko pozneje prispela poraba poveča strošek. Dogodek klica
telephony.complete / web.complete
vsebuje billing_pending: true in obračunska polja z vrednostjo null. Ne blokira
izvajanja in je dostavljen samo končnim točkam (nikoli zastarelemu spletnemu kavlju z enim URL-jem).
Klici, obračunani ob koncu, vsebujejo obračun v dogodku dokončanja
in ne prejmejo call.billed.
Vrstni red ni zagotovljen: strošek običajno čaka na dogodek dokončanja,
vendar lahko call.billed prispe pred njim (če je dogodek dokončanja zadržan
eno uro ali so dostave ponovljene ob različnih časih), dva dogodka
call.billed pa lahko prispeta v napačnem vrstnem redu. Za vsak call_id
ohranite dogodek z najvišjim 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"
}| Polje | Vrsta | Opis |
|---|---|---|
call_id | celo število | Klic, ki je bil obračunan |
agent_id | celo število | null | Agent, ki je obravnaval klic, če je bil dodeljen |
agent_name | niz | null | Agent, ki je obravnaval klic, če je bil dodeljen |
reason | niz | settled: strošek klica. adjusted: poraba, ki je prispela po strošku in ga povečala (strošek se nikoli ne zniža) |
billing_seq | celo število | 1 za strošek, nato 2, 3, ... za vsako povečanje. Najvišja prejeta vrednost predstavlja trenutni obračun klica |
billable_minutes | število | Zaračunane minute, zaokrožene na najbližjo četrtino minute |
billing_total_cents | celo število | Vse, kar je bilo doslej zaračunano za klic v ameriških centih, po morebitnem dobroimetju za brezplačni klic, vključno s povečanji adjusted |
adjustment_cents | celo število | null | Samo adjusted: to povečanje v ameriških centih po morebitnem dobroimetju za brezplačni klic |
Enaki skupni zneski so v objektu klica
kot billable_minutes in billing_total_cents. event_id je enak pri
vsaki dostavi enega billing_seq, zato ponovljeno poročilo nikoli ne ustvari
drugega dogodka.
call.status_changed
Poslano med potekajočim klicem vsakič, ko doseže novo fazo: ThunderPhone začne klicati, oseba ali njen telefon odgovori, glasovni agent doseže glasovni predal ali pa je glasovni agent postavljen na čakanje in nato odstranjen s čakanja. Uporabite ga za prikaz napredka klica v živo, na primer »Klicanje …«, »Odgovorjeno«, »Na čakanju« in »Čakanje končano po 4 minutah« v niti klepeta, ki spremlja klic. Dogodek ne blokira in je dostavljen samo končnim točkam (nikoli podedovanemu webhooku z enim URL-jem).
{
"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"
}| Polje | Tip | Opis |
|---|---|---|
call_id | integer | Klic |
agent_id | integer | null | Glasovni agent, ki je obravnaval klic, če je bil dodeljen |
agent_name | string | null | Glasovni agent, ki je obravnaval klic, če je bil dodeljen |
direction | string | Smer klica, kot je navedena v objektu klica |
status | string | Faza, ki jo je klic dosegel; glejte spodnjo tabelo |
occurred_at | timestamp | Čas dogodka |
hold_seconds | integer | null | Samo off_hold: trajanje čakanja v sekundah. null za vsa druga stanja |
status | Kdaj se pošlje |
|---|---|
dialing | Odhodni klici: ThunderPhone vzpostavlja klic. Pošlje se tik preden se klic posreduje ponudniku omrežja, potem ko so uspešno prestala vsa preverjanja, ki bi lahko klic zavrnila. Preskusni klici, začeti na nadzorni plošči, se ne pošljejo |
answered | Odhodni klici: ponudnik omrežja je sporočil, da je bil klic sprejet. Šteje tudi odgovor glasovnega predala ali sistema za preverjanje klicev, zato lahko sledi voicemail. Ko ThunderPhone za odgovor izve šele iz poročila ob koncu klica, se answered pošlje ob koncu klica |
voicemail | Odhodni klici: glasovni agent je dosegel glasovni predal in pušča sporočilo ali prekine klic, kot določa voicemail_action glasovnega agenta. Pošlje se, ko je glasovni predal potrjen (njegov pisk ali brez odgovora), ne ob prvi domnevi |
on_hold | Glasovni agent je bil postavljen na čakanje in tiho čaka (orodje wait_on_hold) |
off_hold | Oseba se je vrnila na linijo in glasovni agent znova govori. hold_seconds navaja trajanje čakanja |
Vsak klic pošlje posamezno stanje največ enkrat, razen on_hold in off_hold,
ki se pošljeta enkrat za vsako čakanje. Običajen odhodni klic, ki čaka na
čakanju, pošlje dialing, answered, on_hold, off_hold in nato
telephony.complete, ko se konča.
O zvonjenju se ne poroča: ali telekomunikacijski ponudnik signalizira zvonjenje, se preveč razlikuje, da bi se na to lahko zanesli. Pri redkih klicih z voicemail_action: "prompt", kjer poziv agenta namesto ThunderPhone odloči, kaj storiti v glasovnem predalu, stanje voicemail ni poslano; answered_by v telephony.complete še vedno navaja voicemail. Podatki ne vsebujejo prepisa, telefonskih številk ali spremenljivk, zato je call.status_changed poslan tudi za klice, pri katerih je snemanje izklopljeno.
Dogodki SMS
Dogodki SMS opisujejo sporočila, poslana prek povezanega računa organizacije Twilio ali Telnyx. Telo sporočila je izpuščeno, to pa je anonimiziran.
Sporočilo v obsegu organizacije pridobite z
GET /v1/sms/{message_id}, ko potrebujete njegovo
vsebino ali prejemnika. source je api, agent_tool, followup
ali pre_call (besedilo kampanje pred klicem), kot pri
objektu sporočila.
Vsak dogodek SMS vsebuje scheduled_send_id: ID
načrtovanega pošiljanja, za katerega je bilo besedilno sporočilo poslano, ali
null za besedilno sporočilo, ki ni bilo načrtovano. Načrtovana besedilna sporočila imajo source
"scheduled".
sms.sent
Pošlje se, ko ponudnik mobilnih storitev stranke sprejme zahtevo za odhodni SMS. To ni potrdilo o dostavi na napravo.
{
"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
Poslano po trajni zavrnitvi operaterja, ko so začasni ponovni poskusi
izčrpani, ko je izid dokončno neznan ali ko Twilio sporoči, da sprejeto sporočilo
ni bilo dostavljeno oziroma ni uspelo. V zadnjem primeru je bil dogodek sms.sent
sporočila že poslan, status pa ostane "accepted". error_code je stabilna koda
ThunderPhone, error_message pa navaja dejanje stranke, kadar je to na voljo.
status: "unknown" pomeni, da je operater morda sprejel SMS; uskladite ga v dnevniku
operaterja, ker ga ThunderPhone ne bo samodejno znova poslal.
sms.received
Rezervirano za podporo dohodnim sporočilom SMS. V trenutni izdaji se ne pošilja noben
dogodek sms.received. Konfiguracija webhookov dohodnega ponudnika mobilnih storitev in
preverjanje podpisov bosta na voljo ločeno.
Načrtovani dogodki
Načrtovana pošiljanja, ki niso izvedena, sprožijo enega
od teh dogodkov. Pošiljanje, ki je izvedeno, namesto tega sproži običajne dogodke:
dogodke sms.* z nastavljenim scheduled_send_id za besedilno sporočilo ter dogodke klica za
klic, pri čemer je scheduled_send_id v njegovem telephony.complete. Oba nista blokirajoča. Ko ima pošiljanje agenta, jih prejmejo tudi
končne točke, vezane na tega agenta.
Podatkovni paket vsebuje samo ID-je, stanje in čase: nikoli telesa besedilnega sporočila ali
spremenljivk oziroma konteksta klica, to pa je redigiran. Za preostalo pridobite
GET /v1/scheduled/{id}.
scheduled.skipped
Poslano, ko pošiljanje namenoma ni poslano. reason je expired (pošiljanje ni moglo biti
izvedeno pred expires_at), opted_out (številka je na
seznamu odjav, vključno z odjavo, dodano po ustvarjanju
pošiljanja), quiet_hours (čas pošiljanja je nastopil zunaj obdobja med 8.00 in 21.00 v
časovnem pasu prejemnika), sender_not_ready (številka za besedilna sporočila ne more več
pošiljati) ali outbound_tcpa_unconfirmed (čas klica je nastopil, preden je bila
zabeležena potrditev TCPA organizacije).
{
"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
Poslano, ko je ThunderPhone poskusil poslati, vendar pošiljanje ni uspelo. reason je
napaka samega pošiljanja: koda napake SMS, kot je
carrier_rejected za sporočilo, ali razlog za zavrnitev oziroma neuspeh klica,
kot je pravilo za blokirani cilj (na primer premium_rate) ali
agent_deleted. Koristni tovor ima enaka
polja kot scheduled.skipped.
| Polje | Vrsta | Opis |
|---|---|---|
id | niz | ID načrtovanega pošiljanja |
type | niz | sms ali call |
status | niz | skipped ali failed |
reason | niz | Zakaj, kot je navedeno zgoraj; enaka vrednost kot status_reason pošiljanja |
detail | niz | Berljiva razlaga |
source | niz | Kaj je ustvarilo pošiljanje: api |
external_id | niz | null | Vaš ključ za pošiljanje ali null |
from_number | niz | Številka pošiljatelja |
to | niz | Vedno "[REDACTED]" |
agent_id | celo število | null | Klici: agent; sporočila: null |
send_at, expires_at, created_at | časovni žig | ISO 8601 |
Glasovni dogodki
Ustvarjanje glasov po meri je asinhrono. Ti neblokirni dogodki vam omogočajo, da se odzovete na končni rezultat, namesto da bi preverjali končno točko s podrobnostmi klona.
voice.ready in voice.failed sta dostavljena samo na končno točko za celotno
organizacijo z events: []. Ni ju mogoče izbrati kot izrecna filtra dogodkov.
voice.ready
Pošlje se, ko se glas po meri preneha obdelovati in ga je mogoče dodeliti agentu.
{
"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
Pošlje se, ko obdelava glasu po meri doseže trajno napako.
{
"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"
}| Polje | Vrsta | Opis |
|---|---|---|
voice.id | niz | Javni ID glasu po meri |
voice.name | niz | Vrednost glasu agenta v obliki custom:<public_id> |
voice.display_name | niz | Ime glasu, prikazano organizaciji |
voice.language | niz | Enojezikovna koda klona |
voice.gender | niz | male, female ali prazen niz |
voice.status | niz | ready za voice.ready; failed za voice.failed |
voice.failure_reason | niz | Prazno ob uspehu; podrobnost napake obdelave ob neuspehu |
voice.created_at, voice.updated_at | časovni žig | Časovna žiga ISO 8601 |
reason | niz | Podrobnost napake; prisotno samo pri voice.failed |
Dogodki kakovosti
call.graded
Poslano vsakič, ko se za klic zaključi zagon ocenjevanja z UI. Neblokirajoče.
{
"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"
}| Polje | Vrsta | Opis |
|---|---|---|
agent_id | integer | null | Agent, ki je obravnaval klic, če je bil dodeljen |
agent_name | string | null | Agent, ki je obravnaval klic, če je bil dodeljen |
grade.id | integer | ID ocene |
grade.score | integer | null | 0–100 |
grade.call_outcome | string | success, failure, unknown ali no_conversation |
grade.summary | string | Povzetek v enem odstavku |
grade.detected_issues | array | Nizi težav, ki jih je zaznal ocenjevalnik |
grade.status | string | Vedno completed — pošljejo se samo dokončani zagoni |
grade.grader_model | string | Kateri ocenjevalnik je ustvaril rezultat: heuristic-v1 (ali drug ThunderPhone ocenjevalnik na podlagi pravil) za hitro začasno oceno, thunderphone-grader za celotno oceno. To je oznaka ThunderPhone, ne ime modela UI |
grade.graded_at, grade.created_at | timestamp | |
report | object | null | Poročilo o klicu, namenjeno stranki: oznaka izida, oznaka in razlog za potrebno pozornost, klicatelj, enovrstični povzetek, izkušnja klicatelja. Pri zgodnji hevristični oceni je null ali poročilo pending, katerega polja so nadomestne vrednosti; dogodek celotne ocene vsebuje dokončano poročilo |
call.data_extracted
Poslano vsakič, ko se uspešno zaključi ekstrakcija strukturiranih podatkov,
vključno s poznim ponovnim poskusom po telephony.complete / web.complete
ali ročnim ponovnim zagonom prek
POST /v1/calls/{call_id}/extract.
Neblokirajoče.
V načinu blokirajoče ekstrakcije zaključni dogodek običajno čaka največ do
75-sekundnega proračuna za ekstrakcijo. Če se proces delavca za ekstrakcijo
izgubi, produkcijsko zaključevanje v čakalni vrsti (vsakih pet minut) sprosti
zaključek, katerega blocking_deadline_at je potekel, preden začne nov poskus
ekstrakcije. Poznejši uspeh je ločeno dostavljen kot ta dogodek.
{
"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"
}| Polje | Vrsta | Opis |
|---|---|---|
agent_id | integer | null | Agent, ki je obravnaval klic, kadar je bil dodeljen |
agent_name | string | null | Agent, ki je obravnaval klic, kadar je bil dodeljen |
summary | string | null | Dokončan povzetek klica, kadar ima agent vklopljeno možnost Ustvari povzetek klica, zato pozni dogodek ekstrakcije dostavi tudi povzetek, ki je zamudil okno za dokončanje; sicer null. Agenti s povzetkom, vendar brez polj za ekstrakcijo, tega dogodka nikoli ne pošljejo: pozni povzetek preberite z GET /v1/calls/{call_id} |
extracted_data.status | string | Za ta dogodek vedno completed |
extracted_data.fields | object | Vrednosti, določene s ključi konfiguriranih polj za ekstrakcijo; nedostopne vrednosti so null |
extracted_data.evidence | object | Dokazi, določeni s poljem za ekstrakcijo. Vrednost, ki ni null, vsebuje natančen strukturno preverjen citat (največ 1.000 znakov), speaker_role (caller ali agent) in turn_index; daljši citati, ki jih vrne model, so zavrnjeni namesto okrajšani, dokazi pa so null, kadar je njihovo polje null |
extracted_data.verification | string | verified samo, kadar je neodvisni prehod dokazov vrnil natanko eno veljavno presojo za vsako kandidatno polje. unavailable pomeni, da prehod ni uspel, je potekel čas, ni bilo dovolj proračuna ali pa je vrnil nepravilno oblikovan oziroma delen izhod. Povsem nedostopen prehod ohrani strukturno utemeljene vrednosti za pregled stranke. Pri delnem izhodu se uporabijo veljavne presoje, vsako kandidatno polje brez natanko ene veljavne presoje pa se nastavi na null |
extracted_data.field_reasons | object | Razlogi, določeni s polji, ki so bila nastavljena na null zaradi strukturnega utemeljevanja ali neodvisnega preverjevalnika |
extracted_data.schema_version | string | Zgoščena vrednost natančne sheme polj, uporabljene za to ekstrakcijo |
extracted_at | timestamp | Čas dokončanja ISO 8601 |
model | string | Vedno thunderphone-extractor: oznaka ThunderPhone za model ekstrakcije, ne ime modela umetne inteligence |
campaign.completed
Poslano enkrat, ko kampanja preide iz running v completed, ne glede na to,
ali se je njen urnik končal ali pa so vsi stiki dosegli končna stanja. Ponovni
poskusi izvajalnika ne pošljejo novega dogodka. Ta življenjski dogodek na ravni
organizacije se dostavi samo končnim točkam na ravni organizacije, ne pa
končnim točkam na ravni agenta. Neblokirajoče.
{
"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"
}Štirje izidi so med seboj ločeni, njihova vsota pa je contacts_total:
completed vsebuje uspešno zaključene kontakte; no_answer vsebuje neuspešne/izčrpane kontakte v končnem stanju, katerih končni izid je bil neodgovorjen klic; failed vsebuje vse druge neuspešne/izčrpane kontakte v končnem stanju; remaining pa vsebuje čakajoče, načrtovane ali trenutno klicane kontakte. Kontakt, ki čaka na ponovni poskus, je remaining, tudi če je bil njegov zadnji poskus neodgovorjen klic. Klici v teku se uskladijo pred enkratnim posnetkom ob zaključku. started_at je konfigurirani začetek kampanje oziroma čas ustvarjanja kampanje, če začetek ni bil konfiguriran. skipped ni peta kategorija: šteje kontakte znotraj failed, ki jih je filter vrste številke zaključil brez klica.
issue.reported
Poslano, ko je ustvarjeno poročilo o težavi —
bodisi ga uporabnik vloži z nadzorne plošče (source: "user") bodisi ga
ocenjevanje klica ustvari samodejno (source: "system"). Neblokirajoče.
{
"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"
}| Polje | Vrsta | Opis |
|---|---|---|
agent_id | integer | null | Agent, ki je obravnaval klic, kadar je bil dodeljen |
agent_name | string | null | Agent, ki je obravnaval klic, kadar je bil dodeljen |
issue_report.severity | string | critical, warning ali info |
issue_report.status | string | open ali resolved |
issue_report.source | string | user (vloženo z nadzorne plošče) ali system (ustvarjeno z ocenjevanjem) |
issue.escalated
Poslano, ko je vzorec težave poslan ThunderPhone v pregled osebja: po Prijavite ThunderPhone ali kadar možnost Odpravi z UI ne more potrditi popravka na strani stranke in težavo samodejno usmeri naprej. Ta dogodek prejmejo samo končne točke na ravni celotne organizacije.
{
"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"
}| Polje | Vrsta | Opis |
|---|---|---|
automatic | boolean | true za samodejno eskalacijo; false za ročno eskalacijo |
cluster_id | UUID | Eskalirani vzorec težave |
escalation_id | UUID | Zapis eskalacije |
status | string | open ob pošiljanju dogodka |
To je obvestilo, ne sveženj dokazov. Uporabite cluster_id, da ga povežete z
vzorcem težave. Glejte Prijavite ThunderPhone.
Dogodki testnih klicev
test-call.completed
Poslano, ko
izvedba testnega klica
doseže končno stanje — completed ali failed, vključno z izvedbami,
ki niso uspele ob zagonu in nikoli niso ustvarile klica. Ne blokira.
Uporabno za povezovanje paketnih izvajanj CI s sistemi za klepet in obvestila.
{
"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"
}| Polje | Vrsta | Opis |
|---|---|---|
agent_id | integer | null | Agent, ki je obravnaval klic, če je bil dodeljen |
agent_name | string | null | Agent, ki je obravnaval klic, če je bil dodeljen |
test_call_run.target_type | string | agent ali phone_number |
test_call_run.target_id | integer | ID agenta ali telefonske številke, na katerega je ciljala izvedba, skladno z target_type |
test_call_run.status | string | completed ali failed |
test_call_run.call_id | integer | null | null, kadar izvedba ni uspela pred vzpostavitvijo klica |
test_call_run.error_message | string | Ob uspehu prazno |
Dogodki opozoril
alert.triggered
Poslano, ko pravilo opozorila z omogočenim kanalom Pošlji spletnim kavljem za razvijalce preseže svoj prag. Ne blokira. Pravilo se sproži enkrat, nato pa upošteva obdobje hlajenja, zato dolgotrajna kršitev ustvari en dogodek na obdobje hlajenja.
{
"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"
}| Polje | Vrsta | Opis |
|---|---|---|
event_id (v data) | UUID | ID sprožitve opozorila — razlikuje se od ID-ja event_id dostave v ovojnici |
rule_id, rule_name | UUID, string | Pravilo, ki se je sprožilo |
metric | string | success_rate, failure_rate, avg_score, call_volume ali suite_regression |
comparator | string | lt, lte, gt ali gte |
metric_value | number | Vrednost metrike v obdobju, ko se je pravilo sprožilo |
threshold | number | Konfigurirani prag |
window_hours | integer | Drseče okno za ocenjevanje |
fired_at | timestamp |
Za ustvarjanje pravil, metrike, obdobja hlajenja ter kanale e-pošte in Slack glejte vodnik za opozorila.
Dogodki telefonskih številk
phone_number.spam_risk_changed
Pošlje se, ko spremljanje oznak neželene pošte (plačljiv dodatek, na zahtevo prek podpore)
zazna, da se tveganje neželene pošte za spremljano številko poveča na medium ali high (z low, brez
prejšnjega odčitka ali z medium na high). Ne blokira drugih postopkov. Številka, ki ostane
označena, se ne pošlje znova; številka, ki se vrne na low in je pozneje znova označena, pa se.
Dogodek nima konteksta agenta, zato ga prejmejo le končne točke na ravni organizacije.
Lastniki in skrbniki organizacije prejmejo tudi e-poštno sporočilo.
{
"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"
}| Polje | Vrsta | Opis |
|---|---|---|
phone_number | niz | Številka v zapisu E.164 |
phone_number_id | celo število | null | Njen ID v Telefonskih številkah |
spam_risk | niz | medium ali high |
previous_spam_risk | niz | null | Tveganje pri zadnjem odčitku; null pred prvim odčitkom |
spam_category | niz | null | Oznaka, ki jo lahko prikažejo operaterji, na primer Telemarketer ali Survey. Obravnavajte jo kot prosto besedilo |
scores | predmet | Vsaka vrednost je od 0 do 100 ali null, dokler ni dovolj velikega obsega klicev: maturity (kako uveljavljena je številka), connection (ali se ljudje oglasijo), engagement (ali ostanejo na liniji), sentiment (ali jo blokirajo oziroma prijavijo) |
checked_at | časovni žig | Kdaj je ThunderPhone prebral rezultat |
Dogodki migracije
migration.call.complete
Pošlje se, ko se konča klic, vzpostavljen prek
POST /v1/migrations/{id}/calls,
ne glede na to, katera platforma ga je prevzela. Ne blokira izvajanja. Prispe največ približno 5 minut
po koncu klica. data vsebuje vsa polja iz
telephony.complete ter blok migration. Klic, ki ga je vzpostavil ThunderPhone, kot običajno pošlje tudi telephony.complete z istim
call_id. Za klic, ki ga je prevzela druga platforma, je answered_by nastavljen na null. Klic na drugi platformi, ki se ne konča v 2
urah ali katerega migracija se najprej zaključi oziroma izgubi ključ, se pošlje s
status: "unknown" in brez prepisa.
{
"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"
}| Polje | Vrsta | Opis |
|---|---|---|
migration.id | UUID | Migracija |
migration.routing_id | UUID | Usmerjeni klic, kot je vrnjen ob vzpostavitvi |
migration.arm | string | ours (vzpostavil ga je ThunderPhone) ali vendor (vzpostavila ga je druga platforma) |
migration.vendor | string | retell, vapi, elevenlabs ali bland |
migration.vendor_call_id | string | null | ID klica druge platforme; null za ours |
migration.metadata | object | metadata, ki ste jo poslali ob vzpostavitvi klica |
migration.vendor_cost_usd | string | null | Strošek klica, ki ga je sporočila druga platforma, kadar ga je sporočila |
call_id | integer | null | ID klica ThunderPhone; null za vendor |
status | string | Za vendor: completed, ko je klicani spregovoril, failed, ko ni, unknown kot zgoraj. Za ours: kot v telephony.complete |
Za klic vendor ThunderPhone nima podatkov o obračunavanju ali ekstrakciji:
billable_minutes, billing_total_cents in extracted_data so null,
product in voice sta prazna, recording_mode je vendor, in
recording_url je povezava druge platforme, kadar jo je ta posredovala.
migration.rollback
Pošlje se, ko postopni preklop migracije samodejno preusmeri vse klice nazaj na drugo platformo: 3 klici se v 15 minutah niso uspeli povezati s ThunderPhone, 2 klica, poslana v ThunderPhone, sta se končala, preden je agent odgovoril, ali pa je stopnja uspešnosti izida naloge ThunderPhone padla za več kot konfigurirano razliko pod stopnjo druge platforme. Ne blokira, enkrat na povrnitev. Po tem je delež ThunderPhone 0 %, migracija pa je začasno ustavljena, dokler je nekdo ne nadaljuje na zavihku Migracija agenta. Podatkovni paket ne vsebuje telefonskih številk, prepisov ali ID-jev klicev.
{
"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"
}| Polje | Vrsta | Opis |
|---|---|---|
migration_id | UUID | Migracija |
vendor | niz | retell, vapi, elevenlabs ali bland |
reason | niz | ours_failed_burst (3 neuspele povezave v 15 minutah), dropped_calls (2 klica sta se končala, preden je agent odgovoril, v 30 minutah) ali rate_gap (razlika v stopnji uspešnosti izida naloge pri vsaj rollback_min_calls ocenjenih klicih na vsaki strani) |
previous_percent | celo število | Delež klicev ThunderPhone pred povrnitvijo |
ours_percent | celo število | Vedno 0 |
step | celo število | null | Korak urnika, na katerem je bila migracija (indeksirano od 0) |
ours / theirs | objekt | null | Ocenjeni klici v trenutnem koraku in njihova stopnja uspešnosti; theirs lahko predstavlja zadnjih 30 dni, kadar ima korak premalo klicev. null, kadar jih ni bilo |
ours_failed | celo število | Neuspele povezave, štete v zadnjih 15 minutah |
dropped | celo število | Klici, šteti kot prekinjeni v zadnjih 30 minutah |
rolled_back_at | časovni žig |