Open in
Katalogi ya Matukio
Aina zote za matukio ya webhook zinazotolewa na ThunderPhone.
Kila mwili wa webhook una sehemu ya type ambayo thamani yake ni mojawapo ya aina za matukio kwenye ukurasa huu. Unapojiandikisha kwa
endpoint, mkusanyiko wa events lazima uwe na
aina za matukio unazotaka (au uwe tupu ili kujiandikisha kwa kila kitu —
isipokuwa matukio ya kila zamu telephony.turn /
web.turn, ambayo hutumwa tu kwa endpoint zinazoyataja
waziwazi).
Mitindo miwili ya uwasilishaji hubeba matukio haya:
- Uwasilishaji wa endpoint daima ni arifa zisizozuia
zenye majaribio tena: jibu kwa
2xx yoyote; bahasha ina
event_idya kutumika kuondoa nakala. - Mabadilishano yanayozuia hufanyika tu kwenye
webhook ya zamani yenye URL moja: ombi la usanidi la
telephony.incoming/web.incoming(namba za hali ya webhook: 13 s ikijumuisha jaribio moja tena; funguo za wijeti za hali ya webhook: 10 s) na hali ya webhook ya utumaji wa zana. Jibu lako huunda simu inayoendelea.
Mizigo ya mfano hapa chini inaonyesha bahasha ya endpoint katika mpangilio
wake wa kutumwa (funguo zimepangwa kialfabeti: data, event_id, type);
uwasilishaji wa urithi hubeba data sawa bila event_id.
Matukio ya simu
telephony.incoming
Hutumwa wakati simu inayoingia inafika kwenye mojawapo ya
nambari zako za simu. Uwasilishaji kwa endpoint ni
arifa za kutuma-na-kuendelea zinazotumwa kwa kila simu inayoingia, iwe
nambari imesanidiwa kwa ejenti au kwa webhook. Nambari zisizo na
ejenti iliyoteuliwa pia hupokea ombi la usanidi la kuzuia
kwenye webhook ya zamani — tazama
telephony.incoming / web.incoming kwa
schema kamili ya ombi / jibu.
{
"data": {
"call_id": 987654321,
"from_number": "+14155550199",
"to_number": "+15551234567"
},
"event_id": "3f6b2ad0-1c9e-4a57-9f2b-8f6f0f9d2f11",
"type": "telephony.incoming"
}| Sehemu | Aina | Maelezo |
|---|---|---|
agent_id | integer | null | Ejenti aliyeshughulikia simu, ikiwa aliteuliwa |
agent_name | string | null | Ejenti aliyeshughulikia simu, ikiwa aliteuliwa |
returning_call | object | Huwepo tu wakati nambari ilimpigia mpigaji huyu ndani ya siku 30 zilizopita: call_id, agent_id, started_at na outcome za simu ya awali. Tazama Simu za kurudia |
sip_headers | object | Huwepo tu wakati simu ilipokelewa ikiwa na vijajuu vya SIP vya X-* au User-to-User (anwani za SIP na miunganisho ya SIP ya moja kwa moja): jina la kijajuu kwa herufi ndogo → thamani. Tazama Vijajuu vya SIP |
telephony.complete
Hutumwa wakati simu ya mawasiliano inayoingia au kutoka inapoisha. Haizuii.
Inajumuisha nakala ya mazungumzo, URL ya rekodi inapopatikana, na muhtasari wa bili. Tazama
telephony.complete / web.complete kwa
schema ya payload.
| Sehemu | Aina | Maelezo |
|---|---|---|
agent_id | integer | null | Ejenti aliyeshughulikia simu, ikiwa aliteuliwa |
agent_name | string | null | Ejenti aliyeshughulikia simu, ikiwa aliteuliwa |
telephony.tool
Hutumwa baada ya simu ya mawasiliano kuita
zana ya function. Arifa ya ukaguzi isiyozuia —
zana tayari imetekelezwa tukio hili linapowasilishwa; inahusu
zana zako za function na zana iliyojengewa ndani ya send_sms (si zana nyingine zilizojengewa ndani,
za msingi wa maarifa, za muunganisho wa app, au za MCP). Kwa send_sms,
zote arguments.to na arguments.body ni [REDACTED]. Nakala za
mazungumzo za ukamilishaji pia huzificha; pata maudhui na mpokeaji kutoka kwenye
rasilimali ya SMS inayohusu shirika kwa kutumia message_id ya jibu.
{
"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 ni matokeo yaliyotekelezwa: {"status": <http status>, "response": <your endpoint's JSON>} yanapofaulu, au
{"status": <status>, "error": "<message>"} yanaposhindwa.
| Sehemu | Aina | Maelezo |
|---|---|---|
agent_id | integer | null | Ejenti aliyeshughulikia simu, ikiwa aliteuliwa |
agent_name | string | null | Ejenti aliyeshughulikia simu, ikiwa aliteuliwa |
telephony.turn
Hutumwa simu ya mawasiliano ikiwa inaendelea, mara moja kwa kila
zamu yenye sauti inapotokea — majibu ya ejenti yaliyosemwa na
zamu za mpigaji zilizonakiliwa. Hukuruhusu kufuatilia mazungumzo ya moja kwa moja
kupitia webhook za kawaida badala ya kuchunguza mara kwa mara
GET /v1/calls/{call_id}/transcript.
Haizuii.
{
"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"
}| Sehemu | Aina | Maelezo |
|---|---|---|
agent_id | integer | null | Ejenti aliyeshughulikia simu, ikiwa aliteuliwa |
agent_name | string | null | Ejenti aliyeshughulikia simu, ikiwa aliteuliwa |
position | integer | Kielezo cha zamu katika historia ya simu — utambulisho thabiti wa kupanga mpangilio |
role | string | assistant (sauti ya ejenti) au user (sauti ya mpigaji) |
text | string | Maandishi ya nakala ya mazungumzo ya zamu kama yalivyojulikana wakati wa utumaji |
entry_type | string | Aina ya ingizo la historia la msingi: completion (ejenti), au user_turn / span (mpigaji) |
start_ms, end_ms | integer | Vipimo vya muda vya sauti kwa ms tangu simu ianze; vinapatikana tu wakati muda wa uchezaji ulikuwa tayari unajulikana wakati wa utumaji |
web.incoming
Kilinganishi cha chaneli ya wavuti cha telephony.incoming, hutumwa wakati
kipindi cha wijeti ya wavuti au simu ya majaribio ya maikrofoni ya builder
inapoanza. Uwasilishaji kwa endpoint ni wa kutuma-na-kuendelea kwa kila kipindi cha wavuti.
Funguo zinazoweza kuchapishwa katika mode="webhook" pia hupokea
ombi la usanidi la kuzuia kwenye webhook ya zamani — ombi hilo
la kuzuia lina muundo tofauti (origin_domain,
publishable_key_prefix; hakuna nambari za simu). Tazama
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 daima ni thamani halisi "web". Kwa vipindi vya wijeti
vya hali ya webhook, to_number huwa tupu (nambari ya ejenti ya kipindi hutolewa
baada ya usanidi); kwa simu za majaribio ya maikrofoni ya builder, origin_domain na
publishable_key_prefix huwa tupu.
| Sehemu | Aina | Maelezo |
|---|---|---|
agent_id | integer | null | Ejenti aliyeshughulikia simu, ikiwa aliteuliwa |
agent_name | string | null | Ejenti aliyeshughulikia simu, ikiwa aliteuliwa |
web.complete
Kilinganishi cha chaneli ya wavuti cha telephony.complete, kinachohusu simu za
wijeti ya wavuti (direction: "web") na simu za majaribio ya maikrofoni ya builder
(direction: "test"). Haizuii. Muundo wa payload ni sawa na
telephony.complete, pamoja na origin_domain,
na from_number imewekwa kuwa "web".
| Sehemu | Aina | Maelezo |
|---|---|---|
agent_id | integer | null | Ejenti aliyeshughulikia simu, ikiwa aliteuliwa |
agent_name | string | null | Ejenti aliyeshughulikia simu, ikiwa aliteuliwa |
web.tool
Kilinganishi cha chaneli ya wavuti cha telephony.tool. data hubeba
origin_domain badala ya from_number / to_number.
| Sehemu | Aina | Maelezo |
|---|---|---|
agent_id | integer | null | Ejenti aliyeshughulikia simu, ikiwa aliteuliwa |
agent_name | string | null | Ejenti aliyeshughulikia simu, ikiwa aliteuliwa |
web.turn
Kilinganishi cha chaneli ya wavuti cha telephony.turn,
kinachohusu simu za wijeti ya wavuti na simu za majaribio ya maikrofoni ya builder. Muundo wa payload
ni sawa, ukiwa na origin_domain badala ya from_number / to_number.
Kama telephony.turn, kinahitaji usajili wa wazi — hakiwasilishwi
kamwe kupitia mkusanyiko tupu wa events.
| Sehemu | Aina | Maelezo |
|---|---|---|
agent_id | integer | null | Ejenti aliyeshughulikia simu, ikiwa aliteuliwa |
agent_name | string | null | Ejenti aliyeshughulikia simu, ikiwa aliteuliwa |
call.transfer_completed
Hutumwa mara moja kwa kila simu ikiwa na matokeo ya mwisho ya
uhamisho wa simu: uhamisho baridi, au daraja la
kibinadamu linalobaki baada ya ejenti kuondoka kwenye uhamisho wa joto.
Haitazuia utekelezaji, na hutumwa kwa vituo vya mwisho pekee (kamwe si kwa
webhook ya zamani ya URL moja). Hufika baada ya telephony.complete ya simu:
mtoa huduma anapochukua simu au uhamisho unaposhindikana, au, ThunderPhone
ilipounganisha simu, daraja linapoisha.
{
"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"
}| Sehemu | Aina | Maelezo |
|---|---|---|
call_id | integer | Simu iliyohamishwa |
agent_id | integer | null | Ejenti aliyeshughulikia simu, ikiwa aliteuliwa |
agent_name | string | null | Ejenti aliyeshughulikia simu, ikiwa aliteuliwa |
transfer_outcome | string | refer_accepted: mtoa huduma alichukua simu. bridged: ThunderPhone iliendelea kumunganisha mpigaji na lengwa yenyewe, ama kwa sababu mtoa huduma alikataa uhamisho baridi au kwa sababu ejenti wa uhamisho wa joto aliondoka. bridge_unanswered: mtoa huduma alikataa uhamisho baridi na lengwa halikujibu simu ya ThunderPhone yenyewe. failed: uhamisho haukufaulu na simu ikaisha |
destination | string | null | Nambari ambayo simu ilihamishiwa |
sip_status | integer | null | Hali ya SIP ya mtoa huduma ilipokataa uhamisho baridi: 403 (kwa mfano, trunk ya Twilio isiyo na uhamisho wa simu), 405 au 501. null wakati mtoa huduma hakuikataa |
bridge_kind | string | null | Kwa bridged pekee: cold_fallback (uhamisho baridi uliokataliwa ambao ThunderPhone iliunganisha) au warm (watu wawili wa uhamisho wa joto baada ya ejenti kuondoka) |
bridge_seconds | integer | null | Kwa bridged pekee: muda wa daraja ambao ThunderPhone ilitoza, kwa sekunde |
bridge_total_cents | integer | null | Kwa bridged pekee: gharama ya daraja kwa senti za USD baada ya salio lolote la simu bila malipo, inayotozwa kando na billing_total_cents ya simu |
Thamani hizohizo ziko kwenye kitu cha simu
kama transfer_outcome, transfer_destination, transfer_sip_status,
transfer_bridge_kind, transfer_bridge_seconds na
transfer_bridge_total_cents. event_id ni ileile kwenye kila utumaji
kwa simu, hivyo ripoti inayorudiwa haitoi tukio la pili.
call.billed
Hutumwa kwa simu inayotozwa kulingana na matumizi: malipo yake yanapothibitishwa, dakika chache
baada ya simu kuisha matumizi yake yanapopokelewa, na tena kila matumizi
yaliyopokelewa baadaye yanapoongeza malipo. Tukio la simu la
telephony.complete / web.complete
hubeba billing_pending: true na sehemu za malipo zenye null. Halizuii,
na hutumwa kwa endpoints pekee (kamwe si kwa webhook ya zamani ya URL moja).
Simu zinazotozwa zinapoisha hubeba maelezo yao ya malipo katika tukio la kukamilika
na hazipokei call.billed.
Mpangilio haujahakikishwa: kwa kawaida malipo husubiri tukio la kukamilika,
lakini call.billed inaweza kuwasili kabla yake (tukio la kukamilika likicheleweshwa
kwa saa moja, au utumaji ukijaribiwa tena kwa nyakati tofauti), na matukio mawili ya
call.billed yanaweza kuwasili bila mpangilio. Hifadhi tukio lenye
billing_seq ya juu zaidi kwa kila call_id.
{
"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"
}| Sehemu | Aina | Maelezo |
|---|---|---|
call_id | integer | Simu iliyotozwa |
agent_id | integer | null | Ejenti aliyeshughulikia simu, iwapo alipewa |
agent_name | string | null | Ejenti aliyeshughulikia simu, iwapo alipewa |
reason | string | settled: malipo ya simu. adjusted: matumizi yaliyopokelewa baada ya malipo kuyaongeza (malipo hayapunguzwi kamwe) |
billing_seq | integer | 1 kwa malipo, kisha 2, 3, ... kwa kila ongezeko. Ya juu zaidi iliyopokelewa ndiyo malipo ya sasa ya simu |
billable_minutes | number | Dakika zinazotozwa, zilizozungushwa hadi robo dakika iliyo karibu zaidi |
billing_total_cents | integer | Kila kitu ambacho simu imetoza hadi sasa kwa senti za USD, baada ya mkopo wowote wa simu bila malipo, ikijumuisha ongezeko la adjusted |
adjustment_cents | integer | null | adjusted pekee: ongezeko hili kwa senti za USD, baada ya mkopo wowote wa simu bila malipo |
Jumla hizo hizo ziko kwenye kitu cha simu
kama billable_minutes na billing_total_cents. event_id ni ileile kwenye
kila utumaji wa billing_seq moja, kwa hivyo ripoti inayorudiwa haitoi
tukio la pili.
Matukio ya SMS
Matukio ya SMS yanaeleza ujumbe unaotumwa kupitia akaunti ya Twilio au Telnyx iliyounganishwa na shirika. Maudhui ya ujumbe hayajajumuishwa na to imefichwa. Rejesha ujumbe wa shirika kutoka
GET /v1/sms/{message_id} wakati maudhui yake au mpokeaji wake yanahitajika. source ni api, agent_tool, followup
au pre_call (maandishi ya kampeni kabla ya kupiga simu), kama ilivyo kwenye
kitu cha ujumbe.
Kila tukio la SMS hubeba scheduled_send_id: kitambulisho cha
utumaji ulioratibiwa ambao ujumbe ulitumwa kwa ajili yake, au
null kwa ujumbe ambao haukuratibiwa. Ujumbe ulioratibiwa una source
"scheduled".
sms.sent
Hutumwa mtoa huduma wa mteja anapokubali ombi la SMS inayotumwa. Hiki si risiti ya uwasilishaji kwenye kifaa.
{
"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
Hutumwa baada ya mtoa huduma kukataa kabisa, baada ya majaribio ya muda mfupi kuisha, matokeo yanapokuwa hayajulikani kabisa, au Twilio inaporipoti ujumbe uliokubaliwa lakini haukuwasilishwa au umeshindwa. Katika hali hiyo ya mwisho, sms.sent ya ujumbe ilikuwa tayari imetumwa, na status hubaki "accepted". error_code ni msimbo thabiti wa ThunderPhone, na error_message hueleza hatua ya mteja inapopatikana. status: "unknown" inamaanisha mtoa huduma huenda alikubali SMS; linganisha na kumbukumbu ya mtoa huduma kwa sababu ThunderPhone haitautuma tena kiotomatiki.
sms.received
Imehifadhiwa kwa ajili ya usaidizi wa SMS zinazoingia. Hakuna matukio ya
sms.received yanayotolewa katika toleo la sasa. Usanidi wa webhook ya mtoa
huduma kwa SMS zinazoingia na uthibitishaji wa sahihi vitatolewa kando.
Matukio yaliyoratibiwa
Utumaji ulioratibiwa ambao hautoki huchochea moja
ya matukio haya. Utumaji unaotoka huchochea matukio ya kawaida badala yake: matukio
ya sms.* yenye scheduled_send_id iliyowekwa kwa ujumbe wa maandishi, matukio ya simu kwa
simu, yenye scheduled_send_id kwenye telephony.complete yake. Yote mawili hayazuii utekelezaji. Utumaji unapokuwa na ejenti, vituo vya mwisho vinavyohusu ejenti huyo
huvipokea pia.
Payload hubeba vitambulisho, hali na nyakati pekee: kamwe si maudhui ya ujumbe wa
maandishi au vigeu au muktadha wa simu, na to hufichwa. Leta
GET /v1/scheduled/{id}
kwa yaliyosalia.
scheduled.skipped
Hutumwa wakati utumaji hautumwi kimakusudi. reason ni expired (haikuweza
kutoka kabla ya expires_at), opted_out (namba iko kwenye
orodha ya kujiondoa, ikijumuisha iliyoingizwa baada ya utumaji
kuundwa), quiet_hours (muda wake ulifika nje ya saa 2 asubuhi hadi saa 3 usiku katika
eneo la saa la mpokeaji), sender_not_ready (namba ya ujumbe wa maandishi haiwezi tena
kutuma) au outbound_tcpa_unconfirmed (muda wa simu ulifika kabla ya
uthibitisho wa TCPA wa shirika kurekodiwa).
{
"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
Hutumwa ThunderPhone ilipojaribu kutuma lakini haikutumwa. reason ni hitilafu
ya utumaji wenyewe: msimbo wa hitilafu wa SMS
kama vile carrier_rejected kwa ujumbe wa maandishi, au sababu ya kukataliwa
au kushindwa kwa simu, kama vile kanuni ya eneo lililozuiwa (premium_rate,
kwa mfano) au agent_deleted. Payload ina sehemu zilezile
kama scheduled.skipped.
| Sehemu | Aina | Maelezo |
|---|---|---|
id | string | Kitambulisho cha utumaji ulioratibiwa |
type | string | sms au call |
status | string | skipped au failed |
reason | string | Sababu, kama ilivyo hapo juu; thamani sawa na status_reason ya utumaji |
detail | string | Maelezo yanayosomeka |
source | string | Kilichounda utumaji: api |
external_id | string | null | Ufunguo wako wa utumaji, au null |
from_number | string | Namba ya kutuma |
to | string | Daima "[REDACTED]" |
agent_id | integer | null | Simu: ejenti; ujumbe wa maandishi: null |
send_at, expires_at, created_at | timestamp | ISO 8601 |
Matukio ya sauti
Uundaji wa sauti maalum hufanyika kwa njia isiyosubiri. Matukio haya yasiyozuia hukuruhusu kuitikia matokeo ya mwisho badala ya kuuliza mara kwa mara endpoint ya maelezo ya nakala.
voice.ready na voice.failed huwasilishwa tu kwenye endpoint ya shirika
zima yenye events: []. Hayawezi kuchaguliwa kama vichujio dhahiri vya
matukio.
voice.ready
Hutumwa sauti maalum inapomaliza kuchakatwa na inaweza kupewa ejenti.
{
"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
Hutumwa uchakataji wa sauti maalum unapofikia hitilafu ya kudumu.
{
"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"
}| Sehemu | Aina | Maelezo |
|---|---|---|
voice.id | string | Kitambulisho cha umma cha sauti maalum |
voice.name | string | Thamani ya sauti ya ejenti katika muundo custom:<public_id> |
voice.display_name | string | Jina la sauti linaloonekana kwa shirika |
voice.language | string | Msimbo wa lugha moja wa nakala |
voice.gender | string | male, female, au mfuatano tupu |
voice.status | string | ready kwa voice.ready; failed kwa voice.failed |
voice.failure_reason | string | Tupu wakati wa mafanikio; maelezo ya hitilafu ya uchakataji wakati wa hitilafu |
voice.created_at, voice.updated_at | timestamp | Mihuri ya muda ya ISO 8601 |
reason | string | Maelezo ya hitilafu; hupatikana tu kwenye voice.failed |
Matukio ya ubora
call.graded
Hutumwa kila wakati utekelezaji wa ukadiriaji wa AI unakamilika kwa simu. Haizuii.
{
"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"
}| Sehemu | Aina | Maelezo |
|---|---|---|
agent_id | integer | null | Ejenti iliyoshughulikia simu, ikiwa iliteuliwa |
agent_name | string | null | Ejenti iliyoshughulikia simu, ikiwa iliteuliwa |
grade.id | integer | Kitambulisho cha tathmini |
grade.score | integer | null | 0–100 |
grade.call_outcome | string | success, failure, unknown, au no_conversation |
grade.summary | string | Muhtasari wa aya moja |
grade.detected_issues | array | Mifuatano ya maandishi ya matatizo yaliyopatikana na kitathmini |
grade.status | string | Daima completed — ni utekelezaji uliokamilika pekee unaotoa tukio |
grade.grader_model | string | Kitathmini kilichotoa matokeo (kwa mfano, heuristic-v1) |
grade.graded_at, grade.created_at | timestamp | |
report | object | null | Ripoti ya simu inayomlenga mteja: lebo ya matokeo, alama ya inahitaji uangalizi na sababu, mpigaji simu, muhtasari wa mstari mmoja, uzoefu wa mpigaji simu. Katika tathmini ya awali ya heuristiki, ni null au ripoti ya pending ambayo sehemu zake ni viwakilishi; tukio la tathmini kamili hubeba iliyo kamili |
call.data_extracted
Hutumwa kila wakati uchimbaji wa data iliyopangwa unakamilika kwa mafanikio,
ikiwemo jaribio la baadaye baada ya telephony.complete / web.complete au
utekelezaji upya wa mikono kupitia
POST /v1/calls/{call_id}/extract.
Haizuii.
Katika hali ya uchimbaji unaozuia, tukio la ukamilishaji kwa kawaida husubiri
si zaidi ya bajeti ya uchimbaji ya sekunde 75. Ikiwa mchakato wa worker wa
uchimbaji utapotea, uondoaji wa uzalishaji wa ukamilishaji (kila dakika tano)
hutoa ukamilishaji ambao blocking_deadline_at yake imepita kabla ya kuanza
jaribio lingine la uchimbaji. Mafanikio ya baadaye huwasilishwa kando kama
tukio hili.
{
"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": "<model id>",
"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"
}| Sehemu | Aina | Maelezo |
|---|---|---|
agent_id | integer | null | Ejenti iliyoshughulikia simu, ilipokuwa imepewa |
agent_name | string | null | Ejenti iliyoshughulikia simu, ilipokuwa imepewa |
summary | string | null | Muhtasari wa simu uliokamilika wakati ejenti ana Tengeneza muhtasari wa simu imewashwa, hivyo tukio la uchimbaji lililochelewa pia huwasilisha muhtasari uliokosa muda wa kukamilisha; null vinginevyo. Ejenti zenye muhtasari lakini zisizo na sehemu za uchimbaji hazitoi tukio hili kamwe: soma muhtasari uliochelewa kutoka GET /v1/calls/{call_id} |
extracted_data.status | string | Daima completed kwa tukio hili |
extracted_data.fields | object | Thamani zilizo na funguo za sehemu za uchimbaji zilizosanidiwa; thamani zisizopatikana ni null |
extracted_data.evidence | object | Ushahidi wenye funguo za sehemu za uchimbaji. Thamani isiyo null ina nukuu kamili iliyokaguliwa kimuundo (isiyozidi herufi 1,000), speaker_role (caller au agent), na turn_index; nukuu ndefu zinazorejeshwa na modeli hukataliwa badala ya kufupishwa, na ushahidi ni null kila wakati sehemu yake ni null |
extracted_data.verification | string | verified tu wakati uchunguzi huru wa ushahidi ulirejesha uamuzi mmoja halali kwa kila sehemu ya mgombea. unavailable inamaanisha uchunguzi ulishindwa, ulizidi muda, haukuwa na bajeti ya kutosha, au ulirejesha towe lisilo sahihi au lisilo kamili. Uchunguzi usiopatikana kabisa huhifadhi thamani zilizoegemezwa kimuundo kwa ukaguzi wa mteja. Kwa towe la sehemu, maamuzi halali hutumika na kila mgombea asiye na uamuzi mmoja halali huwekwa null |
extracted_data.field_reasons | object | Sababu zenye funguo za sehemu zilizowekwa null kwa uegemezaji wa kimuundo au kikaguzi huru |
extracted_data.schema_version | string | Hash ya schema kamili ya sehemu iliyotumika kwa uchimbaji huu |
extracted_at | timestamp | Muda wa kukamilika wa ISO 8601 |
model | string | Modeli iliyotumika kwa uchimbaji |
campaign.completed
Hutumwa mara moja kampeni inapohama kutoka running hadi completed, iwe
ratiba yake imekwisha au waasiliani wote wamefikia hali za mwisho. Majaribio
upya ya runner hayatumi tukio lingine. Tukio hili la mzunguko wa maisha wa
kiwango cha shirika huwasilishwa kwa endpoints za kiwango cha shirika pekee,
si endpoints za kiwango cha ejenti. Haizuii.
{
"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"
}Hesabu nne za matokeo hazina mwingiliano na jumla yake ni contacts_total:
completed ina waasiliani waliofanikiwa; no_answer ina waasiliani waliofeli au kuisha kwa jaribio ambao matokeo yao ya mwisho yalikuwa hakuna jibu; failed ina waasiliani wengine wote waliofeli au kuisha kwa jaribio; na remaining ina waasiliani wanaosubiri, walioratibiwa, au wanaopigiwa simu kwa sasa. Mwasiliani anayesubiri jaribio la kurudia ni remaining, hata kama jaribio lake la hivi karibuni halikupata jibu. Simu zinazoendelea husawazishwa kabla ya muhtasari wa ukamilishaji unaotumwa mara moja pekee. started_at ni mwanzo wa kampeni uliosanidiwa, au muda wa kuundwa kwa kampeni ikiwa hakuna mwanzo uliosanidiwa. skipped si kundi la tano: huhesabu waasiliani ndani ya failed ambao kichujio cha aina ya nambari kiliwamaliza bila simu.
issue.reported
Hutumwa wakati ripoti ya tatizo inaundwa —
ama ikiwasilishwa na mtumiaji kutoka dashboard (source: "user") au
kiotomatiki na ukadiriaji wa simu (source: "system"). Haizuii.
{
"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"
}| Sehemu | Aina | Maelezo |
|---|---|---|
agent_id | integer | null | Ejenti iliyoshughulikia simu, ikiwa moja iliteuliwa |
agent_name | string | null | Ejenti iliyoshughulikia simu, ikiwa moja iliteuliwa |
issue_report.severity | string | critical, warning, au info |
issue_report.status | string | open au resolved |
issue_report.source | string | user (imewasilishwa kutoka dashboard) au system (imeundwa na ukadiriaji) |
issue.escalated
Hutumwa wakati muundo wa tatizo unatumwa kwa ThunderPhone kwa ukaguzi wa wafanyakazi: baada ya Ripoti kwa ThunderPhone, au wakati Fix with AI haiwezi kuthibitisha marekebisho ya upande wa mteja na kuelekeza tatizo kiotomatiki. Endpoints za kiwango cha shirika pekee hupokea tukio hili.
{
"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"
}| Sehemu | Aina | Maelezo |
|---|---|---|
automatic | boolean | true kwa uelekezaji wa kiotomatiki; false kwa uelekezaji wa mikono |
cluster_id | UUID | Muundo wa tatizo ulioelekezwa |
escalation_id | UUID | Rekodi ya uelekezaji |
status | string | open wakati tukio linatumwa |
Hii ni arifa, si kifurushi cha ushahidi. Tumia cluster_id kuihusianisha na
muundo wa tatizo. Tazama Ripoti kwa ThunderPhone.
Matukio ya simu za majaribio
test-call.completed
Hutumwa wakati
utekelezaji wa simu ya majaribio
unafikia hali ya mwisho — completed au failed, ikijumuisha utekelezaji
uliofeli wakati wa kuanzishwa na ambao haukuwahi kutoa simu. Haiwezi kuzuia. Ni muhimu
kwa kuunganisha utekelezaji wa kundi wa CI kwenye mifumo yako ya gumzo/arifa.
{
"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"
}| Sehemu | Aina | Maelezo |
|---|---|---|
agent_id | integer | null | Ejenti iliyoshughulikia simu, ilipokuwa imepewa |
agent_name | string | null | Ejenti iliyoshughulikia simu, ilipokuwa imepewa |
test_call_run.target_type | string | agent au phone_number |
test_call_run.target_id | integer | Kitambulisho cha ejenti au cha nambari ya simu ambacho utekelezaji ulilengwa, kinacholingana na target_type |
test_call_run.status | string | completed au failed |
test_call_run.call_id | integer | null | null wakati utekelezaji ulifeli kabla simu haijapigwa |
test_call_run.error_message | string | Tupu inapofaulu |
Matukio ya arifa
alert.triggered
Hutumwa wakati kanuni ya arifa yenye chaneli ya Wasilisha kwa webhook za wasanidi iliyowashwa inapovuka kizingiti chake. Haiwezi kuzuia. Kanuni huwashwa mara moja kisha huheshimu kipindi chake cha kusubiri, kwa hiyo ukiukaji unaoendelea hutoa tukio moja kwa kila dirisha la kipindi cha kusubiri.
{
"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"
}| Sehemu | Aina | Maelezo |
|---|---|---|
event_id (katika data) | UUID | Kitambulisho cha uwashaji wa arifa — tofauti na event_id ya uwasilishaji ya bahasha |
rule_id, rule_name | UUID, string | Kanuni iliyowashwa |
metric | string | success_rate, failure_rate, avg_score, call_volume, au suite_regression |
comparator | string | lt, lte, gt, au gte |
metric_value | number | Thamani ya kipimo kwenye dirisha wakati kanuni ilipowashwa |
threshold | number | Kizingiti kilichosanidiwa |
window_hours | integer | Dirisha la tathmini linalofuatia |
fired_at | timestamp |
Tazama mwongozo wa Arifa kwa kuunda kanuni, vipimo, vipindi vya kusubiri, na chaneli za barua pepe / Slack.
Matukio ya nambari za simu
phone_number.spam_risk_changed
Hutumwa wakati ufuatiliaji wa lebo za spam (nyongeza ya kulipia, kwa ombi kupitia usaidizi)
unapoona hatari ya spam ya nambari inayofuatiliwa ikiongezeka hadi medium au high (kutoka low, kutoka
kutokuwa na usomaji bado, au kutoka medium hadi high). Haizuii utekelezaji. Nambari inayoendelea
kuwekewa alama haitumwi tena; nambari inayorejea hadi low na kuwekewa alama baadaye hutumwa.
Tukio halina muktadha wa ejenti, kwa hivyo ni vituo vya mwisho vya shirika zima pekee vinavyolipokea.
Wamiliki na wasimamizi wa shirika pia hupokea barua pepe.
{
"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"
}| Uga | Aina | Maelezo |
|---|---|---|
phone_number | mfuatano | Nambari, katika E.164 |
phone_number_id | nambari kamili | null | Kitambulisho chake katika Nambari za Simu |
spam_risk | mfuatano | medium au high |
previous_spam_risk | mfuatano | null | Hatari kwenye usomaji wa mwisho, null kabla ya wa kwanza |
spam_category | mfuatano | null | Lebo ambayo watoa huduma wanaweza kuonyesha, kama vile Telemarketer au Survey. Ichukulie kama maandishi huru |
scores | kitu | 0 hadi 100 kila moja, au null hadi kuwe na kiasi cha kutosha cha simu: maturity (jinsi nambari ilivyojengeka), connection (je, watu hujibu), engagement (je, wanaendelea kwenye simu), sentiment (je, wanaizuia au kuiripoti) |
checked_at | muhuri wa muda | Wakati ThunderPhone iliposoma matokeo |
Matukio ya uhamishaji
migration.call.complete
Hutumwa wakati simu iliyopigwa kupitia
POST /v1/migrations/{id}/calls inaisha,
bila kujali ni jukwaa gani lililoipokea. Haiathiri utekelezaji. Hufika hadi takriban dakika 5
baada ya simu kuisha. data ina kila sehemu ya
telephony.complete pamoja na bloku ya migration. Simu
iliyopigwa na ThunderPhone pia hutuma telephony.complete kama kawaida, ikiwa na
call_id sawa. answered_by ni null kwa simu iliyopokelewa na jukwaa lingine. Simu kwenye jukwaa lingine ambayo haijaisha baada ya saa 2,
au ambayo uhamishaji wake umekamilika au kupoteza ufunguo wake kwanza, hutumwa ikiwa na
status: "unknown" na bila transkripti.
{
"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"
}| Sehemu | Aina | Maelezo |
|---|---|---|
migration.id | UUID | Uhamishaji |
migration.routing_id | UUID | Simu iliyoelekezwa, kama ilivyorejeshwa ulipoipiga |
migration.arm | string | ours (ThunderPhone iliipiga) au vendor (jukwaa lingine liliipiga) |
migration.vendor | string | retell, vapi, elevenlabs, au bland |
migration.vendor_call_id | string | null | Kitambulisho cha simu cha jukwaa lingine; null kwa ours |
migration.metadata | object | metadata uliyotuma ulipopiga simu |
migration.vendor_cost_usd | string | null | Gharama ambayo jukwaa lingine liliripoti kwa simu, lilipotoa taarifa hiyo |
call_id | integer | null | Kitambulisho cha simu cha ThunderPhone; null kwa vendor |
status | string | Kwa vendor: completed wakati mpokeaji wa simu alizungumza, failed wakati hakuzungumza, unknown kama ilivyoelezwa hapo juu. Kwa ours: kama ilivyo katika telephony.complete |
Kwa simu ya vendor, ThunderPhone haina data ya utozaji au uchimbaji:
billable_minutes, billing_total_cents na extracted_data ni null,
product na voice ni tupu, recording_mode ni vendor, na
recording_url ni kiungo cha jukwaa lingine, lilipotoa kiungo.
migration.rollback
Hutumwa wakati ubadilishaji wa taratibu wa uhamishaji unaporudisha simu zote kwenye jukwaa jingine wenyewe: simu 3 zilishindwa kuunganishwa na ThunderPhone ndani ya dakika 15, simu 2 zilizotumwa kwa ThunderPhone ziliisha kabla ejenti hajajibu, au kiwango cha matokeo ya kazi cha ThunderPhone kilishuka zaidi ya pengo lililosanidiwa chini ya kile cha jukwaa jingine. Haizuii utekelezaji, mara moja kwa kila urejeshaji. Baada yake, sehemu ya ThunderPhone ni 0% na uhamishaji unasitishwa hadi mtu aendeleze tena kwenye kichupo cha Uhamishaji cha ejenti. Payload haina namba za simu, nakala za mazungumzo au vitambulisho vya simu.
{
"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"
}| Sehemu | Aina | Maelezo |
|---|---|---|
migration_id | UUID | Uhamishaji |
vendor | string | retell, vapi, elevenlabs, au bland |
reason | string | ours_failed_burst (miunganisho 3 iliyoshindwa ndani ya dakika 15), dropped_calls (simu 2 ziliisha kabla ejenti hajajibu, ndani ya dakika 30), au rate_gap (pengo la kiwango cha matokeo ya kazi katika angalau simu zilizopimwa rollback_min_calls kwa kila upande) |
previous_percent | integer | Sehemu ya simu za ThunderPhone kabla ya urejeshaji |
ours_percent | integer | Daima 0 |
step | integer | null | Hatua ya ratiba iliyokuwa ikitumika (ikianza na 0) |
ours / theirs | object | null | Simu zilizopimwa katika hatua ya sasa na kiwango chake cha mafanikio; theirs inaweza kuwa ya siku 30 zilizopita wakati hatua ina simu chache sana. null wakati hazikuwepo |
ours_failed | integer | Miunganisho iliyoshindwa iliyohesabiwa katika dakika 15 zilizopita |
dropped | integer | Simu zilizohesabiwa kuwa zimekatika katika dakika 30 zilizopita |
rolled_back_at | timestamp |
Yanayohusiana
Payload ya simu zinazoingia inayozuia ambayo lazima uijibu.
Nakala ya mazungumzo na vipimo baada ya simu.
Sajili URL kwa kikundi kidogo cha matukio haya.
Jinsi matukio ya telephony.tool / web.tool yanavyozalishwa.