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

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

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

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

Події дзвінків

`telephony.incoming`

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

`telephony.complete`

Надсилається, коли завершується вхідний або вихідний телефонний дзвінок. Неблокувальна подія. Містить повну транскрипцію, URL запису та підсумок білінгу. Схему payload дивіться в 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>"} у разі помилки.

`web.incoming`

Еквівалент telephony.incoming для вебканалу, що надсилається на початку сеансу вебвіджета або тестового дзвінка з мікрофона в конструкторі. Доставки до endpoint є fire-and-forget для кожного вебсеансу. Публічні ключі в 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 порожні.

`web.complete`

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

У застарілому webhook з однією URL-адресою тестові дзвінки з мікрофона в конструкторі історично передаються як telephony.complete — лише дзвінки з direction: "web" використовують там тип web.complete. Система endpoint зіставляє як вебдзвінки, так і тестові дзвінки з web.*. Історичні payload можуть містити застарілі значення direction: widget або mic.

`web.tool`

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

Події якості

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

Поле	Тип	Опис
`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`)
`grade.graded_at`, `grade.created_at`	timestamp

Виклик можна оцінювати кілька разів — за швидкою евристичною оцінкою часто слідує повна оцінка моделлю, щойно стає доступним запис, а також можливе повторне оцінювання вручну. Кожен завершений запуск надсилає власну подію call.graded; вважайте найновіший graded_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_report.severity`	string	`critical`, `warning` або `info`
`issue_report.status`	string	`open` або `resolved`
`issue_report.source`	string	`user` (надіслано з панелі керування) або `system` (створено оцінюванням)

Повторне оцінювання виклику перегенеровує його звіти про проблеми, згенеровані системою, що повторно надсилає issue.reported для відтворених звітів. Виконуйте дедуплікацію за call_id + title, якщо потрібне лише одне сповіщення для кожної основної проблеми.

Події тестових викликів

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

Поле	Тип	Опис
`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, рядок	Правило, яке спрацювало
`metric`	рядок	`success_rate`, `failure_rate`, `avg_score`, `call_volume` або `suite_regression`
`comparator`	рядок	`lt`, `lte`, `gt` або `gte`
`metric_value`	число	Значення метрики за вікно на момент спрацювання правила
`threshold`	число	Налаштований поріг
`window_hours`	ціле число	Ковзне вікно оцінювання
`fired_at`	позначка часу

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

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

telephony.incoming / web.incoming

Блокувальне корисне навантаження вхідного виклику, на яке потрібно відповісти.

telephony.complete / web.complete

Транскрипт і метрики після виклику.

Кінцеві точки вебхуків

Підпишіть URL на підмножину цих подій.

Інструменти функцій

Як генеруються події telephony.tool / web.tool.

Webhooks

Function Tools

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

Події дзвінків

`telephony.incoming`

`telephony.complete`

`telephony.tool`

`web.incoming`

`web.complete`

`web.tool`

Події якості

`call.graded`

`issue.reported`

Події тестових викликів

`test-call.completed`

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

`alert.triggered`

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

telephony.incoming / web.incoming

telephony.complete / web.complete

Кінцеві точки вебхуків

Інструменти функцій

​Події дзвінків

​telephony.incoming

​telephony.complete

​telephony.tool

​web.incoming

​web.complete

​web.tool

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

​call.graded

​issue.reported

​Події тестових викликів

​test-call.completed

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

​alert.triggered

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

telephony.incoming / web.incoming

telephony.complete / web.complete

Кінцеві точки вебхуків

Інструменти функцій

Події дзвінків

`telephony.incoming`

`telephony.complete`

`telephony.tool`

`web.incoming`

`web.complete`

`web.tool`

Події якості

`call.graded`

`issue.reported`

Події тестових викликів

`test-call.completed`

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

`alert.triggered`

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