Preferências
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, 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 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 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.

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

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:
for await (const preference of bird.preferences.list({
channel: "whatsapp",
handle: "+15550001234",
})) {
console.log(preference.status, preference.coverage, preference.sender_scope);
}for preference in client.preferences.list(channel="whatsapp", handle="+15550001234"):
print(preference.status, preference.coverage, preference.sender_scope)for pref, err := range client.Preferences.List(context.Background(), bird.PreferencesListParams{
Channel: bird.PreferenceChannelWhatsapp,
Handle: "+15550001234",
}) {
if err != nil {
log.Fatal(err)
}
fmt.Println(*pref.Status, *pref.Coverage)
}foreach ($bird->preferences->list(['channel' => 'whatsapp', 'handle' => '+15550001234']) as $preference) {
echo $preference->getStatus(), ' ', $preference->getCoverage(), PHP_EOL;
}bird preferences list --channel whatsapp --handle +15550001234curl "https://us1.platform.bird.com/v1/preferences?channel=whatsapp&handle=%2B15550001234" \
-H "Authorization: Bearer $BIRD_API_KEY"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:
const result = await bird.preferences.create({
channel: "whatsapp",
handle: "+15550001234",
status: "revoked",
coverage: "non_transactional",
});
console.log(result.applied, result.preference?.id);result = client.preferences.create(
channel="whatsapp",
handle="+15550001234",
status="revoked",
coverage="non_transactional",
)
print(result.applied, result.preference.id)result, err := client.Preferences.Create(context.Background(), bird.PreferencesCreateParams{
Channel: bird.PreferenceChannelWhatsapp,
Handle: "+15550001234",
Status: bird.PreferenceStatusRevoked,
Coverage: bird.PreferenceCoverageNonTransactional,
})
if err != nil {
log.Fatal(err)
}
// A newer statement already on file answers Applied false instead of an
// error, with the surviving statement in Preference.
if result.Applied != nil && *result.Applied {
fmt.Println("opt-out recorded")
}$result = $bird->preferences->create(
channel: 'whatsapp',
handle: '+15550001234',
status: 'revoked',
coverage: 'non_transactional',
);
echo var_export($result->getApplied(), true);bird preferences create \
--channel whatsapp \
--handle +15550001234 \
--status revoked \
--coverage non_transactionalcurl -X POST https://us1.platform.bird.com/v1/preferences \
-H "Authorization: Bearer $BIRD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"channel":"whatsapp","handle":"+15550001234","status":"revoked","coverage":"non_transactional"}'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: os endereços que seu espaço de trabalho bloqueia diretamente.
- Regras de palavras-chave: as palavras que registram uma preferência nos seus números.
- Eventos WhatsApp: o payload whatsapp.rejected que um envio bloqueado produz.
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