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.

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=systemretorna o catálogo da Bird, incluindo o padrão que uma regra sua substitui.scope=workspaceretorna 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);
}rules = client.whatsapp.keyword_rules.list(operation="opt_out")
for rule in rules.data or []:
print(rule.scope, rule.effective_keywords)rules, err := client.Whatsapp.KeywordRules.List(context.Background(), bird.WhatsappKeywordRulesListParams{
Operation: "opt_out", // omit for both operations, Bird's rules and your own
})
if err != nil {
log.Fatal(err)
}
for _, rule := range rules.Data {
fmt.Println(rule.Scope, rule.EffectiveKeywords)
}$rules = $bird->whatsapp->keywordRules->list(['operation' => 'opt_out']);
foreach ($rules->getData() ?? [] as $rule) {
echo $rule->getScope(), ' ', implode(',', $rule->getEffectiveKeywords() ?? []), PHP_EOL;
}bird whatsapp keyword-rules listcurl "https://us1.platform.bird.com/v1/whatsapp/keyword-rules?operation=opt_out" \
-H "Authorization: Bearer $BIRD_API_KEY"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);rule = client.whatsapp.keyword_rules.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.
print(rule.id, rule.effective_keywords)rule, err := client.Whatsapp.KeywordRules.Create(context.Background(), bird.WhatsappKeywordRulesCreateParams{
Operation: "opt_out",
Country: bird.String("US"), // the SENDER's country, from their own number
Reply: bird.String("You're off the list. ACME Courier won't message you again."),
})
if err != nil {
log.Fatal(err)
}
// EffectiveKeywords is Bird's set plus any of your own.
fmt.Println(rule.Id, rule.EffectiveKeywords)$rule = $bird->whatsapp->keywordRules->create(
(new WhatsAppKeywordRuleCreate())
->setOperation('opt_out')
->setCountry('US')
->setReply("You're off the list. ACME Courier won't message you again."),
);
// getEffectiveKeywords() is Bird's set plus any of your own.
echo $rule->getId(), ' ', implode(',', $rule->getEffectiveKeywords() ?? []);bird whatsapp keyword-rules create \
--country US \
--keywords 'no more texts' \
--keywords 'remove me' \
--operation opt_out \
--reply "You're off the list. ACME Courier won't message you again." \
--waba 102290129340398curl -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","country":"US","reply":"You'"'"'re off the list. ACME Courier won'"'"'t message you again."}'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.

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);# Omitting keywords leaves the set alone; an empty list clears your additions
# back to Bird's.
rule = client.whatsapp.keyword_rules.update(
"wkr_01m2kj8x4te9p0rr7e5w2n1abc", keywords=["no more texts", "remove me"]
)
print(rule.effective_keywords)// Omitting keywords leaves the set alone; an empty slice clears your
// additions back to Bird's.
rule, err := client.Whatsapp.KeywordRules.Update(context.Background(),
"wkr_01m2kj8x4te9p0rr7e5w2n1abc", bird.WhatsappKeywordRulesUpdateParams{
Keywords: []string{"no more texts", "remove me"},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(rule.EffectiveKeywords)// Omitting keywords leaves the set alone; an empty array clears your additions
// back to Bird's.
$rule = $bird->whatsapp->keywordRules->update(
'wkr_01m2kj8x4te9p0rr7e5w2n1abc',
(new WhatsAppKeywordRuleUpdate())->setKeywords(['no more texts', 'remove me']),
);
echo implode(',', $rule->getEffectiveKeywords() ?? []);bird whatsapp keyword-rules update <id> \
--keywords 'no more texts' \
--reply "You're off the list. ACME Courier won't message you again."curl -X PATCH https://us1.platform.bird.com/v1/whatsapp/keyword-rules/wkr_01m2kj8x4te9p0rr7e5w2n1abc \
-H "Authorization: Bearer $BIRD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"keywords":["no more texts"]}'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:
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 é:
- Sua regra para uma conta e um país.
- Sua regra para a conta.
- Sua regra para o país.
- A regra da Bird para o país do remetente.
- Sua regra mundial.
- 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");# The next rule in the ladder answers the scope, which is another rule of yours if you hold a less specific one.
client.whatsapp.keyword_rules.delete("wkr_01m2kj8x4te9p0rr7e5w2n1abc")if err := client.Whatsapp.KeywordRules.Delete(context.Background(),
"wkr_01m2kj8x4te9p0rr7e5w2n1abc"); err != nil {
log.Fatal(err)
}// The next rule in the ladder answers the scope, which is another rule of yours if you hold a less specific one.
$bird->whatsapp->keywordRules->delete('wkr_01m2kj8x4te9p0rr7e5w2n1abc');bird whatsapp keyword-rules delete <id> --yescurl -X DELETE https://us1.platform.bird.com/v1/whatsapp/keyword-rules/wkr_01m2kj8x4te9p0rr7e5w2n1abc \
-H "Authorization: Bearer $BIRD_API_KEY"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.
Recursos relacionados
Continue com a documentação, guias e exemplos sobre este tópico.