ThunderPhone v3 вече е тук.Започнете самостоятелно — от 2 цента/мин.Прочетете съобщението

Webhooks

Каталог на събитията

Всички типове 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_idinteger | nullАгентът, обработил обаждането, когато е бил назначен такъв
agent_namestring | 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_idinteger | nullАгентът, обработил обаждането, когато е бил назначен такъв
agent_namestring | 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_idinteger | nullАгентът, обработил обаждането, когато е бил назначен такъв
agent_namestring | nullАгентът, обработил обаждането, когато е бил назначен такъв
positionintegerИндексът на хода в хронологията на обаждането — стабилен идентификатор за подреждане
rolestringassistant (реч на агента) или user (реч на обаждащия се)
textstringТекстът от транскрипцията на хода, наличен към момента на изпращане
entry_typestringТипът на основния запис в хронологията: completion (агент) или user_turn / span (обаждащ се)
start_ms, end_msintegerАудио отмествания в 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_idinteger | nullАгентът, обработил обаждането, когато е бил назначен такъв
agent_namestring | nullАгентът, обработил обаждането, когато е бил назначен такъв

web.complete

Еквивалентът на telephony.complete за уеб канала, обхващащ обаждания от уеб джаджа (direction: "web") и тестови обаждания с микрофон в конструктора (direction: "test"). Неблокиращо. Същата структура на payload-а като telephony.complete, плюс origin_domain, като from_number е зададено на "web".

ПолеТипОписание
agent_idinteger | nullАгентът, обработил обаждането, когато е бил назначен такъв
agent_namestring | nullАгентът, обработил обаждането, когато е бил назначен такъв

web.tool

Еквивалентът на telephony.tool за уеб канала. data съдържа origin_domain вместо from_number / to_number.

ПолеТипОписание
agent_idinteger | nullАгентът, обработил обаждането, когато е бил назначен такъв
agent_namestring | nullАгентът, обработил обаждането, когато е бил назначен такъв

web.turn

Еквивалентът на telephony.turn за уеб канала, обхващащ обаждания от уеб джаджа и тестови обаждания с микрофон в конструктора. Същата структура на payload-а, с origin_domain вместо from_number / to_number. Подобно на telephony.turn, той изисква изричен абонамент — никога не се доставя чрез празен масив events.

ПолеТипОписание
agent_idinteger | nullАгентът, обработил обаждането, когато е бил назначен такъв
agent_namestring | 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_idintegerОбаждането, което е прехвърлено
agent_idinteger | nullАгентът, обработил обаждането, когато е бил назначен такъв
agent_namestring | nullАгентът, обработил обаждането, когато е бил назначен такъв
transfer_outcomestringrefer_accepted: операторът пое обаждането. bridged: ThunderPhone запази връзката между обаждащия се и целевия номер, защото операторът е отказал студено прехвърляне или защото агентът при топло прехвърляне се е оттеглил. bridge_unanswered: операторът отказа студено прехвърляне и целевият номер не отговори на собственото обаждане на ThunderPhone. failed: прехвърлянето не е осъществено и обаждането е приключило
destinationstring | nullНомерът, към който е прехвърлено обаждането
sip_statusinteger | nullSIP статусът на оператора, когато е отказал студеното прехвърляне: 403 (например Twilio trunk без прехвърляне на обаждания), 405 или 501. null, когато операторът не го е отказал
bridge_kindstring | nullСамо при bridged: cold_fallback (отказано студено прехвърляне, което ThunderPhone е свързал) или warm (двамата участници при топло прехвърляне, след като агентът се е оттеглил)
bridge_secondsinteger | nullСамо при bridged: времето на свързването чрез мост, таксувано от ThunderPhone, в секунди
bridge_total_centsinteger | 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_idintegerОбаждането
agent_idinteger | nullАгентът, обработил обаждането, когато е назначен такъв
agent_namestring | nullАгентът, обработил обаждането, когато е назначен такъв
directionstringПосоката на обаждането, както в обекта за обаждане
statusstringЕтапът, достигнат от обаждането; вижте таблицата по-долу
occurred_attimestampКога се е случило
hold_secondsinteger | 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.

