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:

Reconhece a mensagem comparando-a com o catálogo de palavras-chave do país daquele número.
Registra uma supressão naquele par exato de remetente e assinante.
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 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 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:

Exemplo de código

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:

Exemplo de código

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.

Exemplo de código

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:

Exemplo de código

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. 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 antes de um envio para audiência, ou explore o tratamento de opt-out de SMS para sua integração.

Enviando SMS: revise categorias, remetentes e condições de rejeição.
Events: trate os eventos sms.* de envios e respostas.
SMS log: inspecione uma mensagem, incluindo um envio rejeitado.

Recursos relacionados

Continue com a documentação, guias e exemplos sobre este tópico. Os recursos estão em inglês.

Entenda o conceitoHow do I collect SMS opt-ins?Use a ferramentaPreview message segments Explore a funcionalidadeSMS compliance Siga o percurso de aprendizagemOperate messaging reliably

Obtenha um resumo de implementação