# Regras de palavras-chave do WhatsApp

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**](https://bird.com/dashboard/w/whatsapp/keyword-rules) é 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](/images/docs/dashboard-whatsapp-keyword-rules.png)

## 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.

**TypeScript**

```typescript
const rules = await bird.whatsapp.keywordRules.list({ operation: "opt_out" });
for (const rule of rules.data ?? []) {
  console.log(rule.scope, rule.effective_keywords);
}
```

Examples: [TypeScript](/pt-br/documentacao/guides/whatsapp/opt-outs/keyword-rules.ts.md) · [Python](/pt-br/documentacao/guides/whatsapp/opt-outs/keyword-rules.py.md) · [Go](/pt-br/documentacao/guides/whatsapp/opt-outs/keyword-rules.go.md) · [PHP](/pt-br/documentacao/guides/whatsapp/opt-outs/keyword-rules.php.md) · [CLI](/pt-br/documentacao/guides/whatsapp/opt-outs/keyword-rules.cli.md) · [MCP](/pt-br/documentacao/guides/whatsapp/opt-outs/keyword-rules.mcp.md) · [cURL](/pt-br/documentacao/guides/whatsapp/opt-outs/keyword-rules.curl.md)

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:

**TypeScript**

```typescript
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);
```

Examples: [TypeScript](/pt-br/documentacao/guides/whatsapp/opt-outs/keyword-rules.ts.md) · [Python](/pt-br/documentacao/guides/whatsapp/opt-outs/keyword-rules.py.md) · [Go](/pt-br/documentacao/guides/whatsapp/opt-outs/keyword-rules.go.md) · [PHP](/pt-br/documentacao/guides/whatsapp/opt-outs/keyword-rules.php.md) · [CLI](/pt-br/documentacao/guides/whatsapp/opt-outs/keyword-rules.cli.md) · [MCP](/pt-br/documentacao/guides/whatsapp/opt-outs/keyword-rules.mcp.md) · [cURL](/pt-br/documentacao/guides/whatsapp/opt-outs/keyword-rules.curl.md)

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`.

![Uma caixa de diálogo para adicionar uma regra de palavra-chave, com campos para palavras-chave extras e uma resposta](/images/docs/dashboard-whatsapp-keyword-rule-dialog.png)

## Adicionando suas próprias palavras-chave

**TypeScript**

```typescript
// 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);
```

Examples: [TypeScript](/pt-br/documentacao/guides/whatsapp/opt-outs/keyword-rules.ts.md) · [Python](/pt-br/documentacao/guides/whatsapp/opt-outs/keyword-rules.py.md) · [Go](/pt-br/documentacao/guides/whatsapp/opt-outs/keyword-rules.go.md) · [PHP](/pt-br/documentacao/guides/whatsapp/opt-outs/keyword-rules.php.md) · [CLI](/pt-br/documentacao/guides/whatsapp/opt-outs/keyword-rules.cli.md) · [MCP](/pt-br/documentacao/guides/whatsapp/opt-outs/keyword-rules.mcp.md) · [cURL](/pt-br/documentacao/guides/whatsapp/opt-outs/keyword-rules.curl.md)

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 é:

1. Sua regra para uma conta e país.
2. Sua regra para a conta.
3. Sua regra para o país.
4. Regra de Bird para o país do remetente.
5. Sua regra mundial.
6. 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:

**TypeScript**

```typescript
// 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");
```

Examples: [TypeScript](/pt-br/documentacao/guides/whatsapp/opt-outs/keyword-rules.ts.md) · [Python](/pt-br/documentacao/guides/whatsapp/opt-outs/keyword-rules.py.md) · [Go](/pt-br/documentacao/guides/whatsapp/opt-outs/keyword-rules.go.md) · [PHP](/pt-br/documentacao/guides/whatsapp/opt-outs/keyword-rules.php.md) · [CLI](/pt-br/documentacao/guides/whatsapp/opt-outs/keyword-rules.cli.md) · [MCP](/pt-br/documentacao/guides/whatsapp/opt-outs/keyword-rules.mcp.md) · [cURL](/pt-br/documentacao/guides/whatsapp/opt-outs/keyword-rules.curl.md)

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](/docs/guides/whatsapp/opt-outs/preferences): os registros que uma palavra-chave cria e quais deles você pode reverter.
- [Supressões](/docs/guides/whatsapp/opt-outs/suppressions): os endereços que o seu espaço de trabalho bloqueia diretamente.
- [Opt-outs e palavras-chave para SMS](/docs/guides/sms/opt-outs-and-keywords): o mesmo mecanismo no outro canal, que também inclui palavras-chave de ajuda e campanha.

## Related resources

- [Connecting WhatsApp to Bird: from buying a number to a live channel](/learn/whatsapp/connecting-whatsapp-to-bird) (video)
- [What is the 24-hour customer service window on WhatsApp?](/explained/whatsapp/what-is-the-24-hour-customer-service-window) (answer)
- [WhatsApp message builder](/tools/whatsapp-message-builder) (tool)
- [WhatsApp](/whatsapp-api) (product)

[Get an implementation brief](/learn/workspace?topic=whatsapp)