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

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

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

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

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

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

Не храним сообщения по умолчанию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

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

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

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

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

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

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

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

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

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

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

Вебхук messagesЧто несёт полезная нагрузка, как подтвердить получение и почему поле не попадает к провайдеру на маршрутизированном номере.Вебхук smb_message_echoesКак программа видит сообщения человека из WhatsApp Business. Поле есть только у номеров Coexistence: без него клиент может получить два ответа.Вебхук account_update и все причины отключенияaccount_update сообщает об изменениях состояния подключения. Полный список причин отключения от Meta, их значение и возможность восстановления.Вебхук phone_number_quality_updateЧто этот вебхук передаёт в 2026 году, почему рейтинг качества цвета отсутствует и где его читать.Аккаунт WhatsApp Business и почему переопределения действуют на нёмЧто хранит WABA, почему переопределение вебхука действует на уровне аккаунта, а не номера, и что происходит после удаления подключения.Коды ошибок WhatsApp Cloud APIВсе коды ошибок WhatsApp Cloud API в одной таблице: значение, необходимость повтора и ссылка на подробное описание.

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

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

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

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