Примеры Webhook завершения и фиксации звонков WhatsApp

Полный каталог, сформированный на основе схемы, см. в всех примерах.

Что это такое

Обработка событий завершения звонков, записи и транскрипции в WhatsApp.

Перед началом работы

Создайте публичный эндпоинт HTTPS в вашем приложении.
Настройте эндпоинт Webhook в YCloud для необходимых типов событий.
Надежно сохраните секретный ключ подписи эндпоинта.
Обеспечьте идемпотентность обработки событий.

Как это работает

YCloud отправляет запрос HTTP POST при возникновении события. Проверьте подпись, надежно сохраните событие, верните ответ 2xx и выполняйте длительные операции асинхронно.

Запрос

В приведенных ниже сценариях показаны запросы, отправляемые на ваш Webhook URL. Используйте id события как идентификатор доставки, а type — для маршрутизации полезной нагрузки.

Ответ

Возвращайте статус 2xx после принятия события.

HTTP/1.1 200 OK

Сведения о настройке эндпоинта, проверке подписи и механизме повторных попыток см. в разделе Настройка Webhook.

Как бизнес, так и пользователь WhatsApp могут завершить звонок в любой момент. Когда бизнес или пользователь WhatsApp завершает звонок, вы получаете Webhook Call Terminate:

Звонок завершен

Запрос

{
  "id": "evt_6757b889a5a42d369ef48481",
  "type": "whatsapp.call.terminate",
  "apiVersion": "v2",
  "createTime": "2024-12-10T03:42:01.822Z",
  "callingTerminate": {
    "id": "6757b889960b25543b9ecc67",
    "wacid": "wacid.HBgNNjI4MTM2MTkwNTE",
    "phoneId": "461269257068832",
    "from": "+6281361905133",
    "fromUserId": "ID.13491208655302741918",
    "fromParentUserId": "ID.11815799212886844830",
    "to": "+6283138205150",
    "direction": "USER_INITIATED",
    "startTime": 1733734738000,
    "endTime": 1733734771000,
    "duration": 33,
    "status": "COMPLETED"
  }
}

Ответ

Подтвердите доставку после надежного сохранения события.

HTTP/1.1 200 OK

Пояснение

Маршрутизируйте событие по type, дедуплицируйте его по id и переносите медленные или подверженные сбоям задачи в асинхронный обработчик.

Сбой звонка

Запрос

{
  "id": "evt_675907f431c55113a751d0e7",
  "type": "whatsapp.call.terminate",
  "apiVersion": "v2",
  "createTime": "2024-12-11T03:33:08.679Z",
  "callingTerminate": {
    "id": "675907a13ae4a901f05fee95",
    "wacid": "wacid.HBgNODYxNTE1NzEzNzYyM",
    "phoneId": "461269257068832",
    "from": "+6281361905133",
    "fromUserId": "ID.13491208655302741918",
    "fromParentUserId": "ID.11815799212886844830",
    "to": "+6283138205150",
    "direction": "USER_INITIATED",
    "startTime": 1733826484000,
    "endTime": 1733826637000,
    "duration": 30,
    "status": "FAILED",
    "errorCode": "131000"
  }
}

Ответ

Подтвердите доставку после надежного сохранения события.

HTTP/1.1 200 OK

Пояснение

Запись звонка доступна

Для звонка, инициированного через API с включенной записью, whatsapp.call.recording.updated сообщает о доступности записи или о неустранимой ошибке обработки.

Запрос

{
  "id": "evt_call_recording_01JZ8K4V7H3P6Q9R2T5W8X1Y4Z",
  "type": "whatsapp.call.recording.updated",
  "apiVersion": "v2",
  "createTime": "2026-08-04T08:00:00.000Z",
  "callingRecording": {
    "wacid": "wacid.HBgNNjI4MTM2MTkwNTEzMxUCABE",
    "phoneId": "461269257068832",
    "mediaAssetId": "66b1f0c2e4b05c2d8f1a3b47",
    "status": "AVAILABLE"
  }
}

Ответ

Подтвердите доставку после надежного сохранения события.

HTTP/1.1 200 OK

Пояснение

Используйте callingRecording.wacid для идентификации звонка и phoneId для идентификации номера телефона компании. Скачивайте mediaAssetId только тогда, когда status имеет значение AVAILABLE. Обработка записи отделена от результата завершения звонка. В случае FAILED проверьте error.code и error.retryable. См. раздел записи и транскрипции.

Сбой транскрипции звонка

Для звонка, инициированного через API с включенной транскрипцией, whatsapp.call.transcription.updated сообщает о доступности транскрипции или о неустранимой ошибке обработки.

Запрос

{
  "id": "evt_call_transcription_01JZ8K5A9C4D7E0F3G6H9J2K5M",
  "type": "whatsapp.call.transcription.updated",
  "apiVersion": "v2",
  "createTime": "2026-08-04T08:01:00.000Z",
  "callingTranscription": {
    "wacid": "wacid.HBgNNjI4MTM2MTkwNTEzMxUCABE",
    "phoneId": "461269257068832",
    "mediaAssetId": "66b1f0d9e4b05c2d8f1a3b48",
    "status": "FAILED",
    "error": {
      "code": "CALLING_TRANSCRIPTION_PROCESSING_FAILED",
      "retryable": false
    }
  }
}

Ответ

Подтвердите доставку после надежного сохранения события.

HTTP/1.1 200 OK

Пояснение

Считывайте callingTranscription, а не callingRecording. В этом примере status имеет значение FAILED, а error.retryable равно false. Не пытайтесь скачать ресурс с ошибкой. При результате AVAILABLE для скачивания используется mediaAssetId; результат транскрипции не зависит от результата записи и статуса завершения звонка.

Начало работы

Руководства

Конечные точки

Webhooks

Примеры Webhook завершения и фиксации звонков WhatsApp

Что это такое

Перед началом работы

Как это работает

Запрос

Ответ

Звонок завершен

Запрос

Ответ

Пояснение

Сбой звонка

Запрос

Ответ

Пояснение

Запись звонка доступна

Запрос

Ответ

Пояснение

Сбой транскрипции звонка

Запрос

Ответ

Пояснение

​Что это такое

​Перед началом работы

​Как это работает

​Запрос

​Ответ

​Звонок завершен

​Запрос

​Ответ

​Пояснение

​Сбой звонка

​Запрос

​Ответ

​Пояснение

​Запись звонка доступна

​Запрос

​Ответ

​Пояснение

​Сбой транскрипции звонка

​Запрос

​Ответ

​Пояснение

Что это такое

Перед началом работы

Как это работает

Запрос

Ответ

Звонок завершен

Запрос

Ответ

Пояснение

Сбой звонка

Запрос

Ответ

Пояснение

Запись звонка доступна

Запрос

Ответ

Пояснение

Сбой транскрипции звонка

Запрос

Ответ

Пояснение