Webhooks

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

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

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

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

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

Наведені нижче приклади корисних навантажень показують конверт кінцевої точки в порядку передавання (ключі відсортовано за абеткою: 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#

Надсилається після того, як телефонний виклик викликає інструмент-функцію. Неблокувальне сповіщення для аудиту — інструмент уже виконано на момент доставки цієї події; воно охоплює ваші власні інструменти-функції (не вбудовані інструменти, інструменти бази знань, підключень застосунків або MCP).

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

Події голосу#

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

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…"
    }
  },
  "event_id": "7c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
  "type": "call.graded"
}

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

Події тестових дзвінків#

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.

Пов’язане#