ThunderPhone v3 je zdaj na voljo.Začnite sami, že od 2 ¢/min.Preberite obvestilo

Webhooks

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_id za 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"
}
PoljeVrstaOpis
agent_idcelo število | nullAgent, ki je obravnaval klic, kadar je bil dodeljen
agent_nameniz | nullAgent, ki je obravnaval klic, kadar je bil dodeljen
returning_callobjektPrisotno 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_headersobjektPrisotno 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.

PoljeVrstaOpis
agent_idinteger | nullAgent, ki je obravnaval klic, kadar je bil dodeljen
agent_namestring | nullAgent, 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.

PoljeVrstaOpis
agent_idinteger | nullAgent, ki je obravnaval klic, kadar je bil dodeljen
agent_namestring | nullAgent, 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"
}
PoljeVrstaOpis
agent_idinteger | nullAgent, ki je obravnaval klic, kadar je bil dodeljen
agent_namestring | nullAgent, ki je obravnaval klic, kadar je bil dodeljen
positionintegerIndeks obrata v zgodovini klica — stabilna identiteta za razvrščanje
rolestringassistant (govor agenta) ali user (govor klicatelja)
textstringBesedilo prepisa obrata, kot je znano ob času pošiljanja
entry_typestringVrsta osnovnega vnosa v zgodovini: completion (agent) ali user_turn / span (klicatelj)
start_ms, end_msintegerZvoč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.

PoljeVrstaOpis
agent_idinteger | nullAgent, ki je obravnaval klic, kadar je bil dodeljen
agent_namestring | nullAgent, 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".

PoljeVrstaOpis
agent_idinteger | nullAgent, ki je obravnaval klic, kadar je bil dodeljen
agent_namestring | nullAgent, 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.

PoljeVrstaOpis
agent_idinteger | nullAgent, ki je obravnaval klic, kadar je bil dodeljen
agent_namestring | nullAgent, 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.

PoljeVrstaOpis
agent_idinteger | nullAgent, ki je obravnaval klic, kadar je bil dodeljen
agent_namestring | nullAgent, 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"
}
PoljeVrstaOpis
call_idintegerKlic, ki je bil preusmerjen
agent_idinteger | nullAgent, ki je obravnaval klic, če je bil dodeljen
agent_namestring | nullAgent, ki je obravnaval klic, če je bil dodeljen
transfer_outcomestringrefer_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
destinationstring | nullŠtevilka, na katero je bil klic preusmerjen
sip_statusinteger | nullSIP-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_kindstring | nullSamo za bridged: cold_fallback (zavrnjeni hladni prenos, ki ga je povezal ThunderPhone) ali warm (dve osebi pri toplem prenosu po odhodu agenta)
bridge_secondsinteger | nullSamo za bridged: čas povezave, ki ga je ThunderPhone zaračunal, v sekundah
bridge_total_centsinteger | nullSamo 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"
}
PoljeVrstaOpis
call_idcelo številoKlic, ki je bil obračunan
agent_idcelo število | nullAgent, ki je obravnaval klic, če je bil dodeljen
agent_nameniz | nullAgent, ki je obravnaval klic, če je bil dodeljen
reasonnizsettled: strošek klica. adjusted: poraba, ki je prispela po strošku in ga povečala (strošek se nikoli ne zniža)
billing_seqcelo število1 za strošek, nato 2, 3, ... za vsako povečanje. Najvišja prejeta vrednost predstavlja trenutni obračun klica
billable_minutesšteviloZaračunane minute, zaokrožene na najbližjo četrtino minute
billing_total_centscelo številoVse, 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_centscelo število | nullSamo 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"
}
PoljeTipOpis
call_idintegerKlic
agent_idinteger | nullGlasovni agent, ki je obravnaval klic, če je bil dodeljen
agent_namestring | nullGlasovni agent, ki je obravnaval klic, če je bil dodeljen
directionstringSmer klica, kot je navedena v objektu klica
statusstringFaza, ki jo je klic dosegel; glejte spodnjo tabelo
occurred_attimestampČas dogodka
hold_secondsinteger | nullSamo off_hold: trajanje čakanja v sekundah. null za vsa druga stanja
statusKdaj se pošlje
dialingOdhodni 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
answeredOdhodni 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
voicemailOdhodni 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_holdGlasovni agent je bil postavljen na čakanje in tiho čaka (orodje wait_on_hold)
off_holdOseba 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.

