Каталог событий

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

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

Примеры полезной нагрузки ниже показывают оболочку конечной точки в порядке передачи по сети (ключи отсортированы по алфавиту: 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>"} при ошибке.

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

В устаревшем вебхуке с единым URL тестовые звонки микрофона в конструкторе исторически передаются как telephony.complete — только звонки с direction: "web" используют там тип web.complete. Система эндпоинтов сопоставляет как веб-звонки, так и тестовые звонки с web.*. Исторические полезные нагрузки могут содержать устаревшие значения direction: widget или mic.

`web.tool`

Эквивалент telephony.tool для веб-канала. В data передаётся origin_domain вместо from_number / to_number.

События голосов

Создание пользовательского голоса выполняется асинхронно. Эти неблокирующие события позволяют реагировать на конечный результат вместо опроса эндпоинта сведений о клоне.

`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`	string	Публичный идентификатор пользовательского голоса
`voice.name`	string	Значение голоса агента в формате `custom:<public_id>`
`voice.display_name`	string	Название голоса для организации
`voice.language`	string	Код единственного языка клона
`voice.gender`	string	`male`, `female` или пустая строка
`voice.status`	string	`ready` для `voice.ready`; `failed` для `voice.failed`
`voice.failure_reason`	string	Пусто при успехе; сведения об ошибке обработки при сбое
`voice.created_at`, `voice.updated_at`	timestamp	Метки времени ISO 8601
`reason`	string	Сведения об ошибке; присутствует только в `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"
}

Поле	Тип	Описание
`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`

События голосов

`voice.ready`

`voice.failed`

События качества

`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

​События голосов

​voice.ready

​voice.failed

​События качества

​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`

События голосов

`voice.ready`

`voice.failed`

События качества

`call.graded`

`issue.reported`

События тестовых звонков

`test-call.completed`

События оповещений

`alert.triggered`

Связанные материалы