Каталог подій

Усі типи подій вебхуків, які надсилає ThunderPhone.

Кожне тіло вебхука має поле type, значенням якого є один із типів подій на цій сторінці. Коли ви підписуєтеся на кінцеву точку, масив events має містити потрібні вам типи подій (або бути порожнім, щоб підписатися на все — крім подій для кожного ходу telephony.turn / web.turn, які надсилаються лише кінцевим точкам, де їх явно вказано).

Ці події доставляються у двох стилях:

• Доставки до endpoint завжди є неблокувальними сповіщеннями з повторними спробами: відповідайте будь-яким кодом 2xx; оболонка містить event_id для дедуплікації.
• Блокувальні обміни виконуються лише через застарілий webhook з однією URL-адресою: запит конфігурації telephony.incoming / web.incoming (номери в режимі webhook: 13 с, включно з однією повторною спробою; ключі віджета в режимі webhook: 10 с) і диспетчеризація інструментів у режимі webhook. Ваша відповідь формує перебіг активного дзвінка.

Наведені нижче приклади корисного навантаження показують конверт кінцевої точки в порядку передавання (ключі відсортовано за абеткою: data, event_id, type); застарілі доставки містять ті самі data без event_id.

Події викликів#

telephony.incoming#

Надсилається, коли вхідний виклик надходить на один із ваших номерів телефонів. Доставки до кінцевої точки є сповіщеннями без очікування відповіді та надсилаються для кожного вхідного виклику, незалежно від того, чи номер налаштовано для агента або вебхука. Номери без призначеного агента також отримують блокувальний запит конфігурації на застарілий вебхук — див. telephony.incoming / web.incoming, щоб переглянути повну схему запиту / відповіді.

{
  "data": {
    "call_id": 987654321,
    "from_number": "+14155550199",
    "to_number": "+15551234567"
  },
  "event_id": "3f6b2ad0-1c9e-4a57-9f2b-8f6f0f9d2f11",
  "type": "telephony.incoming"
}

telephony.complete#

Надсилається після завершення вхідного або вихідного телефонного виклику. Неблокувальна. Містить транскрипт, URL запису за наявності та підсумок виставлення рахунків. Див. telephony.complete / web.complete, щоб переглянути схему корисного навантаження.

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>"} у разі помилки.

telephony.turn#

Надсилається, поки телефонний виклик триває, один раз для кожної репліки з мовленням у момент її появи — озвучені відповіді агента та транскрибовані репліки абонента. Дає змогу відстежувати розмову наживо через звичайні вебхуки замість опитування 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"
}

web.incoming#

Еквівалент telephony.incoming для вебканалу, який надсилається, коли починається сеанс вебвіджета або тестовий виклик мікрофона в конструкторі. Доставки до кінцевої точки є сповіщеннями без очікування відповіді для кожного вебсеансу. Публічні ключі в mode="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". Для сеансів віджета в режимі вебхука to_number порожній (номер агента для сеансу призначається після конфігурації); для тестових викликів мікрофона в конструкторі origin_domain і publishable_key_prefix порожні.

web.complete#

Еквівалент telephony.complete для вебканалу, який охоплює виклики вебвіджета (direction: "web") і тестові виклики мікрофона в конструкторі (direction: "test"). Неблокувальна. Така сама структура корисного навантаження, як у telephony.complete, а також origin_domain, де from_number має значення "web".

web.tool#

Еквівалент telephony.tool для вебканалу. data містить origin_domain замість from_number / to_number.

web.turn#

Еквівалент telephony.turn для вебканалу, який охоплює виклики вебвіджета та тестові виклики мікрофона в конструкторі. Така сама структура корисного навантаження, але з origin_domain замість from_number / to_number. Як і telephony.turn, потребує явної підписки — ніколи не доставляється через порожній масив events.

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"
}

Ті самі значення доступні в об’єкті дзвінка як transfer_outcome, transfer_destination, transfer_sip_status, transfer_bridge_kind, transfer_bridge_seconds і transfer_bridge_total_cents. event_id є однаковим для кожної доставки одного дзвінка, тому повторне повідомлення не створює другу подію.

