WhatsApp API: отслеживание статуса доставки сообщения

Обновлено: 11 октября 2026 · 6 мин чтения

Шаги

1. 1

   Статусы

   • sent: Meta приняла сообщение, оно отправлено на телефон
   • delivered: дошло до телефона клиента
   • read: клиент открыл и прочитал
   • failed: отправить не удалось, причина в поле external_error

   sent, пришедший сразу после отправки, ещё не значит «доставлено».

2. 2

   Прочитайте статус запросом

   curl -s "https://api.clomni.ai/v1/accounts/{account_id}/whatsapp/messages/{message_id}" \
     -H "Authorization: Bearer <API_ACARI>"

   message_id это id из ответа на отправку. Структура ответа такая же, как у ответа на отправку сообщения. Этот запрос можно отправлять с ключом любого пользователя аккаунта. Периодически опрашивать (polling) можно, но вебхук удобнее.

3. 3

   Настройте вебхук

   В панели на странице «Settings › Workspace settings › Integrations» в карточке «Webhook» нажмите «Configure», затем «Add new webhook». Впишите адрес своего сервера, в списке «Events» выберите «Message updated» (message_updated) и нажмите «Create webhook». Подробные шаги есть в статье «Настроить вебхук (webhook): отправлять события в свою систему».

4. 4

   Что приходит в вебхуке

   {
     "event": "message_updated",
     "id": 918234,
     "status": "delivered",
     "message_type": "outgoing",
     "whatsapp_message_id": "wamid.HBgMOTk0NTAxMjM0NTY3...",
     "conversation": { "id": 1042 },
     "inbox": { "id": 159, "name": "WhatsApp компании" },
     "sender": { "phone_number": "+994 50 123 45 67" }
   }

   • id это id сообщения из ответа на отправку, храните его у себя в базе.
   • status: sent, delivered, read, failed. У неотправленного сообщения причина приходит в поле content_attributes.external_error.
   • Clomni отправляет этот запрос один раз и не повторяет его. Ваш сервер должен вернуть 2xx в течение 5 секунд: поставьте запрос в свою очередь и сразу ответьте.
5. 5

   Отчёт на Ваш адрес по каждому сообщению (status_callback)

   Добавьте в отправку блок status_callback, и Clomni отправит статус этого сообщения прямо на Ваш адрес. В панели ничего настраивать не нужно.

   {
     "channel_id": 159,
     "phone_number": "+994501234567",
     "template": { "name": "otp_code", "language": "az", "parameters": { "1": "4821" } },
     "source_reference": "otp-10422-1791700000",
     "status_callback": {
       "url": "https://example.com/whatsapp/status",
       "after_seconds": 8,
       "on_change": true,
       "secret": "<GIZLI_ACAR>"
     }
   }

   • url (обязательно): только https://. Адреса внутренней сети не принимаются, редиректы не выполняются.
   • after_seconds (1-3600): один отчёт через N секунд после отправки со статусом сообщения на этот момент.
   • on_change (true/false): отдельный отчёт при каждой смене статуса (delivered, read, failed). Если Meta не приняла отправку (например, неверный номер), failed тоже приходит так.
   • Нужен хотя бы один из параметров after_seconds и on_change.
   • secret (необязательно): отчёт подписывается этим ключом. Мы храним его в зашифрованном виде и не возвращаем в ответах.

   Запрос, который получит Ваш сервер:

   {
     "event": "message_status",
     "trigger": "scheduled",
     "message_id": 918234,
     "source_reference": "otp-10422-1791700000",
     "phone_number": "+994501234567",
     "status": "delivered",
     "delivered": true,
     "read": false,
     "sent_at": "2026-10-11T08:00:01Z",
     "delivered_at": "2026-10-11T08:00:04Z",
     "read_at": null,
     "error": null,
     "after_seconds": 8,
     "checked_at": "2026-10-11T08:00:09Z"
   }

   • trigger: scheduled (отчёт after_seconds) или status_change (отчёт on_change).
   • delivered: true это две серые галочки: сообщение дошло до телефона, значит у телефона был интернет.
   • Если через N секунд статус всё ещё sent, телефон офлайн, без интернета или WhatsApp давно не открывали. Доставку сообщит отчёт on_change.
   • read приходит, только если у клиента включены отчёты о прочтении. Его отсутствие не значит, что сообщение не прочитано.
   • Meta обычно присылает статус за 1-5 секунд, поэтому для after_seconds подходит 8-15 секунд.

   Подпись и повторы такие же, как у вебхуков звонков: X-ChatX-Delivery, X-ChatX-Timestamp, X-ChatX-Signature (sha256= + HMAC-SHA256(secret, "<timestamp>.<тело запроса>")). Сервер должен ответить 2xx в течение 5 секунд. При отсутствии соединения, таймауте, 429 или 5xx мы повторяем через 10 секунд и через 1 минуту. X-ChatX-Delivery одинаков во всех попытках, по нему отбрасывайте повторы.

   В массовой рассылке работает тот же блок: отчёт приходит по каждому номеру отдельно, задержка считается от отправки на этот номер. Ответ GET /messages/{message_id} тоже содержит delivered_at, read_at и status_callback (без секрета).

6. 6

   Получайте и ответ клиента

   Если выбрать также событие «Message created» (message_created), ответ клиента и нажатие кнопки шаблона тоже придут в Вашу систему. Именно в этот момент открывается 24-часовое окно: с него начинайте отправлять следующие уведомления бесплатным текстом.