PoljeVrstaOpis
idnizID načrtovanega pošiljanja
typenizsms ali call
statusnizskipped ali failed
reasonnizZakaj, kot je navedeno zgoraj; enaka vrednost kot status_reason pošiljanja
detailnizBerljiva razlaga
sourcenizKaj je ustvarilo pošiljanje: api
external_idniz | nullVaš ključ za pošiljanje ali null
from_numbernizŠtevilka pošiljatelja
tonizVedno "[REDACTED]"
agent_idcelo število | nullKlici: agent; sporočila: null
send_at, expires_at, created_atčasovni žigISO 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"
}
PoljeVrstaOpis
voice.idnizJavni ID glasu po meri
voice.namenizVrednost glasu agenta v obliki custom:<public_id>
voice.display_namenizIme glasu, prikazano organizaciji
voice.languagenizEnojezikovna koda klona
voice.gendernizmale, female ali prazen niz
voice.statusnizready za voice.ready; failed za voice.failed
voice.failure_reasonnizPrazno ob uspehu; podrobnost napake obdelave ob neuspehu
voice.created_at, voice.updated_atčasovni žigČasovna žiga ISO 8601
reasonnizPodrobnost 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"
}
PoljeVrstaOpis
agent_idinteger | nullAgent, ki je obravnaval klic, če je bil dodeljen
agent_namestring | nullAgent, ki je obravnaval klic, če je bil dodeljen
grade.idintegerID ocene
grade.scoreinteger | null0–100
grade.call_outcomestringsuccess, failure, unknown ali no_conversation
grade.summarystringPovzetek v enem odstavku
grade.detected_issuesarrayNizi težav, ki jih je zaznal ocenjevalnik
grade.statusstringVedno completed — pošljejo se samo dokončani zagoni
grade.grader_modelstringKateri 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_attimestamp
reportobject | nullPoroč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"
}
PoljeVrstaOpis
agent_idinteger | nullAgent, ki je obravnaval klic, kadar je bil dodeljen
agent_namestring | nullAgent, ki je obravnaval klic, kadar je bil dodeljen
summarystring | nullDokonč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.statusstringZa ta dogodek vedno completed
extracted_data.fieldsobjectVrednosti, določene s ključi konfiguriranih polj za ekstrakcijo; nedostopne vrednosti so null
extracted_data.evidenceobjectDokazi, 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.verificationstringverified 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_reasonsobjectRazlogi, določeni s polji, ki so bila nastavljena na null zaradi strukturnega utemeljevanja ali neodvisnega preverjevalnika
extracted_data.schema_versionstringZgoščena vrednost natančne sheme polj, uporabljene za to ekstrakcijo
extracted_attimestampČas dokončanja ISO 8601
modelstringVedno 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"
}
PoljeVrstaOpis
agent_idinteger | nullAgent, ki je obravnaval klic, kadar je bil dodeljen
agent_namestring | nullAgent, ki je obravnaval klic, kadar je bil dodeljen
issue_report.severitystringcritical, warning ali info
issue_report.statusstringopen ali resolved
issue_report.sourcestringuser (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"
}
PoljeVrstaOpis
automaticbooleantrue za samodejno eskalacijo; false za ročno eskalacijo
cluster_idUUIDEskalirani vzorec težave
escalation_idUUIDZapis eskalacije
statusstringopen 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"
}
PoljeVrstaOpis
agent_idinteger | nullAgent, ki je obravnaval klic, če je bil dodeljen
agent_namestring | nullAgent, ki je obravnaval klic, če je bil dodeljen
test_call_run.target_typestringagent ali phone_number
test_call_run.target_idintegerID agenta ali telefonske številke, na katerega je ciljala izvedba, skladno z target_type
test_call_run.statusstringcompleted ali failed
test_call_run.call_idinteger | nullnull, kadar izvedba ni uspela pred vzpostavitvijo klica
test_call_run.error_messagestringOb 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"
}
PoljeVrstaOpis
event_id (v data)UUIDID sprožitve opozorila — razlikuje se od ID-ja event_id dostave v ovojnici
rule_id, rule_nameUUID, stringPravilo, ki se je sprožilo
metricstringsuccess_rate, failure_rate, avg_score, call_volume ali suite_regression
comparatorstringlt, lte, gt ali gte
metric_valuenumberVrednost metrike v obdobju, ko se je pravilo sprožilo
thresholdnumberKonfigurirani prag
window_hoursintegerDrseče okno za ocenjevanje
fired_attimestamp

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"
}
PoljeVrstaOpis
phone_numbernizŠtevilka v zapisu E.164
phone_number_idcelo število | nullNjen ID v Telefonskih številkah
spam_risknizmedium ali high
previous_spam_riskniz | nullTveganje pri zadnjem odčitku; null pred prvim odčitkom
spam_categoryniz | nullOznaka, ki jo lahko prikažejo operaterji, na primer Telemarketer ali Survey. Obravnavajte jo kot prosto besedilo
scorespredmetVsaka 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 žigKdaj 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"
}
PoljeVrstaOpis
migration.idUUIDMigracija
migration.routing_idUUIDUsmerjeni klic, kot je vrnjen ob vzpostavitvi
migration.armstringours (vzpostavil ga je ThunderPhone) ali vendor (vzpostavila ga je druga platforma)
migration.vendorstringretell, vapi, elevenlabs ali bland
migration.vendor_call_idstring | nullID klica druge platforme; null za ours
migration.metadataobjectmetadata, ki ste jo poslali ob vzpostavitvi klica
migration.vendor_cost_usdstring | nullStrošek klica, ki ga je sporočila druga platforma, kadar ga je sporočila
call_idinteger | nullID klica ThunderPhone; null za vendor
statusstringZa 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"
}
PoljeVrstaOpis
migration_idUUIDMigracija
vendornizretell, vapi, elevenlabs ali bland
reasonnizours_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_percentcelo številoDelež klicev ThunderPhone pred povrnitvijo
ours_percentcelo številoVedno 0
stepcelo število | nullKorak urnika, na katerem je bila migracija (indeksirano od 0)
ours / theirsobjekt | nullOcenjeni 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_failedcelo številoNeuspele povezave, štete v zadnjih 15 minutah
droppedcelo številoKlici, šteti kot prekinjeni v zadnjih 30 minutah
rolled_back_atčasovni žig

Sorodno