Sign inGet Started

Regras de palavras-chave do WhatsApp

O Bird já vem com o catálogo de palavras-chave, então um destinatário que responde STOP a um dos seus números que recebem mensagens tem o descadastro registrado sem nenhuma configuração da sua parte. START desfaz o descadastro. Uma regra sua substitui o padrão do Bird no escopo que ela abrange.

Esta página explica o que o Bird reconhece, como uma mensagem recebida é comparada e como alterar o texto ou adicionar palavras-chave. A página Keywords é o equivalente no painel.

Uma lista de regras de palavras-chave, com as regras do espaço de trabalho acima das regras padrão que elas substituem

O que o Bird reconhece por padrão

Nove palavras registram um descadastro:

stop, stop all, stopall, unsubscribe, cancel, end, quit, revoke, optout

Duas o desfazem: start e unstop.

A comparação considera a mensagem inteira, e não um trecho dela. Como cancel e end são palavras-chave, essa diferença importa: "cancel my 3pm delivery" é uma mensagem comum, e não uma retirada de consentimento. Maiúsculas e minúsculas, acentos, espaços repetidos e pontuação no final são ignorados, então Stop! e STOP correspondem. A pontuação antes ou dentro da palavra não é ignorada, então #stop não corresponde.

Onde as palavras-chave não são comparadas

Uma palavra-chave dentro de uma mensagem de grupo é ignorada, então um participante não consegue cancelar a inscrição respondendo ali. Respeite na sua própria lógica de envio o cancelamento que um membro do grupo declarar.

Quando a preferência é registrada

A classificação é executada em paralelo ao evento whatsapp.received, e não antes dele. Por isso, uma integração que acompanha esse evento pode ver um STOP chegar antes de existir a preferência que ele registra. Se o seu handler reage à mensagem recebida enviando algo, leia novamente os registros do destinatário em vez de contar com a ordem dos eventos.

Como ver o que se aplica

GET /v1/whatsapp/keyword-rules descreve como as respostas aos seus números são tratadas. Sem filtros, retorna uma linha por escopo: a sua regra onde você tiver uma e a da Bird onde não tiver. Uma regra sua sem waba substitui a regra da Bird para a mesma operação e o mesmo país. Restrinja o resultado com country, waba, operation ou scope:

  • scope=system retorna o catálogo da Bird, incluindo o padrão que uma regra sua substitui.
  • scope=workspace retorna as suas próprias regras.
const rules = await bird.whatsapp.keywordRules.list({ operation: "opt_out" });
for (const rule of rules.data ?? []) {
  console.log(rule.scope, rule.effective_keywords);
}

As regras são retornadas da mais específica para a menos específica, que é a ordem em que uma mensagem recebida é comparada a elas. Cada uma traz effective_keywords: o conjunto da Bird para essa operação e esse país, sem o que você removeu e com o que você adicionou.

Para uma regra sua sem country, effective_keywords mostra o conjunto mundial da Bird, porque a regra não tem país e o país do remetente só é conhecido quando uma mensagem chega. Essa regra é comparada ao conjunto da Bird para o país do remetente, que pode ser maior. Defina um country na sua regra para ver exatamente com o que esses remetentes correspondem.

country é o país do remetente, determinado pelo número de telefone dele, e não pelo número para o qual ele enviou a mensagem. É o sinal de país que a WhatsApp envia. Um remetente identificado por um ID de usuário vinculado à empresa não tem país, então uma mensagem dele ignora as regras com escopo de país e corresponde a uma regra mundial.

Como alterar a resposta

As respostas padrão da Bird são corretas, mas genéricas. Para responder em seu próprio nome, crie uma regra:

const rule = await bird.whatsapp.keywordRules.create({
  operation: "opt_out",
  country: "US", // the SENDER's country, from their own number
  reply: "You're off the list. ACME Courier won't message you again.",
});
// effective_keywords is Bird's set plus any of your own.
console.log(rule.id, rule.effective_keywords);

Sua regra substitui a resposta do Bird nesse escopo e mantém as palavras-chave do Bird. Suas keywords são acréscimos, não uma substituição, então uma palavra-chave que o Bird incluir depois passa a ser reconhecida sem nenhuma alteração da sua parte.

