Вебхук user_preferences: когда клиент отключает или возобновляет маркетинговые сообщения
Вебхук user_preferences сообщает бизнесу, что пользователь WhatsApp остановил или возобновил маркетинговые сообщения через настройку «Предложения и объявления». Каждое событие содержит категорию marketing_messages, значение stop или resume, пояснительную строку, wa_id и BSUID пользователя, а также метку времени Unix. Отметки «Интересно» и «Не интересно» в той же настройке этот вебхук не запускают.
easyCoexistence подключает номер вашего приложения WhatsApp Business к Cloud API Meta через Coexistence, поэтому ваш ИИ и автоматизации работают на номере, который вы держите в приложении.
Значения настройки: stop и resume, оба в категории marketing_messages.
Код ошибки для статуса failed при отправке маркетингового шаблона пользователю, который отключил ваши маркетинговые сообщения.
Куда Meta отправляет user_preferences: это поле, которое аккаунт WhatsApp Business или номер не могут переопределить.
Разрешение, нужное приложению для вебхуков, кроме messages и calls, включая user_preferences.
Что запускает вебхук user_preferences?
Клиент открывает «Предложения и объявления» в WhatsApp и выбирает, отключить или позже снова включить маркетинговые сообщения от вашего бизнеса. Только эти два действия запускают вебхук. Та же настройка позволяет отметить «Интересно» или «Не интересно». Эта обратная связь вебхук не отправляет, хотя «Не интересно» может снизить лимит маркетинговых сообщений между вами и этим клиентом и открывает второй экран с предложением полностью отключить маркетинг. Только если клиент затем нажмёт отключить, срабатывает user_preferences.
Что содержит тело запроса?
Массив user_preferences рядом с массивом contacts, в поле с именем user_preferences. Здесь метка времени является целым числом, тогда как статусные вебхуки присылают её строкой. Поле wa_id отсутствует, если клиент использует имя пользователя и номер телефона нельзя передать. Поле user_id отсутствует, если для вашего бизнеса не включены идентификаторы пользователей в рамках бизнеса, а parent_user_id отсутствует, если не включены родительские BSUID. Пример возобновления от Meta:
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "102290129340398",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "15550783881",
"phone_number_id": "106540352242922"
},
"contacts": [
{
"wa_id": "16505551234",
"user_id": "US.13491208655302741918",
"parent_user_id": "US.ENT.506847293015824"
}
],
"user_preferences": [
{
"wa_id": "16505551234",
"user_id": "US.13491208655302741918",
"parent_user_id": "US.ENT.506847293015824",
"detail": "User requested to resume marketing messages",
"category": "marketing_messages",
"value": "resume",
"timestamp": 1731705721
}
]
},
"field": "user_preferences"
}
]
}
]
}Что должна делать ваша система при остановке?
Записать отключение за клиентом и исключать его из каждой маркетинговой рассылки до получения возобновления. В поле detail приходит либо «User requested to stop marketing messages», либо «User requested to resume marketing messages», но код должен читать value.
- Храните настройку по BSUID и по номеру телефона, так как любой из них может отсутствовать в конкретном событии.
- Исключайте клиента из отправок маркетинговых шаблонов: Meta всё равно отклонит их с кодом 131050.
- Применяйте настройку только к конкретному клиенту: Meta никогда не применяет её на уровне родительского BSUID.
- При возобновлении снимайте исключение, а собственную запись о согласии сохраняйте, как того требует политика Meta в отношении opt-in.
Что, если user_preferences никогда не доходит до вашего сервера?
Meta всё равно применяет отключение, поэтому пропущенный вебхук стоит вам неотправленного сообщения, а не нарушения политики. Когда вы отправляете маркетинговый шаблон тому, кто отключил рассылки, API принимает запрос, но не отправляет сообщение и запускает статусный вебхук со статусом failed, кодом 131050 и заголовком «Unable to deliver the message. This recipient has chosen to stop receiving marketing messages on WhatsApp from your business». Обрабатывайте эту ошибку точно так же, как событие отключения: записывайте её и подавляйте дальнейшие маркетинговые отправки этому клиенту.
Как это работает на номере, подключённом через easyCoexistence?
Поле user_preferences не входит в список полей, для которых Meta разрешает переопределять адрес доставки, поэтому Meta доставляет его только на обратный вызов по умолчанию приложения, подписанного на аккаунт. Для номера, подключённого через easyCoexistence, это приложение принадлежит easyCoexistence, и сегодня оно не подписано на user_preferences, поэтому событие не доходит ни до прямого адреса, ни до Forward URL. Статус 131050 доходит, потому что передаётся через поле messages.
Если ваш ИИ отправляет маркетинговые шаблоны через send_template, ведите список отключений в своей системе и проверяйте его первым: easyCoexistence такого списка не ведёт.
Распространённые ошибки
- Считать «Не интересно» отключением. Вебхук при этом не отправляется и доставка не останавливается, хотя для этого клиента может снизиться лимит маркетинговых сообщений.
- Привязывать настройки только к wa_id. Он не передаётся клиентам с именем пользователя, если номер нельзя передать, поэтому сохраняйте и BSUID.
- Применять отключение ко всем под родительским BSUID. Meta применяет настройки для каждого пользователя, никогда на уровне родителя.
- Повторять отправку после 131050 вместо того, чтобы записать её как отключение. Каждая повторная попытка завершается так же.
Маркетинговые шаблоны, отправленные через него, уходят с вашего собственного аккаунта WhatsApp Business, а статусы, которые сообщают об отключившем рассылку клиенте, доходят до вашего сервера напрямую или как подписанные пересылки. От US$ 9 до US$ 0,75 за номер в месяц, с понижением по мере добавления номеров, первые 3 дня бесплатно.
Часто задаваемые вопросы
Отключение также блокирует ответы на собственные сообщения клиента?
Документация Meta описывает отключение как касающееся маркетинговых сообщений, и ошибка, которую она возвращает, называет маркетинговые сообщения. Ответы клиенту, который написал вам, являются сервисными сообщениями, это другая категория.
Блокировка бизнеса запускает user_preferences?
Нет. Вебхук срабатывает только при отключении и возобновлении в настройке «Предложения и объявления». Блокировка отдельное действие, и в этом поле оно не отражается.
Возобновление считается opt-in?
Это значит, что клиент выбрал снова получать ваши маркетинговые сообщения. Ваши собственные обязательства по opt-in согласно политике Meta по-прежнему действуют, поэтому храните запись о том, как и когда этот клиент согласился получать от вас сообщения.
На какое поле вебхука подписываться?
На user_preferences, в App Dashboard в разделе WhatsApp > Configuration, в приложении, подписанном на аккаунт WhatsApp Business. Это поле отдельно от messages и требует whatsapp_business_management.
Читайте дальше
Готовы начать?
Настройте WhatsApp Coexistence за несколько минут, а не месяцев. Приложение продолжит работать на телефоне.
Начать бесплатный пробный периодПроверено по состоянию на