# Preferências de WhatsApp

Uma preferência é uma declaração sobre o que uma pessoa deseja, registrada no identificador dela em um canal. No WhatsApp, o identificador é um número de telefone no formato E.164. É um registro separado de uma [supressão](/docs/guides/whatsapp/opt-outs/suppressions), e ambos são verificados antes de um envio.

As preferências chegam ao seu espaço de trabalho de três formas: WhatsApp registra uma, um destinatário digita uma palavra-chave ou você mesmo registra uma. O que você pode fazer com cada uma depende de quem a declarou.

## O que uma preferência carrega

Uma declaração é `revoked`, um opt-out, ou `granted`, consentimento.

Ela também carrega uma cobertura, que define quanto tráfego ela bloqueia. `non_transactional` cobre mensagens de marketing e outras não essenciais, enquanto mensagens transacionais como recibos e códigos de verificação continuam sendo enviadas. `all` cobre todas as mensagens. A aba **Preferences** exibe esses valores na coluna **Covers** como **Non-transactional** e **All messages**.

Uma declaração pode restringir-se a um remetente com `sender_scope`, que no WhatsApp identifica a conta comercial. Sem ele, a declaração cobre o canal inteiro no seu espaço de trabalho, incluindo contas que você conectar depois.

Uma pessoa pode ter várias linhas em um canal, como um opt-out de canal inteiro ao lado de um com escopo de remetente. A declaração mais restritiva decide se a mensagem é enviada.

## Preferências que Bird registra para você

Quando Bird recebe um evento Meta indicando que um destinatário parou de receber mensagens de marketing, ele registra uma preferência de origem do destinatário para aquela conta comercial WhatsApp. A preferência cobre mensagens não transacionais. Ela não cria uma supressão de todas as mensagens nem exclui a pessoa de todas as contas no seu espaço de trabalho.

Um destinatário pode declarar a mesma coisa respondendo `STOP`. Essa preferência tem escopo da conta comercial para a qual ele enviou a mensagem, assim como a anterior. Ela cobre todas as mensagens, porque um `STOP` digitado é mais abrangente do que o opt-out de marketing do WhatsApp. Consulte as [regras de palavras-chave](/docs/guides/whatsapp/opt-outs/keyword-rules) para saber o que Bird reconhece e como alterar a resposta.

Um evento de retomada posterior atualiza a preferência daquela conta. Supressões e outras preferências aplicáveis ainda valem, então um evento de retomada sozinho não prova que o envio é elegível.

## Preferências que você registra

Abra a página [**Suppressions**](https://bird.com/dashboard/w/whatsapp/suppressions) e mude para a aba **Preferences**. Registrar uma com **Every business account in the workspace** impede o endereço de receber mensagens WhatsApp de todas as contas que você possui, incluindo contas que você conectar depois.

![Uma lista de assinantes que optaram por receber ou não, com a cobertura de cada declaração](/images/docs/dashboard-whatsapp-preferences.png)

O diálogo **Record opt-out** nessa aba registra cobertura de todas as mensagens.

![Uma caixa de diálogo para registrar um opt-out, com o escopo de todo o espaço de trabalho selecionado](/images/docs/dashboard-whatsapp-preference-new.png)

Para registrar uma que bloqueie apenas marketing, use a página **Contacts** > **Preferences** do espaço de trabalho, cujo diálogo oferece **Marketing messages** além de **All messages**.

## Lendo preferências via código

`GET /v1/preferences` retorna as preferências registradas do espaço de trabalho, começando pela criada mais recentemente. Passe `channel=whatsapp` para restringir a este canal e `handle` junto para consultar tudo registrado para um número antes de enviar mensagens:

**TypeScript**

```typescript
for await (const preference of bird.preferences.list({
  channel: "whatsapp",
  handle: "+15550001234",
})) {
  console.log(preference.status, preference.coverage, preference.sender_scope);
}
```

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

`handle` exige `channel`, já que o mesmo identificador pode existir em mais de um canal.

## Registrando uma preferência via código

`POST /v1/preferences` registra uma declaração. A escrita é um upsert com chave no canal, identificador e escopo de remetente, então uma nova declaração substitui a atual daquela chave:

**TypeScript**

```typescript
const result = await bird.preferences.create({
  channel: "whatsapp",
  handle: "+15550001234",
  status: "revoked",
  coverage: "non_transactional",
});
console.log(result.applied, result.preference?.id);
```

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

As declarações são ordenadas pelo momento em que foram feitas, não pelo momento em que chegam. API recusa uma declaração com data anterior à atual da chave e retorna `applied: false` com a declaração que sobreviveu. A recusa permanece no histórico da chave.

Um `201` significa que a chave não tinha registro e essa declaração criou um. Um `200` retorna o registro sobrevivente da chave, seja porque essa declaração o substituiu, repetiu ou foi recusada.

## O que você pode reverter

Uma que você registrou pode ser removida na aba **Preferences** ou com `DELETE /v1/preferences/{preference_id}` quando o destinatário pedir para retomar o envio.

Uma declaração feita pela própria pessoa cabe a ela reverter. Um cancelamento de inscrição ou uma palavra-chave de parada encerra quando a pessoa opta por voltar, e uma exclusão retorna `422`. Para retomar o envio de mensagens com o consentimento dela, registre uma declaração `granted` com `consented_at`, o momento em que ela consentiu. A concessão se aplica quando esse momento é posterior ao opt-out que ela reverte, de modo que registra a mudança de decisão em vez de apagar a declaração original.

Uma exclusão é ordenada como qualquer outra declaração, usando o momento em que é recebida. Se o registro contém uma declaração feita após esse momento, a exclusão é recusada e retornada com `applied: false` junto ao registro sobrevivente.

## Quando um erro de entrega chega primeiro

Um erro de entrega do provedor pode reportar uma parada antes de Bird ter registrado um evento correspondente. Preserve a escolha do destinatário e investigue o histórico de preferências e eventos em vez de tratar a ausência de um registro local como permissão para enviar.

## Próximos passos

- [Supressões](/docs/guides/whatsapp/opt-outs/suppressions): os endereços que seu espaço de trabalho bloqueia diretamente.
- [Regras de palavras-chave](/docs/guides/whatsapp/opt-outs/keyword-rules): as palavras que registram uma preferência nos seus números.
- [Eventos WhatsApp](/docs/guides/whatsapp/events): o payload `whatsapp.rejected` que um envio bloqueado produz.

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