Para não enviar nada e ainda assim registrar o opt-out, omita reply ao criar a regra. Para silenciar uma regra existente, defina reply como null em um corpo JSON na atualização abaixo; uma flag CLI não consegue transmitir null.

Uma caixa de diálogo de regra de palavra-chave que lista as palavras-chave do Bird, uma palavra-chave adicionada, uma palavra-chave removida e uma resposta

Como adicionar suas próprias palavras-chave

// Omitting keywords leaves the set alone; an empty array clears your additions
// back to Bird's. reply: null switches the auto-reply off and still records
// the opt-out.
const rule = await bird.whatsapp.keywordRules.update("wkr_01m2kj8x4te9p0rr7e5w2n1abc", {
  keywords: ["no more texts", "remove me"],
});
console.log(rule.effective_keywords);

Se você omitir keywords, seus acréscimos permanecem como estão. Se enviar um array vazio, eles são apagados e volta a valer o conjunto do Bird.

Como remover palavras-chave do Bird

Algumas conversas precisam de cancel ou stop como palavras comuns, por exemplo em um fluxo de bot em que cancel significa cancelar esta etapa. Liste-as em excluded_keywords na sua regra:

Exemplo de código
curl -X POST https://us1.platform.bird.com/v1/whatsapp/keyword-rules \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"operation":"opt_out","waba":"102290129340398","excluded_keywords":["cancel","end"]}'

A partir daí, uma mensagem que seja exatamente uma delas não registra opt-out de ninguém e não recebe resposta para as pessoas cobertas pela regra. A mensagem continua chegando a você normalmente, e a regra do próprio Bird não age sobre ela no lugar da sua. Exclua todas as palavras-chave do Bird para desativá-las. Uma palavra-chave que o Bird incluir depois continua sendo reconhecida, a menos que sua regra já a exclua. Com palavras-chave removidas, cabe a você respeitar os opt-outs que elas representam. O botão de opt-out da própria Meta nos templates de marketing continua funcionando.

Em uma atualização, excluded_keywords substitui o conjunto removido, um array vazio não remove nenhuma palavra-chave e omiti-lo mantém o conjunto como está. Uma palavra-chave não pode ser adicionada e excluída ao mesmo tempo. Cada palavra-chave excluída precisa ser uma das palavras-chave do Bird para a operação da regra. Para uma regra com country, ela precisa ser uma das palavras-chave do Bird para esse país, ou uma das palavras-chave mundiais do Bird se o Bird não tiver nenhuma para ele. O Bird recusa qualquer outra palavra com um 422, porque, caso contrário, removeria essa palavra se o Bird passasse a incluí-la depois.

Escopo das regras e duplicatas

Uma regra pode se restringir a uma Business Account do WhatsApp com waba, a um país do remetente com country, a ambos ou a nenhum. Você pode ter uma regra por combinação de operação, país e conta. Uma segunda gravação para a mesma combinação retorna um erro de duplicata.

O Bird rejeita uma regra que vincule stop a opt_in, seja a palavra do catálogo do Bird ou de outra regra sua, para que uma palavra de opt-out não possa ser usada para conceder consentimento.

Como excluir uma regra

Quando você exclui sua regra, esse escopo passa para a próxima regra na ordem de correspondência, que nem sempre é uma das suas. A ordem é:

  1. Sua regra para uma conta e um país.
  2. Sua regra para a conta.
  3. Sua regra para o país.
  4. A regra da Bird para o país do remetente.
  5. Sua regra mundial.
  6. A regra mundial da Bird.

Por isso, quando você exclui sua regra para um país, o escopo passa para a regra da Bird para esse país antes da sua própria regra mundial:

// The next rule in the ladder answers the scope, which is another rule of yours if you hold a less specific one.
await bird.whatsapp.keywordRules.delete("wkr_01m2kj8x4te9p0rr7e5w2n1abc");

Ao excluir uma regra, o texto e o conjunto de palavras-chave voltam a ser os da regra que vem em seguida nessa ordem. Se essa regra for uma das suas que exclui stop, STOP também não tem efeito ali.

Próximos passos

  • Preferências: os registros que uma palavra-chave cria e quais deles você pode reverter.
  • Supressões: os endereços que seu espaço de trabalho bloqueia diretamente.