Regras de palavras-chave
Bird já vem com o catálogo de palavras-chave, então um destinatário que responde STOP a um dos seus números com recebimento habilitado é descadastrado sem nenhuma configuração da sua parte. START reverte isso. Uma regra sua substitui o padrão de Bird no escopo que ela cobre.
Esta página cobre o que 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 Bird reconhece por padrão
Nove palavras registram um opt-out:
stop, stop all, stopall, unsubscribe, cancel, end, quit, revoke, optout
Duas revertem: start e unstop.
A comparação é feita na mensagem inteira e não em uma substring. Como cancel e end são palavras-chave, essa distinção 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. Pontuação antes ou dentro da palavra não é ignorada, então #stop não corresponde.
Onde palavras-chave não são comparadas
Uma palavra-chave dentro de uma mensagem de grupo é ignorada, então um participante não pode se descadastrar respondendo ali. Respeite o opt-out declarado de um membro do grupo na sua própria lógica de envio.
Quando a preferência é registrada
A classificação acontece em paralelo ao evento whatsapp.received e não antes dele. Uma integração observando esse evento pode, portanto, ver um STOP chegar antes de a preferência que ele registra existir. Se o seu handler reage à mensagem recebida enviando algo, releia os registros do destinatário em vez de assumir a ordem dos eventos.
Vendo o que se aplica
GET /v1/whatsapp/keyword-rules descreve como respostas aos seus números são tratadas. Sem filtro, retorna o catálogo de Bird junto com quaisquer regras que você criou. Filtre com country, waba, operation ou scope:
- scope=system retorna o catálogo de 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);
}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 voltam da mais específica primeiro, que é a ordem em que uma mensagem recebida é comparada com elas. Cada uma carrega effective_keywords: o conjunto de Bird para aquela operação e país, mais o que você adicionou.
Para uma regra sua sem country, effective_keywords mostra o conjunto mundial de Bird, porque a regra não tem país e o país do remetente é desconhecido até uma mensagem chegar. Essa regra é comparada com o conjunto de Bird para o país do remetente, que pode ser maior. Defina um country na sua regra para ver exatamente o que esses remetentes correspondem.
country é o país do remetente, determinado pelo próprio número de telefone dele e não pelo número para o qual ele enviou a mensagem. É o sinal de país que WhatsApp envia. Um remetente identificado por um user ID com escopo de negócio não carrega país, então uma mensagem dele pula as regras com escopo de país e corresponde a uma regra mundial.
Alterando a resposta
As respostas padrão de 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 de Bird para aquele escopo e mantém as palavras-chave de Bird. Suas keywords são adições e não uma substituição, então uma palavra-chave que Bird incluir depois começa a corresponder sem nenhuma alteração sua.
Para não enviar nada e mesmo assim registrar o opt-out, omita reply ao criar a regra. Para silenciar uma regra existente, defina reply como null em um body JSON na atualização abaixo; um flag CLI não pode carregar null.

Adicionando 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"]}'Omitir keywords deixa suas adições intactas. Enviar um array vazio as limpa de volta para o conjunto de Bird.
Escopo da regra e duplicatas
Uma regra pode se restringir a uma WhatsApp Business Account com waba, a um país do remetente com country, a ambos ou a nenhum. Você mantém uma regra por combinação de operação, país e conta. Uma segunda escrita para a mesma combinação retorna um erro de duplicata.
Bird rejeita uma regra que vincule stop a opt_in, seja a palavra vinda do catálogo de Bird ou de outra regra sua, para que uma palavra de opt-out não possa conceder consentimento.
Excluindo uma regra
Excluir sua regra passa aquele escopo para a próxima regra na ordem de comparação, que nem sempre é uma das suas. A ordem é:
- Sua regra para uma conta e país.
- Sua regra para a conta.
- Sua regra para o país.
- Regra de Bird para o país do remetente.
- Sua regra mundial.
- Regra mundial de Bird.
Excluir sua regra para um país, portanto, passa o escopo para a regra de Bird daquele 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; STOP never stops working.
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; STOP never stops working.
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; STOP never stops working.
$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"Excluir uma regra não faz STOP parar de funcionar. Ela devolve o texto e o conjunto de palavras-chave para qualquer regra que venha a seguir naquela ordem.
Próximos passos
- Preferências: os registros que uma palavra-chave cria e quais deles você pode reverter.
- Supressões: os endereços que o seu espaço de trabalho bloqueia diretamente.
- Opt-outs e palavras-chave para SMS: o mesmo mecanismo no outro canal, que também inclui palavras-chave de ajuda e campanha.
Recursos relacionados
Continue com a documentação, guias e exemplos sobre este tópico. Os recursos estão em inglês.
Assista ao guiaConnecting WhatsApp to Bird: from buying a number to a live channelEntenda o conceitoWhat is the 24-hour customer service window on WhatsApp?Use a ferramentaWhatsApp message builderExplore a funcionalidadeWhatsApp
Experimente na prática e obtenha um resumo de implementação