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

Поля вебхука WhatsApp и их маршрутизация

Аккаунт WhatsApp Business отправляет события как именованные поля. Два поля содержат сообщения и идут на ваш эндпоинт. Шесть передают состояние аккаунта и используются для мониторинга. Понимание разницы определяет архитектуру.

  • Два поля сообщений, шесть служебных
  • Маршрутизация задаётся для каждого аккаунта
  • Именованные поля, а не общее тело запроса
Начать бесплатный пробный период

В течение 7 дней ничего не списывается. Отмена в любое время.

Без хранения сообщенийBusiness App + Cloud APIMCP для Claude и ChatGPTПодключение за 2 минуты
2

Поля пути сообщений: messages и smb_message_echoes.

6

Служебные поля остаются для мониторинга.

1

Переопределение задаётся для каждого WhatsApp Business Account и определяет их разделение.

Что содержит каждое поле?

messages содержит всё, что клиент отправляет на номер: текст, ссылки на медиафайлы, ответы и реакции. smb_message_echoes содержит сообщения, которые ваша команда отправляет из приложения WhatsApp Business. Это поле существует только у номера Coexistence и позволяет программному обеспечению видеть ответы сотрудника.

account_update передаёт состояние подключения: PARTNER_REMOVED, когда приложение удалено из аккаунта, ACCOUNT_OFFBOARDED, ACCOUNT_RECONNECTED, а также события ограничений и нарушений. phone_number_quality_update передаёт изменения рейтинга качества и пропускной способности. account_alerts содержит оповещения Meta для аккаунта, а account_review_update передаёт результат проверки.

business_capability_update содержит изменения лимита сообщений и возможностей, а phone_number_name_update передаёт одобрения и отклонения отображаемого имени.

Почему это разделение важно для архитектуры?

Потому что оно определяет, попадёт ли содержимое переписки к провайдеру.

Переопределение отправляет два поля сообщений напрямую с Meta на ваш эндпоинт. Шесть служебных полей продолжают поступать провайдеру, поэтому возможны панель управления и оповещения без хранения сообщений.

Поэтому утверждение об отсутствии хранения сообщений может быть свойством архитектуры, а не только политикой. Если поля сообщений доставляются в другое место, в коде нет пути для их сохранения. Для аккаунта без переопределения используется callback по умолчанию: обработчик отбрасывает эти события и не сохраняет их.

Какие поля должен обрабатывать ваш обработчик?

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

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

Также стоит явно обрабатывать smb_message_echoes, а не считать его шумом. Без него программа не узнает, что сотрудник уже ответил, и клиент может получить два ответа на один вопрос.

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

  • Предполагать общее тело запроса. Каждое событие содержит имя поля, и обработчик должен проверять его.
  • Игнорировать smb_message_echoes. Без него программа отвечает поверх уже отправленного сотрудником ответа.
  • Завершаться с ошибкой на неизвестных полях вместо их пропуска. Meta добавляет поля без предупреждения.
Настройка с EasyCoexistence

EasyCoexistence подписывается на служебные поля для мониторинга и отправляет два поля сообщений на ваш эндпоинт либо отбрасывает их без сохранения, если эндпоинт не задан.

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

Можно ли получать только некоторые поля?

Переопределение направляет путь сообщений к вам. Разделение служебных полей фиксировано, поскольку на нём построен мониторинг.

Есть ли smb_message_echoes у обычного номера Cloud API?

Нет. Это поле существует потому, что с номера Coexistence сотрудник отправляет сообщения из приложения, а программа отправляет их через API.

Что происходит с событиями сообщений, если не указать назначение?

Они поступают в наш callback по умолчанию и отбрасываются без сохранения.

Имена полей принадлежат Meta или вам?

Meta. Мы не придумывали эти имена, поэтому их достаточно выучить один раз.

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

The messages webhookEverything a customer sends arrives on this field. What the payload carries, how to acknowledge it, and why it never reaches a provider on a routed number.The smb_message_echoes webhookHow software sees what a human sent from the WhatsApp Business app. Only exists on Coexistence numbers, and ignoring it causes double replies.The account_update webhook, and every disconnection reasonaccount_update reports connection state changes. The full list of disconnection reasons Meta sends, what each means, and which ones are recoverable.The phone_number_quality_update webhookWhat this webhook actually carries as of 2026, why the colour quality rating is not in it, and where the rating has to be read from instead.The WhatsApp Business Account, and why overrides live on itWhat a WABA holds, why webhook overrides are applied at this level rather than per number, and what that means when a connection is removed.WhatsApp Cloud API error codesEvery WhatsApp Cloud API error code in one table: what each one means, whether retrying helps, and the page that covers it in full.

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

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

Начать бесплатный пробный периодВ течение 7 дней ничего не списывается. Отмена в любое время.

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

Поля вебхука WhatsApp