ПолеТипОписание
idstringИдентификаторът на планираното изпращане
typestringsms или call
statusstringskipped или failed
reasonstringПричината, както е описано по-горе; същата стойност като status_reason на изпращането
detailstringРазбираемо обяснение
sourcestringКакво е създало изпращането: api
external_idstring | nullВашият ключ за изпращането или null
from_numberstringНомер за изпращане
tostringВинаги "[REDACTED]"
agent_idinteger | nullОбаждания: агентът; текстови съобщения: null
send_at, expires_at, created_attimestampISO 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_idinteger | nullАгентът, обработил обаждането, когато е бил назначен такъв
agent_namestring | nullАгентът, обработил обаждането, когато е бил назначен такъв
grade.idintegerИдентификатор на оценката
grade.scoreinteger | null0–100
grade.call_outcomestringsuccess, failure, unknown или no_conversation
grade.summarystringРезюме в един абзац
grade.detected_issuesarrayНизове с проблеми, открити от оценителя
grade.statusstringВинаги completed — изпращат се само завършени изпълнения
grade.grader_modelstringКой оценител е генерирал резултата: heuristic-v1 (или друг базиран на правила оценител на ThunderPhone) за бърза предварителна оценка, thunderphone-grader за пълната оценка. Това е етикет на ThunderPhone, а не име на AI модел
grade.graded_at, grade.created_attimestamp
reportobject | 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_idinteger | nullАгентът, обработил разговора, когато е назначен такъв
agent_namestring | nullАгентът, обработил разговора, когато е назначен такъв
issue_report.severitystringcritical, warning или info
issue_report.statusstringopen или resolved
issue_report.sourcestringuser (подаден от таблото за управление) или 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"
}
ПолеТипОписание
automaticbooleantrue за автоматична ескалация; false за ръчна ескалация
cluster_idUUIDЕскалиран модел на проблем
escalation_idUUIDЗапис за ескалация
statusstringopen при изпращане на събитието

Това е известие, а не пакетът с доказателства. Използвайте 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_idinteger | nullАгентът, който е обработил обаждането, когато е назначен такъв
agent_namestring | nullАгентът, който е обработил обаждането, когато е назначен такъв
test_call_run.target_typestringagent или phone_number
test_call_run.target_idintegerИдентификаторът на агента или телефонния номер, към който е насочено изпълнението, съответстващ на target_type
test_call_run.statusstringcompleted или failed
test_call_run.call_idinteger | nullnull, когато изпълнението е неуспешно преди осъществяване на обаждане
test_call_run.error_messagestringПразно при успех

Събития за предупреждения

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_nameUUID, stringПравилото, което се е задействало
metricstringsuccess_rate, failure_rate, avg_score, call_volume или suite_regression
comparatorstringlt, lte, gt или gte
metric_valuenumberСтойността на метриката за прозореца, когато правилото се е задействало
thresholdnumberКонфигурираният праг
window_hoursintegerПлъзгащ се прозорец за оценяване
fired_attimestamp

Вижте ръководството за предупреждения за създаване на правила, метрики, периоди на изчакване и каналите за имейл / 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.idUUIDМиграцията
migration.routing_idUUIDМаршрутизираният разговор, както е върнат при осъществяването му
migration.armstringours (ThunderPhone го е осъществил) или vendor (другата платформа го е осъществила)
migration.vendorstringretell, vapi, elevenlabs или bland
migration.vendor_call_idstring | nullИдентификаторът на разговора в другата платформа; null за ours
migration.metadataobjectmetadata, които сте изпратили при осъществяването на разговора
migration.vendor_cost_usdstring | nullЦената на разговора, отчетена от другата платформа, ако е предоставила такава
call_idinteger | nullИдентификаторът на разговора в ThunderPhone; null за vendor
statusstringЗа 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_idUUIDМиграцията
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времеви печат

Свързани