EntrarComeçar teste grátis
Meta Tech Provider

Webhook user_preferences do WhatsApp: quando um cliente para de receber ou volta a receber mensagens de marketing

O webhook user_preferences avisa a uma empresa que um usuário do WhatsApp parou de receber ou voltou a receber as mensagens de marketing dela pela configuração Ofertas e anúncios. Cada evento traz a categoria marketing_messages, um valor stop ou resume, uma frase de detalhe, o wa_id e o BSUID do usuário e um timestamp Unix. O feedback Interessado e Não tenho interesse, na mesma configuração, não dispara o webhook.

O easyCoexistence conecta o número do seu app do WhatsApp Business à Cloud API da Meta por meio da Coexistência, para que sua IA e suas automações funcionem no número que você mantém no app.

2

Valores que uma preferência pode assumir: stop e resume, ambos na categoria marketing_messages.

131050

O código do status de falha de um template de marketing enviado a um usuário que deixou de receber suas mensagens de marketing.

Default callback

Para onde a Meta envia user_preferences: não é um campo que uma WhatsApp Business Account ou um número possa sobrescrever.

whatsapp_business_management

A permissão de que um app precisa para webhooks além de messages e calls, incluindo user_preferences.

O que dispara o webhook user_preferences?

Um cliente abrir Ofertas e anúncios no WhatsApp e escolher deixar de receber, ou depois voltar a receber, as mensagens de marketing da sua empresa. Essas duas ações são os únicos gatilhos. A mesma configuração também permite marcar Interessado ou Não tenho interesse, e esse feedback não envia webhook, embora Não tenho interesse possa reduzir o limite de marketing por usuário entre você e esse cliente e abra uma segunda tela que oferece interromper de vez as mensagens de marketing. O user_preferences só dispara se o cliente então tocar em parar.

O que o payload contém?

Um array user_preferences ao lado de um array contacts, no campo user_preferences. Aqui o timestamp é um inteiro, enquanto os webhooks de status o enviam como string. O wa_id fica de fora quando o cliente usa um username e o número de telefone dele não pode ser compartilhado; o user_id, quando os IDs de usuário com escopo de empresa não estão habilitados para a sua empresa; e o parent_user_id, quando os BSUIDs pai não estão ativados. Exemplo da Meta de um resume:

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"
        }
      ]
    }
  ]
}

O que o seu sistema deve fazer com um stop?

Registrá-lo no cadastro do cliente e deixá-lo fora de todo envio de marketing até chegar um resume. O campo detail traz "User requested to stop marketing messages" ou "User requested to resume marketing messages", mas é value que o código deve ler.

  • Guarde a preferência pelo BSUID e pelo número de telefone, já que qualquer um dos dois pode faltar em um evento.
  • Exclua o cliente dos envios de template de marketing; a Meta os recusaria de qualquer forma com 131050.
  • Aplique a preferência só por cliente: a Meta nunca aplica uma preferência no nível do BSUID pai.
  • Ao receber um resume, remova a exclusão e mantenha seu próprio registro de opt-in, como exige a política de opt-in da Meta.

E se o user_preferences nunca chegar ao seu servidor?

A Meta aplica o stop mesmo assim, então um webhook que não chega custa um envio com falha, não uma violação de política. Quando você envia um template de marketing para alguém que pediu para parar, a API aceita a requisição, não envia a mensagem e dispara um webhook de status com status failed, código 131050 e o título "Unable to deliver the message. This recipient has chosen to stop receiving marketing messages on WhatsApp from your business". Trate essa falha exatamente como um evento de stop: registre-a e bloqueie novos envios de marketing para esse cliente.

Como isso funciona em um número conectado pelo easyCoexistence?

O user_preferences não está entre os campos para os quais a Meta permite sobrescrever o destino, então ela o entrega apenas ao callback padrão do app que assinou a conta. Em um número conectado pelo easyCoexistence, esse app é o do easyCoexistence, que hoje não assina o user_preferences; por isso, o evento não chega a um destino direto nem a uma Forward URL. O status de falha 131050 chega, porque trafega no campo messages.

Se a sua IA envia templates de marketing com send_template, mantenha a lista de quem pediu para parar no seu próprio sistema e consulte-a antes de enviar: o easyCoexistence não mantém essa lista.

Erros comuns

  • Tratar Não tenho interesse como um stop. Ele não envia webhook e não interrompe a entrega, embora possa reduzir o limite de marketing por usuário para esse cliente.
  • Usar só o wa_id como chave das preferências. Ele é omitido para clientes com username cujo número não pode ser compartilhado; guarde também o BSUID.
  • Aplicar um stop a todos sob um BSUID pai. A Meta aplica preferências por usuário, nunca no nível pai.
  • Repetir o envio após 131050 em vez de registrá-lo como stop. Toda repetição falha da mesma forma.
Fazendo isso com o EasyCoexistence

Os templates de marketing enviados por ele saem pela sua própria WhatsApp Business Account, e os status de falha que indicam que um cliente pediu para parar chegam ao seu servidor diretamente ou como encaminhamentos assinados. De R$ 29,90 a R$ 3,90 por número por mês, caindo conforme você adiciona números, com os 3 primeiros dias grátis.

O easyCoexistence é uma API e um servidor MCP multicanal que conecta agentes de IA, como o Claude e o ChatGPT, ao WhatsApp, Instagram, TikTok, Facebook e mais. No WhatsApp, ele usa o Coexistence: a empresa continua usando o número no app WhatsApp Business enquanto a IA trabalha pela API oficial da Meta.

Perguntas frequentes

O stop também bloqueia as respostas às mensagens que o próprio cliente envia?

A documentação da Meta descreve o stop como algo que abrange mensagens de marketing, e o erro retornado fala em mensagens de marketing. Respostas a um cliente que escreveu para você são mensagens de serviço, outra categoria.

Bloquear a empresa dispara o user_preferences?

Não. O webhook só dispara com stop e resume na configuração Ofertas e anúncios. Bloquear é uma ação separada e não é informada neste campo.

Um resume conta como opt-in?

Significa que o cliente escolheu voltar a receber suas mensagens de marketing. Suas próprias obrigações de opt-in pela política da Meta continuam valendo, então guarde o registro de como e quando esse cliente concordou em receber suas mensagens.

Qual campo de webhook devo assinar?

user_preferences, no App Dashboard em WhatsApp > Configuration, no app que assina a WhatsApp Business Account. É um campo separado de messages e exige whatsapp_business_management.

Continue lendo

Pronto para começar?

Configure o WhatsApp Coexistence em minutos, não em meses. O aplicativo continua funcionando no celular.

Começar teste grátis

Verificado em