# Opt-outs e palavras-chave

Quando alguém envia uma mensagem para um dos seus números, Bird verifica a mensagem em um catálogo de palavras-chave antes de você recebê-la. Uma palavra-chave de **stop** reconhecida suprime mensagens futuras daquele remetente para o assinante, uma palavra-chave de **start** encerra a supressão, e **help** responde com informações de suporte. Países cobertos não exigem configuração para esse comportamento.

Este guia cobre o que Bird faz por padrão, como visualizar e como alterar.

## O que acontece por padrão

Um assinante envia `STOP` para um dos seus números. Bird:

1. **Reconhece a mensagem** comparando-a com o catálogo de palavras-chave do país daquele número.
2. **Registra uma supressão** naquele par exato de remetente e assinante.
3. **Confirma** respondendo com a mensagem de opt-out daquele país.

A partir daí, um envio daquele remetente para aquele assinante é recusado com [`E12077 SMSRecipientSuppressed`](/docs/api/errors/E12077) em vez de ser enviado. Um `START` encerra a supressão e também confirma, e `HELP` responde sem alterar nada.

Uma supressão cobre **um remetente e um assinante**. Ela não cobre todo o seu espaço de trabalho. O escopo técnico desse bloqueio não estabelece permissão para usar outro remetente. Aplique a preferência declarada do cliente às mensagens e ao programa que ele pediu para interromper. Para interromper todos os remetentes do espaço de trabalho de uma vez, veja [Opt-out de todos os remetentes](#opt-out-de-todos-os-remetentes) abaixo.

A confirmação é isenta da supressão que ela registra. Bird pode responder à mensagem recebida mesmo que a nova supressão bloqueie envios posteriores.

## A cobertura é por país

O catálogo de Bird cobre um **subconjunto de países**. Onde um país é coberto, Bird trata palavras-chave de opt-out, opt-in e help por padrão. Onde não é, Bird não reconhece nenhuma palavra-chave, não envia resposta e não registra opt-out. Se você envia para um país não coberto, deve tratar os opt-outs por conta própria.

Verifique o que um país possui antes de depender dele:

```bash
bird sms keyword-rules list --country NL
```

Um resultado vazio significa que o país não tem cobertura. Você pode adicionar suas próprias palavras-chave `custom` lá, mas todas as outras operações substituem algo que Bird fornece, então você só pode criar uma para um país presente no catálogo de Bird.

## Visualizando o que se aplica

`GET /v1/sms/keyword-rules` descreve como as respostas aos seus números são tratadas. Sem filtro, retorna todo o catálogo de Bird junto com quaisquer regras que você tenha criado; refine com `country`, `number`, `operation` ou `scope`:

- `scope=system` retorna apenas o catálogo de Bird, incluindo o padrão que uma regra do espaço de trabalho substituiu.
- `scope=workspace` retorna apenas suas próprias regras.
- `number=+18005551234` retorna as regras que se aplicam a um dos seus números, na ordem em que são aplicadas a uma mensagem recebida; adicione `from_country` para ver o que um remetente enviando de outro lugar recebe, o que pode ser diferente.

As regras retornam da mais específica para a menos, e cada uma traz `effective_keywords`: o conjunto de Bird para aquela operação e país mais o que você adicionou.

A lista retorna duas operações além de `stop`, `start` e `help`:

- `info` responde com as informações do seu programa e se comporta exatamente como `help`. É separado para que um país cuja resposta INFO precise diferir da resposta HELP possa ter ambas; onde Bird não fornece uma regra `info` para um país, INFO é uma das palavras-chave `help` daquele país e responde com a resposta `help`.
- `confirm` marca uma resposta de double opt-in, como `JOIN` ou `YES`. Não envia nada no momento, então responda a partir do seu próprio handler. Bird mantém essas palavras-chave para que uma regra `custom` não possa reivindicá-las.

## Alterando a resposta

As respostas padrão de Bird são corretas, mas genéricas. Para responder com o nome da sua empresa, crie uma regra para aquele país e operação:

```bash
bird sms keyword-rules create \
  --operation stop \
  --country NL \
  --reply "You are unsubscribed from MyBrand. Reply START to resume."
```

Sua regra substitui a resposta padrão de Bird para aquele país e **mantém as palavras-chave de Bird** a menos que você adicione mais. Ela também herda palavras-chave que Bird adicionar depois. Você não pode alterar a operação atribuída a uma palavra-chave de opt-out ou opt-in; Bird rejeita uma regra que tente vincular `STOP` a outra operação.

Onde Bird fornece as palavras-chave de um país em mais de um idioma, cada idioma tem sua própria regra, então a criação deve indicar o idioma que substitui. O Canadá é esse país hoje: suas regras `stop`, `start` e `help` vêm em `en` e `fr`. `language` é obrigatório lá e rejeitado para um país que Bird oferece em um único idioma.

```bash
bird sms keyword-rules create \
  --operation stop \
  --country CA \
  --language fr \
  --reply "Vous etes desabonne de MyBrand. Repondez DEBUT pour reprendre."
```

Listar as regras de um país mostra se a divisão se aplica e quais idiomas estão disponíveis.

Para restringir uma regra a um número em vez de todos os números que você possui no país, defina `number` em vez de depender apenas do país.

Se você responde a essas mensagens pelo seu próprio sistema em vez de usar Bird, defina `reply` como null junto com `confirmed_self_managed`. Isso desativa a resposta automática de Bird para a regra, enquanto a supressão em si continua funcionando.

## Palavras-chave de campanha

Regras `custom` não possuem comportamento embutido. Elas correspondem a palavras-chave que você escolhe e enviam a resposta que você escreve, o que suporta palavras-chave de campanha como `PIZZA`. Uma regra `custom` não herda palavras-chave, então precisa de pelo menos uma própria, e pode omitir `country` para se aplicar a todos os lugares para onde você envia.

Uma palavra-chave que Bird vinculou a uma operação de conformidade não pode ser reutilizada como personalizada.

## Leitura e gerenciamento de supressões

`GET /v1/sms/suppressions` lista os pares para os quais suas mensagens estão bloqueadas no momento, do mais recente primeiro. Filtre por `destination` para verificar um assinante antes de enviar para ele, por `originator` para um dos seus remetentes, ou por `reason`:

- `keyword_stop`: o assinante enviou uma palavra-chave de stop.
- `carrier_opted_out`: a operadora reportou o opt-out.
- `manual`: adicionado pela API ou pelo dashboard.

Supressões que já terminaram não são listadas, então a resposta identifica destinatários para os quais você não pode enviar mensagens no momento.

Você pode adicionar uma manualmente para honrar um opt-out que um cliente informou por telefone:

```bash
bird sms suppressions add --destination +15550001234 --originator +15557654321
```

Uma supressão manual bloqueia **todas as categorias, incluindo transacionais**, e a adição é idempotente. A remoção é deliberadamente restrita: apenas uma supressão `manual` pode ser encerrada dessa forma. A palavra-chave de stop do próprio assinante e o opt-out da operadora são recusados, porque não cabe a você revertê-los.

## Opt-out de todos os remetentes

Uma palavra-chave de stop e as supressões manuais acima param apenas um remetente. Alguns assinantes querem sair de todos os remetentes do espaço de trabalho de uma vez, por exemplo alguém que pede à sua equipe de suporte para interromper todas as mensagens em vez de responder a cada número individualmente.

Essa é uma preferência declarada e não uma supressão, então ela fica na aba **Preferences** de **SMS** > **Suppressions**, não na lista acima. Abra a aba e registre um opt-out com **Every sender in the workspace**: o número para de receber SMS de todos os remetentes do espaço de trabalho, incluindo remetentes adicionados depois. Um opt-out registrado nessa aba cobre todas as mensagens, incluindo textos de autenticação; para registrar um que interrompa apenas marketing, use a página **Contacts** > **Preferences** do espaço de trabalho, cujo diálogo oferece a escolha de cobertura.

Bird verifica as supressões deste guia primeiro, então um stop por palavra-chave simples ainda rejeita com `E12077` como antes. Um envio para um número com opt-out em nível de espaço de trabalho registrado é rejeitado com [`E25000 PreferenceRevoked`](/docs/api/errors/E25000). Para retomar o envio quando o assinante solicitar, remova a entrada da aba Preferences (você registrou, então pode remover), ou registre um opt-in na página **Contacts** > **Preferences** do espaço de trabalho.

## Próximos passos

Revise [consentimento de campanha e controles de envio](/products/sms/marketing/compliance) antes de um envio para audiência, ou explore o [tratamento de opt-out de SMS](/products/sms/compliance/opt-out) para sua integração.

- [Enviando SMS](/docs/guides/sms/sending-sms): revise categorias, remetentes e condições de rejeição.
- [Events](/docs/guides/sms/events): trate os eventos `sms.*` de envios e respostas.
- [SMS log](/docs/guides/sms/sms-log): inspecione uma mensagem, incluindo um envio rejeitado.

## Related resources

- [How do I collect SMS opt-ins?](/explained/sms/how-do-i-collect-sms-opt-ins) (answer)
- [Preview message segments](/tools/sms-segment-calculator) (tool)
- [SMS compliance](/sms-api/features/compliance) (product)
- [Operate messaging reliably](/learn/paths/reliability) (course)

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