Події SMS#

Події SMS описують повідомлення, надіслані через підключений обліковий запис Twilio або Telnyx організації. Текст повідомлення не вказується, а значення to редагується. Отримуйте повідомлення в межах організації за допомогою GET /v1/sms/{message_id}, коли потрібен його вміст або одержувач.

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",
    "segment_count": 1,
    "source": "agent_tool",
    "status": "accepted",
    "to": "[REDACTED]"
  },
  "event_id": "0ae347b4-1716-45bb-9a0e-b52373586e37",
  "type": "sms.sent"
}

sms.failed#

Надсилається після остаточної відмови оператора, після вичерпання повторних спроб для тимчасових помилок або коли результат остаточно невідомий. error_code — це стабільний код ThunderPhone, а error_message містить дію для клієнта, якщо її можна вказати. status: "unknown" означає, що оператор міг прийняти SMS; звірте це з журналом оператора, оскільки ThunderPhone не надсилатиме його повторно автоматично.

sms.received#

Зарезервовано для підтримки вхідних SMS. У поточному випуску події sms.received не надсилаються. Налаштування webhook для вхідних повідомлень від оператора та перевірка підпису будуть випущені окремо.

Голосові події#

Створення користувацького голосу відбувається асинхронно. Ці неблокувальні події дають змогу реагувати на кінцевий результат замість опитування кінцевої точки відомостей про клон.

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"
}

Події якості#

call.graded#

Надсилається щоразу, коли для виклику завершується запуск оцінювання ШІ. Неблокувальна подія.

{
  "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"
}

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": "<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"
}

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,
      "remaining": 0
    }
  },
  "event_id": "8d8f52ce-6b46-423f-9dde-cea0b91ec135",
  "type": "campaign.completed"
}

Чотири лічильники результатів є взаємовиключними та в сумі дорівнюють contacts_total: completed містить успішні контакти; no_answer містить контакти з остаточним станом невдачі або вичерпаними спробами, для яких останнім результатом була відсутність відповіді; failed містить усі інші контакти з остаточним станом невдачі або вичерпаними спробами; а remaining містить контакти, що очікують, заплановані або для яких зараз здійснюється виклик. Контакт, що очікує повторної спроби, має стан remaining, навіть якщо в його останній спробі не було відповіді. Виклики в процесі виконання узгоджуються перед одноразовим знімком завершення. started_at — це налаштований початок кампанії або час створення кампанії, якщо початок не було налаштовано.

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"
}

issue.escalated#

Надсилається, коли шаблон проблеми надсилається до ThunderPhone для перевірки персоналом: після Повідомити ThunderPhone або коли функція «Виправити за допомогою ШІ» не може підтвердити виправлення на стороні клієнта й автоматично маршрутизує проблему. Цю подію отримують лише кінцеві точки рівня організації.

{
  "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"
}

Це сповіщення, а не пакет доказів. Використовуйте 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"
}

Події сповіщень#

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"
}

Дивіться посібник зі сповіщень, щоб створювати правила, налаштовувати метрики, періоди очікування та канали електронної пошти / Slack.

Події міграції#

migration.call.complete#

Надсилається, коли завершується дзвінок, здійснений через POST /v1/migrations/{id}/calls, незалежно від платформи, через яку його було здійснено. Не блокує виконання. Надходить протягом приблизно 5 хвилин після завершення дзвінка. data містить усі поля з telephony.complete і блок migration. Дзвінок, здійснений ThunderPhone, також надсилає telephony.complete як зазвичай, з тим самим call_id. Дзвінок на іншій платформі, який не завершився протягом 2 годин або для якого міграція раніше завершилася чи втратила ключ, надсилається зі status: "unknown" і без транскрипту.

{
  "data": {
    "agent_id": 42,
    "agent_name": "Front desk",
    "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"
}

Для дзвінка 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"
}

Пов’язані матеріали#