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.
Valores que uma preferência pode assumir: stop e resume, ambos na categoria marketing_messages.
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.
Para onde a Meta envia o user_preferences: não é um campo que uma WhatsApp Business Account ou um número possa substituir.
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:
{
"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.
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 gratuitoVerificado em