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

Вебхук user_preferences: когда клиент отключает или возобновляет маркетинговые сообщения

Вебхук user_preferences сообщает бизнесу, что пользователь WhatsApp остановил или возобновил маркетинговые сообщения через настройку «Предложения и объявления». Каждое событие содержит категорию marketing_messages, значение stop или resume, пояснительную строку, wa_id и BSUID пользователя, а также метку времени Unix. Отметки «Интересно» и «Не интересно» в той же настройке этот вебхук не запускают.

easyCoexistence подключает номер вашего приложения WhatsApp Business к Cloud API Meta через Coexistence, поэтому ваш ИИ и автоматизации работают на номере, который вы держите в приложении.

2

Значения настройки: stop и resume, оба в категории marketing_messages.

131050

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

Default callback

Куда Meta отправляет user_preferences: это поле, которое аккаунт WhatsApp Business или номер не могут переопределить.

whatsapp_business_management

Разрешение, нужное приложению для вебхуков, кроме messages и calls, включая user_preferences.

Что запускает вебхук user_preferences?

Клиент открывает «Предложения и объявления» в WhatsApp и выбирает, отключить или позже снова включить маркетинговые сообщения от вашего бизнеса. Только эти два действия запускают вебхук. Та же настройка позволяет отметить «Интересно» или «Не интересно». Эта обратная связь вебхук не отправляет, хотя «Не интересно» может снизить лимит маркетинговых сообщений между вами и этим клиентом и открывает второй экран с предложением полностью отключить маркетинг. Только если клиент затем нажмёт отключить, срабатывает user_preferences.

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

Массив user_preferences рядом с массивом contacts, в поле с именем user_preferences. Здесь метка времени является целым числом, тогда как статусные вебхуки присылают её строкой. Поле wa_id отсутствует, если клиент использует имя пользователя и номер телефона нельзя передать. Поле user_id отсутствует, если для вашего бизнеса не включены идентификаторы пользователей в рамках бизнеса, а parent_user_id отсутствует, если не включены родительские BSUID. Пример возобновления от Meta:

Meta's example: a customer resumes marketing messages
{
  "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 вместо того, чтобы записать её как отключение. Каждая повторная попытка завершается так же.
Настройка с EasyCoexistence

Маркетинговые шаблоны, отправленные через него, уходят с вашего собственного аккаунта 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 не доставлено: чтение статуса failed и его ошибокСтатус failed значит, что Meta не смогла отправить или доставить сообщение. Разберите массив errors и коды 131047, 131049, 131050 и что делать.Статусы вебхуков WhatsApp: отправлено, доставлено, прочитано, ошибкаКак WhatsApp сообщает о судьбе отправленного сообщения: массив statuses, значения статусов, поля и сопоставление по wamid.Ошибка WhatsApp 131050: пользователь отказался от сообщенийОшибка 131050 означает, что получатель отказался от сообщений вашей компании. Почему это нужно уважать, а не обходить.Согласие на получение сообщений в WhatsApp: требования для бизнесаЧто требует политика Meta для WhatsApp Business перед сообщением клиенту: два условия, содержание согласия и правила отказа от рассылки.Автоматизация маркетинга в WhatsApp: шаблоны и согласиеАвтоматизируйте маркетинг в WhatsApp по правилам Meta: сначала согласие, затем одобренные шаблоны, автоматические ответы и высокое качество рассылки.Поля вебхука WhatsApp и их маршрутизацияВосемь полей вебхука Coexistence: что несёт каждое и какие поля идут на ваш эндпоинт, а какие остаются для мониторинга.

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

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

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

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