Iniciar sessãoIniciar teste gratuito
Meta Tech Provider

Webhook user_preferences do WhatsApp: quando um cliente deixa ou retoma as mensagens de marketing

O webhook user_preferences informa a empresa de que um utilizador do WhatsApp deixou ou retomou as suas mensagens de marketing através da definiçã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 utilizador, e um timestamp Unix. O feedback Interessado e Não interessado na mesma definição não o aciona.

A easyCoexistence liga o número da sua app WhatsApp Business à Cloud API da Meta através da Coexistência, para que a sua IA e as automatizações funcionem no número que mantém na app.

2

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

131050

O código de estado de falha de um template de marketing enviado a um utilizador que deixou de receber as mensagens de marketing da sua empresa.

Default callback

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

whatsapp_business_management

A permissão de que uma app precisa para webhooks que não sejam messages nem calls, incluindo user_preferences.

O que aciona o webhook user_preferences?

Um cliente que abre Ofertas e anúncios no WhatsApp e escolhe deixar de receber, ou mais tarde retomar, as mensagens de marketing da sua empresa. Estas duas ações são os únicos gatilhos. A mesma definição permite também ao cliente marcar Interessado ou Não interessado, e esse feedback não envia webhook, embora Não interessado possa reduzir o limite de marketing por utilizador entre a sua empresa e esse cliente e abra um segundo ecrã que propõe parar por completo as mensagens de marketing. Só se depois tocar em parar é que o user_preferences é acionado.

O que contém o payload?

Um array user_preferences ao lado de um array contacts, sob o nome de campo user_preferences. O timestamp aqui é um inteiro, enquanto os webhooks de estado o enviam como string. O wa_id é omitido quando o cliente utiliza um nome de utilizador e o número de telefone não pode ser partilhado, o user_id quando os IDs de utilizador com âmbito empresarial não estão ativados para a sua empresa, e o parent_user_id, a menos que os BSUIDs principais estejam ativos. Eis o exemplo da Meta de uma retoma:

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 deve o seu sistema fazer perante uma paragem?

Registe a paragem associada ao cliente e mantenha-o fora de todos os envios de marketing até chegar uma retoma. O campo detail diz «User requested to stop marketing messages» ou «User requested to resume marketing messages», mas o código deve ler o campo value.

  • Guarde a preferência por BSUID e por número de telefone, já que qualquer um dos dois pode faltar num dado evento.
  • Exclua o cliente dos envios de template de marketing, porque a Meta os recusaria de qualquer forma com 131050.
  • Aplique-a apenas por cliente: a Meta nunca aplica uma preferência ao nível do BSUID principal.
  • Na retoma, levante a exclusão e mantenha o seu próprio registo de opt-in, tal como a política de opt-in da Meta exige.

E se o user_preferences nunca chegar ao seu servidor?

A Meta aplica a paragem de qualquer forma, por isso um webhook em falta custa-lhe um envio falhado, não uma violação de política. Quando envia um template de marketing a alguém que parou, a API aceita o pedido, não envia a mensagem e aciona um webhook de estado 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 paragem: registe-a e suprima os envios de marketing seguintes a esse cliente.

Como funciona isto num número ligado através da easyCoexistence?

O user_preferences não está entre os campos para os quais a Meta permite substituir o destino, por isso a Meta só o entrega ao callback predefinido da app que subscreveu a conta. Num número ligado através da easyCoexistence, essa app é a da easyCoexistence, que hoje não subscreve o user_preferences, pelo que o evento não chega a um destino direto nem a um Forward URL. O estado de falha 131050 chega, porque viaja no campo messages.

Se a sua IA envia templates de marketing com send_template, mantenha a lista de exclusão no seu próprio sistema e verifique-a primeiro: a easyCoexistence não mantém uma.

Erros comuns

  • Tratar Não interessado como paragem. Não envia webhook nem interrompe a entrega, embora possa reduzir o limite de marketing por utilizador desse cliente.
  • Usar apenas o wa_id como chave das preferências. É omitido em clientes com nome de utilizador cujo número não pode ser partilhado; guarde também o BSUID.
  • Aplicar uma paragem a todos os utilizadores sob um BSUID principal. A Meta aplica as preferências por utilizador, nunca ao nível principal.
  • Voltar a tentar após o 131050 em vez de o registar como paragem. Cada tentativa falha da mesma forma.
Fazer isto com a EasyCoexistence

Os templates de marketing enviados por essa via saem da sua própria WhatsApp Business Account, e os estados de falha que assinalam um cliente que parou chegam ao seu servidor diretamente ou como encaminhamentos assinados. De US$ 9 a US$ 0.75 por número por mês, com descida à medida que acrescenta números, e os primeiros 3 dias gratuitos.

Perguntas frequentes

Uma paragem também bloqueia as respostas às mensagens do próprio cliente?

A documentação da Meta descreve a paragem como aplicável às mensagens de marketing, e o erro devolvido refere as mensagens de marketing. As respostas a um cliente que lhe escreveu são mensagens de serviço, uma categoria diferente.

Bloquear a sua empresa aciona o user_preferences?

Não. O webhook só é acionado com paragem e retoma na definição Ofertas e anúncios. Bloquear é uma ação à parte e não é comunicado neste campo.

Uma retoma conta como opt-in?

Significa que o cliente escolheu voltar a receber as suas mensagens de marketing. As suas obrigações de opt-in ao abrigo da política da Meta continuam a aplicar-se, por isso guarde o registo de como e quando esse cliente deu o seu acordo para ser contactado pela sua empresa.

Em que campo do webhook devo subscrever-me?

user_preferences, no painel da app em WhatsApp > Configuração, na app subscrita à WhatsApp Business Account. É um campo separado de messages e precisa da permissão whatsapp_business_management.

Continue a ler

Pronto para começar?

Configure a Coexistência do WhatsApp em minutos, não em meses. A aplicação continua a funcionar no telemóvel.

Começar período experimental gratuito

Verificado em