Open in
Каталог на събитията
Всички типове webhook събития, които ThunderPhone изпраща.
Всяко тяло на webhook има поле type, чиято стойност е един от типовете
събития на тази страница. Когато се абонирате за
крайна точка, масивът events трябва да съдържа
желаните от вас типове събития (или да е празен, за да се абонирате за всички —
с изключение на събитията за всеки ход telephony.turn /
web.turn и събитието за напредък в реално време
call.status_changed, които се доставят само
до крайни точки, които ги посочват изрично).
Тези събития се доставят по два начина:
- Доставките до крайна точка винаги са неблокиращи известия
с повторни опити: отговорете с
произволен 2xx; обвивката съдържа
event_idза дедупликация. - Блокиращите обмени се изпълняват само чрез
наследения webhook с един URL: заявката за
конфигурация
telephony.incoming/web.incoming(номера в webhook режим: 13 s, включително един повторен опит; ключове за уиджети в webhook режим: 10 s) и изпращането на инструменти в webhook режим. Вашият отговор оформя разговора на живо.
Примерните полезни товари по-долу показват обвивката на крайната точка в нейния
ред при предаване по мрежата (ключовете са сортирани по азбучен ред: data,
event_id, type); остарелите доставки съдържат същото data без event_id.
Събития за обаждания
telephony.incoming
Изпраща се, когато входящо обаждане достигне един от вашите
телефонни номера. Доставките към крайните точки са
уведомления тип „изпрати и забрави“ за всяко входящо обаждане, независимо
дали номерът е конфигуриран за агент или за webhook. Номерата без
назначен агент допълнително получават заявката за блокираща
конфигурация към наследения webhook — вижте
telephony.incoming / web.incoming за
пълната схема на заявката/отговора.
{
"data": {
"call_id": 987654321,
"from_number": "+14155550199",
"to_number": "+15551234567"
},
"event_id": "3f6b2ad0-1c9e-4a57-9f2b-8f6f0f9d2f11",
"type": "telephony.incoming"
}| Поле | Тип | Описание |
|---|---|---|
agent_id | цяло число | null | Агентът, обработил обаждането, когато е бил назначен такъв |
agent_name | низ | null | Агентът, обработил обаждането, когато е бил назначен такъв |
returning_call | обект | Присъства само когато номерът е позвънил на този обаждащ се през последните 30 дни: call_id, agent_id, started_at и outcome на предишното обаждане. Вижте Обратни обаждания |
sip_headers | обект | Присъства само когато обаждането е пристигнало със SIP заглавки X-* или User-to-User (SIP адреси и ръчни SIP връзки): име на заглавка с малки букви → стойност. Вижте SIP заглавки |
telephony.complete
Изпраща се, когато входящо или изходящо телефонно обаждане приключи. Неблокиращо.
Включва транскрипцията, URL адреса на записа, когато е наличен, и обобщение на таксуването. Вижте
telephony.complete / web.complete за
схемата на payload-а.
| Поле | Тип | Описание |
|---|---|---|
agent_id | integer | null | Агентът, обработил обаждането, когато е бил назначен такъв |
agent_name | string | null | Агентът, обработил обаждането, когато е бил назначен такъв |
telephony.tool
Изпраща се, след като телефонно обаждане извика
инструмент за функция. Неблокиращо уведомление за одит —
инструментът вече е изпълнен, когато това събитие бъде доставено; то обхваща
вашите собствени инструменти за функции и вградения инструмент send_sms (но не други вградени
инструменти, инструменти за база знания, връзка с приложение или MCP инструменти). За send_sms
и arguments.to, и arguments.body са [REDACTED]. Те също са редактирани
в транскрипциите след приключване; извлечете съдържанието и получателя от
SMS ресурса с обхват на организацията, като използвате message_id от отговора.
{
"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 е резултатът от изпълнението: {"status": <http status>, "response": <your endpoint's JSON>} при успех или
{"status": <status>, "error": "<message>"} при неуспех.
| Поле | Тип | Описание |
|---|---|---|
agent_id | integer | null | Агентът, обработил обаждането, когато е бил назначен такъв |
agent_name | string | null | Агентът, обработил обаждането, когато е бил назначен такъв |
telephony.turn
Изпраща се, докато телефонно обаждане е в ход, по веднъж за всеки
ход, съдържащ реч, в момента на възникването му — изговорените от агента завършвания и
транскрибираните ходове на обаждащия се. Позволява ви да следите разговора
на живо чрез обикновени webhooks вместо чрез polling на
GET /v1/calls/{call_id}/transcript.
Неблокиращо.
{
"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"
}| Поле | Тип | Описание |
|---|---|---|
agent_id | integer | null | Агентът, обработил обаждането, когато е бил назначен такъв |
agent_name | string | null | Агентът, обработил обаждането, когато е бил назначен такъв |
position | integer | Индексът на хода в хронологията на обаждането — стабилен идентификатор за подреждане |
role | string | assistant (реч на агента) или user (реч на обаждащия се) |
text | string | Текстът от транскрипцията на хода, наличен към момента на изпращане |
entry_type | string | Типът на основния запис в хронологията: completion (агент) или user_turn / span (обаждащ се) |
start_ms, end_ms | integer | Аудио отмествания в ms от началото на обаждането; налични само когато времето за възпроизвеждане вече е било известно към момента на изпращане |
web.incoming
Еквивалентът на telephony.incoming за уеб канала, изпращан при стартиране на
сесия на уеб джаджа или тестово обаждане с микрофон в конструктора.
Доставките към крайните точки са уведомления тип „изпрати и забрави“ за всяка уеб сесия.
Публикуемите ключове в mode="webhook" допълнително получават
заявката за блокираща конфигурация към наследения webhook — тази
блокираща заявка има различна структура (origin_domain,
publishable_key_prefix; без телефонни номера). Вижте
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 винаги е буквалната стойност "web". За сесии на джаджи в режим webhook
to_number е празно (номерът на агента за сесията се назначава
след конфигурирането); за тестови обаждания с микрофон в конструктора origin_domain и
publishable_key_prefix са празни.
| Поле | Тип | Описание |
|---|---|---|
agent_id | integer | null | Агентът, обработил обаждането, когато е бил назначен такъв |
agent_name | string | null | Агентът, обработил обаждането, когато е бил назначен такъв |
web.complete
Еквивалентът на telephony.complete за уеб канала, обхващащ обаждания от
уеб джаджа (direction: "web") и тестови обаждания с микрофон в конструктора
(direction: "test"). Неблокиращо. Същата структура на payload-а като
telephony.complete, плюс origin_domain,
като from_number е зададено на "web".
| Поле | Тип | Описание |
|---|---|---|
agent_id | integer | null | Агентът, обработил обаждането, когато е бил назначен такъв |
agent_name | string | null | Агентът, обработил обаждането, когато е бил назначен такъв |
web.tool
Еквивалентът на telephony.tool за уеб канала. data съдържа
origin_domain вместо from_number / to_number.
| Поле | Тип | Описание |
|---|---|---|
agent_id | integer | null | Агентът, обработил обаждането, когато е бил назначен такъв |
agent_name | string | null | Агентът, обработил обаждането, когато е бил назначен такъв |
web.turn
Еквивалентът на telephony.turn за уеб канала,
обхващащ обаждания от уеб джаджа и тестови обаждания с микрофон в конструктора. Същата структура
на payload-а, с origin_domain вместо from_number / to_number.
Подобно на telephony.turn, той изисква изричен абонамент —
никога не се доставя чрез празен масив events.
| Поле | Тип | Описание |
|---|---|---|
agent_id | integer | null | Агентът, обработил обаждането, когато е бил назначен такъв |
agent_name | string | null | Агентът, обработил обаждането, когато е бил назначен такъв |
call.transfer_completed
Изпраща се веднъж за всяко обаждане с крайния резултат от
прехвърляне на обаждане: студено прехвърляне или моста
между хората, който остава след топло прехвърляне, когато агентът се оттегли.
Не блокира и се доставя само до крайни точки (никога до наследения
уебхук с един URL). Пристига след telephony.complete на обаждането:
когато операторът поеме обаждането или прехвърлянето е неуспешно, или когато
ThunderPhone е свързал обаждането чрез мост — след като мостът приключи.
{
"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"
}| Поле | Тип | Описание |
|---|---|---|
call_id | integer | Обаждането, което е прехвърлено |
agent_id | integer | null | Агентът, обработил обаждането, когато е бил назначен такъв |
agent_name | string | null | Агентът, обработил обаждането, когато е бил назначен такъв |
transfer_outcome | string | refer_accepted: операторът пое обаждането. bridged: ThunderPhone запази връзката между обаждащия се и целевия номер, защото операторът е отказал студено прехвърляне или защото агентът при топло прехвърляне се е оттеглил. bridge_unanswered: операторът отказа студено прехвърляне и целевият номер не отговори на собственото обаждане на ThunderPhone. failed: прехвърлянето не е осъществено и обаждането е приключило |
destination | string | null | Номерът, към който е прехвърлено обаждането |
sip_status | integer | null | SIP статусът на оператора, когато е отказал студеното прехвърляне: 403 (например Twilio trunk без прехвърляне на обаждания), 405 или 501. null, когато операторът не го е отказал |
bridge_kind | string | null | Само при bridged: cold_fallback (отказано студено прехвърляне, което ThunderPhone е свързал) или warm (двамата участници при топло прехвърляне, след като агентът се е оттеглил) |
bridge_seconds | integer | null | Само при bridged: времето на свързването чрез мост, таксувано от ThunderPhone, в секунди |
bridge_total_cents | integer | null | Само при bridged: цената на моста в центове USD след приспадане на евентуален безплатен кредит за обаждания, таксувана отделно от billing_total_cents на обаждането |
Същите стойности се намират в обекта на обаждането
като transfer_outcome, transfer_destination, transfer_sip_status,
transfer_bridge_kind, transfer_bridge_seconds и
transfer_bridge_total_cents. event_id е еднакъв при всяка доставка
за дадено обаждане, така че повторен отчет никога не създава второ събитие.
call.billed
Изпраща се за обаждане, таксувано според измереното потребление: когато таксата му бъде финализирана, няколко
минути след края на обаждането, след като данните за потреблението му са налични, и отново винаги когато
постъпило по-късно потребление увеличи таксата. Събитието на обаждането
telephony.complete / web.complete
съдържа billing_pending: true и null полета за таксуване. Не блокира
и се доставя само до крайни точки (никога до наследения webhook с един URL).
Обажданията, таксувани при приключването си, съдържат данните за таксуването в събитието за завършване
и не получават call.billed.
Редът не е гарантиран: таксата обикновено изчаква събитието за завършване,
но call.billed може да пристигне преди него (събитие за завършване, задържано
за час, или доставки, повторени по различно време), а две събития
call.billed могат да пристигнат в неправилен ред. Запазете събитието с
най-висок billing_seq за всеки 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"
}| Поле | Тип | Описание |
|---|---|---|
call_id | цяло число | Обаждането, което е таксувано |
agent_id | цяло число | null | Агентът, обработил обаждането, когато е бил назначен такъв |
agent_name | низ | null | Агентът, обработил обаждането, когато е бил назначен такъв |
reason | низ | settled: таксата за обаждането. adjusted: потребление, постъпило след таксата и увеличило стойността ѝ (таксата никога не се намалява) |
billing_seq | цяло число | 1 за таксата, след това 2, 3, ... за всяко увеличение. Най-високата получена стойност е текущото таксуване на обаждането |
billable_minutes | число | Таксувани минути, закръглени до най-близката четвърт минута |
billing_total_cents | цяло число | Всичко, начислено досега за обаждането в центове USD, след приспадане на всеки безплатен кредит за обаждания, включително увеличенията adjusted |
adjustment_cents | цяло число | null | Само за adjusted: това увеличение в центове USD, след приспадане на всеки безплатен кредит за обаждания |
Същите общи стойности са в обекта на обаждането
като billable_minutes и billing_total_cents. event_id е един и същ при
всяка доставка на един billing_seq, така че повторен отчет никога не създава
второ събитие.
call.status_changed
Изпраща се, докато обаждането е в ход, всеки път когато достигне нов етап: ThunderPhone започва да набира, човекът или неговият телефон отговаря, агентът достигне гласова поща или агентът бъде поставен в изчакване и след това изведен от него. Използвайте го, за да показвате напредъка на текущо обаждане, например „Набиране…“, „Отговорено“, „В изчакване“ и „Изведено от изчакване след 4 минути“ в чат нишка, която следва обаждането. Не блокира и се доставя само до крайни точки (никога до наследения уебхук с един URL адрес).
{
"data": {
"agent_id": 12,
"agent_name": "Front desk",
"call_id": 987654321,
"direction": "outbound",
"hold_seconds": 240,
"occurred_at": "2026-11-07T17:04:12.418Z",
"status": "off_hold"
},
"event_id": "2f6a1c9e-3b7d-5e8f-9a0b-4c5d6e7f8a9b",
"type": "call.status_changed"
}| Поле | Тип | Описание |
|---|---|---|
call_id | integer | Обаждането |
agent_id | integer | null | Агентът, обработил обаждането, когато е назначен такъв |
agent_name | string | null | Агентът, обработил обаждането, когато е назначен такъв |
direction | string | Посоката на обаждането, както в обекта за обаждане |
status | string | Етапът, достигнат от обаждането; вижте таблицата по-долу |
occurred_at | timestamp | Кога се е случило |
hold_seconds | integer | null | Само за off_hold: колко дълго е продължило изчакването в секунди. null за всеки друг статус |
status | Кога се изпраща |
|---|---|
dialing | Изходящи обаждания: ThunderPhone осъществява обаждането. Изпраща се непосредствено преди набирането да бъде предадено на телекомуникационния доставчик, след като е премината всяка проверка, която може да откаже обаждането. Тестовите обаждания, стартирани от таблото за управление, не го изпращат |
answered | Изходящи обаждания: телекомуникационният доставчик е отчел, че на обаждането е отговорено. Отговор от гласова пощенска кутия или система за филтриране на обаждания също се брои, така че може да последва voicemail. Когато ThunderPhone разбере за отговора едва от отчета в края на обаждането, answered се изпраща при приключване на обаждането |
voicemail | Изходящи обаждания: агентът е достигнал гласова пощенска кутия и оставя съобщението си или прекратява разговора, както указва voicemail_action на агента. Изпраща се, когато пощенската кутия е потвърдена (по нейния сигнал или по липсата на отговор), а не при първо предположение |
on_hold | Агентът е поставен в изчакване и чака без звук (инструментът wait_on_hold) |
off_hold | Човек се е върнал на линията и агентът отново разговаря. hold_seconds указва колко дълго е продължило изчакването |
Всяко обаждане изпраща всеки статус най-много веднъж, с изключение на on_hold и off_hold,
които се изпращат веднъж за всяко изчакване. Типично изходящо обаждане, което чака в изчакване,
изпраща dialing, answered, on_hold, off_hold, а след това
telephony.complete, когато приключи.
Позвъняването не се отчита: дали даден оператор сигнализира за позвъняване варира твърде много, за да може да се разчита на това. При малкото обаждания с voicemail_action: "prompt", при които подканата на агента, а не ThunderPhone, решава какво да се направи при гласова поща, не се изпраща статус voicemail; answered_by в telephony.complete все пак е voicemail. Полезните товари не съдържат транскрипция, телефонни номера или променливи, така че call.status_changed се изпраща дори за обаждания, при които записът е изключен.
SMS събития
SMS събитията описват съобщения, изпратени чрез свързания Twilio или Telnyx акаунт на организацията. Текстът на съобщението се пропуска, а to се редактира.
Извлечете съобщението в обхвата на организацията чрез
GET /v1/sms/{message_id}, когато са необходими неговото съдържание или получателят. source е api, agent_tool, followup
или pre_call (текстът на кампанията преди обаждане), както е описано в
обекта на съобщението.
Всяко SMS събитие съдържа scheduled_send_id: идентификатора на
планираното изпращане, за което е изпратено съобщението, или
null за съобщение, което не е било планирано. Планираните съобщения имат source
"scheduled".
sms.sent
Изпраща се, когато операторът на клиента приеме заявка за изходящ SMS. Това не е потвърждение за доставяне до устройство.
{
"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
Изпраща се след постоянно отхвърляне от оператора, след изчерпване на временните повторни опити, когато резултатът е окончателно неизвестен или когато Twilio отчете прието съобщение като недоставено или неуспешно. В последния случай sms.sent на съобщението вече е изпратено, а status остава "accepted". error_code е стабилен код на ThunderPhone, а error_message посочва действието, което клиентът трябва да предприеме, когато е налично такова. status: "unknown" означава, че операторът може да е приел SMS-а; сверете го в регистрационния журнал на оператора, защото ThunderPhone няма да го изпрати повторно автоматично.
sms.received
Запазено за поддръжка на входящи SMS-и. В текущата версия не се изпращат
събития sms.received. Конфигурирането на webhook за входящи съобщения от
оператор и проверката на подписа ще бъдат предоставени отделно.
Планирани събития
Планираните изпращания, които не се изпращат, задействат едно
от тези събития. Изпращане, което се изпълни, вместо това задейства обичайните събития:
събитията sms.* със зададено scheduled_send_id за текстово съобщение, събитията за обаждане за
обаждане, със scheduled_send_id в неговото telephony.complete. И двете не блокират. Когато
изпращането има агент, крайните точки с обхват за този агент също ги получават.
Полезният товар съдържа само идентификатори, статус и времена: никога съдържанието на текстовото
съобщение или променливите и контекста на обаждането, а to е редактирано. Извлечете
GET /v1/scheduled/{id}
за останалото.
scheduled.skipped
Изпраща се, когато дадено изпращане умишлено не бъде изпратено. reason е expired (то не е могло
да бъде изпратено преди expires_at), opted_out (номерът е в
списъка за отказ, включително ако е добавен след създаването на изпращането),
quiet_hours (то е станало дължимо извън периода от 8:00 до 21:00 ч. в часовата зона на
получателя), sender_not_ready (номерът за текстови съобщения вече не може да изпраща)
или outbound_tcpa_unconfirmed (обаждане е станало дължимо, преди да бъде записано
потвърждението по TCPA на организацията).
{
"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
Изпраща се, когато ThunderPhone е направил опит за изпращане, но то не е било успешно. reason е собствената грешка на изпращането: код за грешка при SMS, като carrier_rejected за текстово съобщение, или причина за отказ или неуспех на обаждането, като например правилото за блокирана дестинация (premium_rate, например) или agent_deleted. Полезният товар има същите полета като scheduled.skipped.
| Поле | Тип | Описание |
|---|---|---|
id | string | Идентификаторът на планираното изпращане |
type | string | sms или call |
status | string | skipped или failed |
reason | string | Причината, както е описано по-горе; същата стойност като status_reason на изпращането |
detail | string | Разбираемо обяснение |
source | string | Какво е създало изпращането: api |
external_id | string | null | Вашият ключ за изпращането или null |
from_number | string | Номер за изпращане |
to | string | Винаги "[REDACTED]" |
agent_id | integer | null | Обаждания: агентът; текстови съобщения: null |
send_at, expires_at, created_at | timestamp | ISO 8601 |
Гласови събития
Създаването на персонализиран глас е асинхронно. Тези неблокиращи събития Ви позволяват да реагирате на краен резултат, вместо да правите периодични заявки към крайната точка за подробности за клониране.
voice.ready и voice.failed се доставят само до крайна точка за цялата
организация с events: []. Те не могат да бъдат избрани като изрични филтри за
събития.
voice.ready
Изпраща се, когато обработката на персонализиран глас завърши и той може да бъде назначен на агент.
{
"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
Изпраща се, когато обработката на персонализиран глас достигне до окончателна грешка.
{
"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"
}| Поле | Тип | Описание |
|---|---|---|
voice.id | низ | Публичен идентификатор на персонализирания глас |
voice.name | низ | Стойност за гласа на агента във формата custom:<public_id> |
voice.display_name | низ | Име на гласа, видимо за организацията |
voice.language | низ | Кодът за единствения език на клонирания глас |
voice.gender | низ | male, female или празен низ |
voice.status | низ | ready за voice.ready; failed за voice.failed |
voice.failure_reason | низ | Празно при успех; подробности за грешката при обработка при неуспех |
voice.created_at, voice.updated_at | времеви печат | Времеви печати по ISO 8601 |
reason | низ | Подробности за грешката; присъства само при voice.failed |
Събития за качество
call.graded
Изпраща се винаги когато изпълнение на AI оценяване завърши за разговор. Не блокира изпълнението.
{
"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"
}| Поле | Тип | Описание |
|---|---|---|
agent_id | integer | null | Агентът, обработил обаждането, когато е бил назначен такъв |
agent_name | string | null | Агентът, обработил обаждането, когато е бил назначен такъв |
grade.id | integer | Идентификатор на оценката |
grade.score | integer | null | 0–100 |
grade.call_outcome | string | success, failure, unknown или no_conversation |
grade.summary | string | Резюме в един абзац |
grade.detected_issues | array | Низове с проблеми, открити от оценителя |
grade.status | string | Винаги completed — изпращат се само завършени изпълнения |
grade.grader_model | string | Кой оценител е генерирал резултата: heuristic-v1 (или друг базиран на правила оценител на ThunderPhone) за бърза предварителна оценка, thunderphone-grader за пълната оценка. Това е етикет на ThunderPhone, а не име на AI модел |
grade.graded_at, grade.created_at | timestamp | |
report | object | null | Отчетът за обаждането, видим за клиента: етикет за резултата, флаг и причина за необходимо внимание, обаждащ се, едноредово резюме, преживяване на обаждащия се. При ранна евристична оценка той е null или отчет със статус pending, чиито полета са заместители; събитието за пълната оценка съдържа завършения отчет |
call.data_extracted
Изпраща се винаги когато извличането на структурирани данни завърши успешно,
включително при късен повторен опит след telephony.complete / web.complete
или ръчно повторно изпълнение чрез
POST /v1/calls/{call_id}/extract.
Не блокира изпълнението.
В режим на блокиращо извличане събитието за завършване обикновено изчаква не
повече от 75-секундния бюджет за извличане. Ако процесът на работника за
извличане бъде изгубен, продукционното изчистване при финализиране (на всеки
пет минути) изпраща завършване, чийто blocking_deadline_at е изтекъл, преди
да започне друг опит за извличане. По-късен успех се доставя отделно чрез това
събитие.
{
"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"
}| Поле | Тип | Описание |
|---|---|---|
agent_id | цяло число | null | Агентът, обработил разговора, когато е бил назначен такъв |
agent_name | низ | null | Агентът, обработил разговора, когато е бил назначен такъв |
summary | низ | null | Завършеното обобщение на разговора, когато за агента е включено Генериране на обобщение на разговора, така че събитие за късно извличане също предоставя обобщение, пропуснало прозореца за завършване; в противен случай null. Агентите с обобщение, но без полета за извличане, никога не изпращат това събитие: прочетете късно обобщение от GET /v1/calls/{call_id} |
extracted_data.status | низ | Винаги completed за това събитие |
extracted_data.fields | обект | Стойности с ключове, съответстващи на конфигурираните ключове на полетата за извличане; недостъпните стойности са null |
extracted_data.evidence | обект | Доказателства с ключове, съответстващи на полетата за извличане. Стойност, различна от null, съдържа точния структурно проверен цитат (до 1 000 знака), speaker_role (caller или agent) и turn_index; по-дългите цитати, върнати от модела, се отхвърлят вместо да се съкращават, а доказателството е null, когато полето му е null |
extracted_data.verification | низ | verified само когато независимата проверка на доказателствата е върнала точно една валидна оценка за всяко кандидат-поле. unavailable означава, че проверката е неуспешна, изтекло е времето ѝ, не е разполагала с достатъчен бюджет или е върнала неправилно форматиран или частичен изход. Изцяло недостъпна проверка запазва структурно обоснованите стойности за преглед от клиента. При частичен изход се прилагат валидните оценки и всеки кандидат без точно една валидна оценка се задава на null |
extracted_data.field_reasons | обект | Причини с ключове, съответстващи на полетата, зададени на null чрез структурно обосноваване или от независимия проверяващ механизъм |
extracted_data.schema_version | низ | Хеш на точната схема на полетата, използвана за това извличане |
extracted_at | времеви отпечатък | Време на завършване по ISO 8601 |
model | низ | Винаги thunderphone-extractor: етикет на ThunderPhone за модела за извличане, а не името на AI модел |
campaign.completed
Изпраща се еднократно, когато кампания премине от running към completed,
независимо дали графикът ѝ е приключил или всички контакти са достигнали крайни
състояния. Повторните опити на изпълнителя не изпращат друго събитие. Това
събитие от жизнения цикъл на ниво организация се доставя само до крайни точки
с обхват на организацията, а не до крайни точки с обхват на агент. Не блокира
изпълнението.
{
"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"
}Четирите броя резултати не се припокриват и сборът им е равен на contacts_total:
completed съдържа успешните контакти; no_answer съдържа контактите с неуспешен/изчерпан краен статус, чийто краен резултат е липса на отговор; failed съдържа всички други контакти с неуспешен/изчерпан краен статус; а remaining съдържа чакащите, насрочените или контактите, към които в момента се извършва обаждане. Контакт, който чака повторен опит, е в remaining, дори когато последният му опит е завършил без отговор. Текущите обаждания се съгласуват преди еднократната моментна снимка при завършване. started_at е конфигурираният старт на кампанията или моментът на създаване на кампанията, когато не е конфигуриран старт. skipped не е пета категория: той отчита контактите в failed, които филтърът по тип номер е приключил без обаждане.
issue.reported
Изпраща се при създаване на доклад за проблем —
или подаден от потребител от таблото за управление (source: "user"), или
автоматично чрез оценяване на разговор (source: "system"). Не блокира
изпълнението.
{
"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"
}| Поле | Тип | Описание |
|---|---|---|
agent_id | integer | null | Агентът, обработил разговора, когато е назначен такъв |
agent_name | string | null | Агентът, обработил разговора, когато е назначен такъв |
issue_report.severity | string | critical, warning или info |
issue_report.status | string | open или resolved |
issue_report.source | string | user (подаден от таблото за управление) или system (създаден чрез оценяване) |
issue.escalated
Изпраща се, когато модел на проблем бъде изпратен до ThunderPhone за преглед от служители: след Докладване до ThunderPhone или когато „Поправяне с AI“ не може да потвърди корекция от страна на клиента и автоматично насочи проблема. Само крайните точки за цялата организация получават това събитие.
{
"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"
}| Поле | Тип | Описание |
|---|---|---|
automatic | boolean | true за автоматична ескалация; false за ръчна ескалация |
cluster_id | UUID | Ескалиран модел на проблем |
escalation_id | UUID | Запис за ескалация |
status | string | open при изпращане на събитието |
Това е известие, а не пакетът с доказателства. Използвайте cluster_id, за да
го свържете с модела на проблема. Вижте
Докладване до ThunderPhone.
Събития за тестови обаждания
test-call.completed
Изпраща се, когато
изпълнение на тестово обаждане
достигне краен статус — completed или failed, включително изпълнения,
които са неуспешни при стартиране и никога не са създали обаждане. Не блокира
изпълнението. Полезно за свързване на пакетни CI изпълнения със системите ви
за чат и известия.
{
"data": {
"test_call_run": {
"call_id": 987654321,
"completed_at": "2026-04-20T18:25:04.822Z",
"error_message": "",
"id": 7110,
"status": "completed",
"target_id": 12,
"target_type": "agent"
}
},
"event_id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
"type": "test-call.completed"
}| Поле | Тип | Описание |
|---|---|---|
agent_id | integer | null | Агентът, който е обработил обаждането, когато е назначен такъв |
agent_name | string | null | Агентът, който е обработил обаждането, когато е назначен такъв |
test_call_run.target_type | string | agent или phone_number |
test_call_run.target_id | integer | Идентификаторът на агента или телефонния номер, към който е насочено изпълнението, съответстващ на target_type |
test_call_run.status | string | completed или failed |
test_call_run.call_id | integer | null | null, когато изпълнението е неуспешно преди осъществяване на обаждане |
test_call_run.error_message | string | Празно при успех |
Събития за предупреждения
alert.triggered
Изпраща се, когато правило за предупреждение с активиран канал Доставяне до уебхукове за разработчици премине своя праг. Не блокира изпълнението. Правилото се задейства веднъж и след това спазва периода си на изчакване, така че продължително нарушение генерира по едно събитие за всеки прозорец на изчакване.
{
"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"
}| Поле | Тип | Описание |
|---|---|---|
event_id (в data) | UUID | Идентификаторът на задействането на предупреждението — различен от event_id за доставката в обвивката |
rule_id, rule_name | UUID, string | Правилото, което се е задействало |
metric | string | success_rate, failure_rate, avg_score, call_volume или suite_regression |
comparator | string | lt, lte, gt или gte |
metric_value | number | Стойността на метриката за прозореца, когато правилото се е задействало |
threshold | number | Конфигурираният праг |
window_hours | integer | Плъзгащ се прозорец за оценяване |
fired_at | timestamp |
Вижте ръководството за предупреждения за създаване на правила, метрики, периоди на изчакване и каналите за имейл / Slack.
Събития за телефонни номера
phone_number.spam_risk_changed
Изпраща се, когато наблюдението на етикетите за спам (платена добавка, заявявана чрез техническата поддръжка) установи, че рискът от спам за наблюдаван номер се е повишил до medium или high (от low, при все още липсващо отчитане или от medium до high). Не блокира изпълнението. Номер, който остава маркиран, не се изпраща повторно; номер, чийто риск се възстанови до low и по-късно бъде маркиран, се изпраща отново. Събитието няма контекст на агент, затова го получават само крайни точки за цялата организация. Собствениците и администраторите на организацията също получават имейл.
{
"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"
}| Поле | Тип | Описание |
|---|---|---|
phone_number | низ | Номерът във формат E.164 |
phone_number_id | цяло число | null | Неговият идентификатор в Телефонни номера |
spam_risk | низ | medium или high |
previous_spam_risk | низ | null | Рискът при последното отчитане; null преди първото |
spam_category | низ | null | Етикетът, който операторите може да показват, например Telemarketer или Survey. Третирайте го като свободен текст |
scores | обект | От 0 до 100 за всеки показател или null, докато няма достатъчен обем обаждания: maturity (доколко номерът е утвърден), connection (дали хората отговарят), engagement (дали остават на линията), sentiment (дали го блокират или докладват) |
checked_at | времеви отпечатък | Кога ThunderPhone е получил резултата |
Събития за миграция
migration.call.complete
Изпраща се, когато разговор, осъществен чрез
POST /v1/migrations/{id}/calls, приключи,
независимо коя платформа го е приела. Не блокира. Пристига до около 5 минути
след приключване на разговора. data съдържа всяко поле от
telephony.complete плюс блок migration. Разговор,
осъществен от ThunderPhone, също изпраща telephony.complete както обикновено,
със същия call_id. answered_by е null за разговор, приет от другата
платформа. Разговор на другата платформа, който не е приключил след 2
часа или чиято миграция първо е приключила или е загубила ключа си, се изпраща
с status: "unknown" и без транскрипция.
{
"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"
}| Поле | Тип | Описание |
|---|---|---|
migration.id | UUID | Миграцията |
migration.routing_id | UUID | Маршрутизираният разговор, както е върнат при осъществяването му |
migration.arm | string | ours (ThunderPhone го е осъществил) или vendor (другата платформа го е осъществила) |
migration.vendor | string | retell, vapi, elevenlabs или bland |
migration.vendor_call_id | string | null | Идентификаторът на разговора в другата платформа; null за ours |
migration.metadata | object | metadata, които сте изпратили при осъществяването на разговора |
migration.vendor_cost_usd | string | null | Цената на разговора, отчетена от другата платформа, ако е предоставила такава |
call_id | integer | null | Идентификаторът на разговора в ThunderPhone; null за vendor |
status | string | За vendor: completed, когато получателят е говорил, failed, когато не е говорил, unknown както е описано по-горе. За ours: както в telephony.complete |
За разговор с vendor ThunderPhone няма данни за таксуване или извличане:
billable_minutes, billing_total_cents и extracted_data са null,
product и voice са празни, recording_mode е vendor, а
recording_url е връзката от другата платформа, ако тя е предоставила такава.
migration.rollback
Изпраща се, когато постепенното превключване на миграция самостоятелно върне всяко обаждане към другата платформа: 3 обаждания не са успели да се свържат с ThunderPhone в рамките на 15 минути, 2 обаждания, изпратени към ThunderPhone, са приключили преди агентът да отговори или процентът на успешно изпълнени задачи на ThunderPhone е спаднал под този на другата платформа с повече от конфигурираната разлика. Неблокиращо, веднъж за всяко връщане назад. След това делът на ThunderPhone е 0%, а миграцията е поставена на пауза, докато някой не я възобнови в раздела „Миграция“ на агента. Полезният товар не съдържа телефонни номера, транскрипции или идентификатори на обаждания.
{
"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"
}| Поле | Тип | Описание |
|---|---|---|
migration_id | UUID | Миграцията |
vendor | низ | retell, vapi, elevenlabs или bland |
reason | низ | ours_failed_burst (3 неуспешни връзки за 15 минути), dropped_calls (2 обаждания са приключили преди агентът да отговори, в рамките на 30 минути) или rate_gap (разлика в процента на успешно изпълнени задачи при поне rollback_min_calls оценени обаждания за всяка страна) |
previous_percent | цяло число | Делът на обажданията на ThunderPhone преди връщането назад |
ours_percent | цяло число | Винаги 0 |
step | цяло число | null | Стъпката от графика, на която се е намирала миграцията (с индексиране от 0) |
ours / theirs | обект | null | Оценените обаждания в текущата стъпка и техният процент на успех; theirs може да обхваща последните 30 дни, когато стъпката има твърде малко обаждания. null, когато няма такива |
ours_failed | цяло число | Неуспешни връзки, отчетени през последните 15 минути |
dropped | цяло число | Обаждания, отчетени като прекъснати през последните 30 минути |
rolled_back_at | времеви печат |
Свързани
Блокиращият payload за входящо обаждане, на който трябва да отговорите.
Транскрипция и метрики след обаждането.
Абонирайте URL адрес за подмножество от тези събития.
Как се генерират събитията telephony.tool / web.tool.