ВойтиНачать бесплатный пробный период
Meta Tech Provider

Статусы вебхуков WhatsApp: отправлено, доставлено, прочитано, ошибка

Вебхуки статусов сообщают, что произошло с сообщением, которое бизнес отправил через WhatsApp Cloud API. Они приходят в поле messages, но вместо массива messages содержат массив statuses: sent (одна галочка), delivered (две галочки), read (две синие галочки), played для голосовых сообщений и failed с массивом errors. Сопоставьте statuses[].id с wamid, который вернул ваш запрос на отправку.

easyCoexistence подключает номер приложения WhatsApp Business, который вы уже используете, к Cloud API Meta через Coexistence.

5

Значения статусов, которые отправляет Meta: sent, delivered, read, played (первое воспроизведение голосовых сообщений) и failed.

3

Отдельные вебхуки статусов, которые может породить одно исходящее сообщение: sent, delivered и read.

v24.0

Начиная с этой версии Graph API объект conversation опускается, кроме сообщений в окне бесплатной точки входа.

0

API для получения прошлых данных вебхуков нет; Meta просит сохранять полезную нагрузку по мере поступления.

messages

Заголовок X-EC-Event у переданного статуса: статусы передаются внутри событий messages, в value.statuses.

Куда приходят вебхуки статусов WhatsApp?

В то же поле messages, которое несёт сообщения клиентов, в том же объекте, с той же оболочкой entry и changes. Отличие внутри value: входящее сообщение содержит массив messages, статус содержит массив statuses. Обработчик, который читает только value.messages, без ошибки отбрасывает все статусы. metadata.phone_number_id указывает, с какого вашего номера отправлено сообщение. Вместе с ним приходит массив contacts с именем профиля клиента, wa_id и BSUID, кроме статусов failed и статуса sent для сообщений в группе. Ниже пример Meta: шаблон маркетингового сообщения, который покинул серверы Meta:

Meta's example: a marketing message with status sent
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "15550783881",
              "phone_number_id": "106540352242922"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Pablo M."
                },
                "wa_id": "16505551234",
                "user_id": "US.13491208655302741918"
              }
            ],
            "statuses": [
              {
                "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUFERjg0NDEzNDdFODU3MUMxMAA=",
                "status": "sent",
                "timestamp": "1750030073",
                "recipient_id": "16505551234",
                "recipient_user_id": "US.13491208655302741918",
                "conversation": {
                  "id": "72b14d6bd5407799e66f64d1b338e567",
                  "expiration_timestamp": "1750116480",
                  "origin": {
                    "type": "marketing"
                  }
                },
                "pricing": {
                  "billable": true,
                  "pricing_model": "PMP",
                  "type": "regular",
                  "category": "marketing"
                }
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

Что означает каждое значение статуса?

Каждое значение соответствует отметке, которую клиент видит в WhatsApp. Статус read засчитывается только после доставки. Но если клиент получает сообщение, когда чат уже открыт, Meta отправляет read без предварительного вебхука delivered, как внутреннюю оптимизацию. Поэтому трекер должен принимать read, даже если delivered не пришёл, и должен ранжировать статусы, а не ждать их по одному в фиксированной последовательности.

sentLeft Meta's servers. One gray check in WhatsApp.
deliveredReached the customer's device. Two gray checks.
readDisplayed in an open chat on the device. Two blue checks.
playedFirst play of voice messages. Blue microphone.
failedCould not be sent or delivered. Red error triangle, plus an errors array.

Какие поля есть в объекте статуса?

Полей меньше, чем у сообщения, и некоторые из них условные. Справочник Meta указывает, когда каждое из них присутствует:

  • id: wamid отправленного вами сообщения, ключ для сопоставления.
  • status и timestamp: значение и время Unix, когда сработал вебхук, в виде строки.
  • recipient_id: номер телефона или идентификатор группы; отсутствует, если вы отправили на BSUID и номер недоступен.
  • recipient_user_id: BSUID клиента; отсутствует в статусе failed, если вы отправляли на номер телефона.
  • recipient_type и recipient_participant_id: только для сообщений, отправленных в группу.
  • biz_opaque_callback_data: только если вы задали его в запросе на отправку.
  • pricing: только в sent и в одном из статусов delivered или read. errors: только в failed.

Как сопоставить статус с отправленным сообщением?

По wamid. Запрос на отправку возвращает messages[0].id, и каждый статус этого сообщения несёт то же значение в statuses[].id. Сохраните его рядом со своей записью при отправке, затем обновляйте запись при поступлении статусов, сохраняя наивысший достигнутый статус, чтобы запоздавший delivered не перезаписал read. Статус с неизвестным вам wamid отправлен чем-то другим с этого номера, например автоматизацией, и его можно игнорировать или записывать в журнал.

statuses.mjs: apply status webhooks to your sends (Node.js)
// statuses.mjs: apply Meta status webhooks to the messages your system sent
const RANK = { sent: 1, delivered: 2, read: 3, played: 4 };

// value: change.value of a "messages" webhook; sends: Map of wamid -> your record
export function applyStatuses(value, sends) {
  for (const s of value.statuses ?? []) {
    const rec = sends.get(s.id); // the wamid your send request returned
    if (!rec) continue; // sent by something else, such as an automation
    if (s.status === "failed") {
      rec.status = "failed";
      rec.error = s.errors?.[0]?.code; // for example 131049, 131050 or 131026
    } else if ((RANK[s.status] ?? 0) > (RANK[rec.status] ?? 0)) {
      rec.status = s.status; // read arriving before delivered is fine; never step back
    }
    rec.updatedAt = Math.max(rec.updatedAt ?? 0, Number(s.timestamp));
  }
}

Что меняется на номере Coexistence?

Статусы описывают то, что отправлено через API: ответы ваших автоматизаций, сообщения, которые отправил ваш ИИ через MCP-коннектор, и всё, что отправил ваш код. То, что владелец набирает в приложении WhatsApp Business, доходит до программ иначе, как smb_message_echoes, которое Meta описывает как зеркало сообщений, отправленных из приложения. Сообщения, перенесённые при однократном импорте истории, несут собственный статус внутри вебхука истории, со значениями вроде delivered, read, played, pending и error.

Статусы идут туда же, куда идёт поле messages номера. При прямом назначении Meta отправляет их прямо на ваш эндпоинт, так как messages является полем, которое Meta позволяет переопределить для назначения. Если автоматизации включены и задан Forward URL, статусы попадают на этот URL как события messages.

Как ваш ИИ или автоматизация узнают, что сообщение доставлено?

Через ваше назначение, а не через отправку. Когда ассистент вызывает send_template или send_message, результат инструмента содержит wamid и сообщает, что Meta приняла сообщение; доставка подтверждается позже, на устройстве клиента, и приходит как статус. easyCoexistence не хранит историю статусов для запроса, и ни один инструмент MCP не читает статусы, поэтому агенту, которому нужно подтверждение доставки, стоит отправлять через вашу систему или читать статусы, которые получает ваш Forward URL.

То же относится к автоматизациям: запуск на вкладке Runs показывает шаг ответа выполненным, как только Meta приняла сообщение, а сбой, сообщённый позже, появляется только как статус failed на вашем назначении.

Распространённые ошибки

  • Поиск отдельного поля statuses. Статусы приходят в messages, поэтому обработчик, который читает только value.messages, теряет их без всякой ошибки.
  • Требование delivered перед read. Meta пропускает вебхук delivered, когда сообщение прочитано в момент поступления.
  • Принятие ответа на отправку за доставку. wamid означает, что Meta приняла запрос; сбой может прийти через несколько минут как статус failed.
  • Идентификация клиентов только по recipient_id. Он отсутствует, если вы отправляли на BSUID и номер телефона недоступен; BSUID находится в recipient_user_id.
Настройка с EasyCoexistence

Статусы того, что отправляют ваши автоматизации, ваш ИИ или ваш код, поступают на ваш сервер: напрямую от Meta в прямом режиме или пересылаются на ваш Forward URL, подписанные X-EC-Signature, когда автоматизации включены, и по умолчанию не хранятся. От US$ 9 до US$ 0,75 за номер в месяц, с понижением по мере добавления номеров, первые 3 дня бесплатно.

Часто задаваемые вопросы

Включают ли вебхуки статусов текст сообщения?

Нет. Статус содержит wamid, сам статус, получателя, временные метки и, где применимо, стоимость и ошибки. Храните собственную копию отправленного, с ключом wamid, если нужно показывать её рядом со статусом.

Могу ли я позже получить прошлые статусы от Meta?

Нет. Руководство Meta по вебхукам говорит, что API для получения исторических данных вебхуков нет, поэтому статус, который ваш эндпоинт не зафиксировал, пропадает, когда Meta прекращает повторные попытки, то есть через до 7 дней.

Для чего нужен biz_opaque_callback_data?

Это строка, которую вы задаёте при отправке, например номер вашего заказа или тикета. Meta возвращает её в statuses этого сообщения, так что вы можете сопоставить статус со своей записью, не ища сначала wamid.

Нужно ли отвечать на вебхуки статусов кодом 200?

Да, как и на любой POST-вебхук. Meta считает любой другой ответ неудачной доставкой и повторяет её, и это один из способов, которым один и тот же статус приходит к вам дважды.

Читайте дальше

Почему сообщение WhatsApp не доставлено: чтение статуса failed и его ошибокСтатус failed значит, что Meta не смогла отправить или доставить сообщение. Разберите массив errors и коды 131047, 131049, 131050 и что делать.Объект ценообразования в вебхуках WhatsApp: тип, категория и billable (2026)Что объект ценообразования в вебхуках статусов WhatsApp сообщает с октября 2026 года: billable, pricing_model, type, category, subtype и как считать списания.Повторы вебхуков WhatsApp, дубликаты и порядок: как с ними работатьMeta повторяет доставку вебхуков WhatsApp до 7 дней, поэтому дубликаты обычны, а порядок не гарантирован. Ключи дедупликации и безопасный обработчик.Вебхуки звонков WhatsApp: события Calling API и звонки на номере CoexistenceПоле вебхука calls передаёт события WhatsApp Calling API: connect, terminate, статусы звонков, записи. Примеры запросов и что относится к номерам Coexistence.Как сообщения WhatsApp доходят до вашего сервера: напрямую или через управляемый режим, и проверка подписиНапрямую: Meta шлёт вебхуки на ваш сервер. Через сервис: автоматизации отвечают, подписанная копия уходит на Forward URL.Имена пользователей WhatsApp и BSUID: что меняется в вебхуках Cloud APIКак имена пользователей WhatsApp меняют вебхуки Cloud API: BSUID в user_id, когда пропадают wa_id и from, ответ по recipient и изменения Coexistence.

Готовы начать?

Настройте WhatsApp Coexistence за несколько минут, а не месяцев. Приложение продолжит работать на телефоне.

Начать бесплатный пробный период

Проверено по состоянию на