Uma mensagem SMS aceita ainda pode falhar por causa de um número inválido, um aparelho inacessível ou um problema de rede. O registro da mensagem, o evento de entrega e o erro retornado ajudam a distinguir esses resultados de uma filtragem.
Como investigo uma suspeita de filtragem?
Você compara o registro da mensagem com seus eventos de SMS. O evento descreve o resultado; o erro e os detalhes do provedor ajudam a explicá-lo.
| Evento | O que o evento informa |
|---|---|
sms.rejected | O processamento ou um provedor downstream recusou a mensagem aceita. |
sms.failed | Uma falha permanente foi reportada. |
sms.undelivered | Uma falha recuperável foi reportada, como um assinante inacessível ou problema de rede. |
sms.expired | O provedor reportou expiração. |
Nenhum evento isolado prova filtragem. No mapeamento de recibos de entrega de Bird, uma razão do provedor carrier_rejected se torna content_rejected. Uma razão não mapeada se torna unknown, que precisa de investigação e pode ter uma causa não relacionada. O status de um recibo determina o evento separadamente da razão, então uma rejeição de operadora pode acompanhar diferentes eventos de falha.
O catálogo de erros define blocked_by_carrier e sender_unregistered. A ausência deles não descarta filtragem: a Bird converte carrier_rejected em content_rejected e motivos não mapeados em unknown. Confira o código efetivamente retornado, preserve valores desconhecidos e mantenha os detalhes do provedor.
Quais detalhes devo salvar?
Mantenha o ID da mensagem, o remetente, o destino, o horário de envio, o tipo de evento, o error.code normalizado, a descrição e carrier_error_code. Agrupe falhas por destino, remetente e tipo de mensagem; uma falha isolada fornece menos evidência do que uma mudança que afeta um grupo consistente de envios.
O código normalizado é o campo estável para o tratamento da sua aplicação. A descrição é texto diagnóstico, então não a interprete como um contrato fixo. carrier_error_code contém o código mais detalhado do provedor de envio quando fornecido; não é garantido que seja o código da própria operadora móvel. Pode estar vazio quando o provedor não fornece nenhum ou quando uma falha ocorre antes do repasse ao provedor.
Por exemplo, content_rejected aponta para a rejeição reportada, invalid_destination para o número do destinatário e provider_unavailable para o resultado de rede ou capacidade. unknown deixa a causa sem resolução. Compartilhe o ID da mensagem e o código do provedor disponível com o suporte quando esses detalhes não explicarem a falha.
Registrar meu remetente evita a filtragem?
O registro satisfaz o programa de remetente aplicável; não garante a entrega. O remetente também precisa ser elegível para o destino, e a mensagem e o tráfego devem atender aos requisitos relevantes.
Para mensagens A2P nos EUA com números locais, verifique o registro 10DLC completo: marca, campanha e vinculação de número. Uma marca ou campanha aprovada não vincula automaticamente todos os números que você possui. Programas de toll-free e short code têm requisitos diferentes. Outros destinos podem exigir registro de nome de remetente.
Use os destinos de SMS para planejar a escolha de remetente e depois confirme os requisitos aplicáveis e o estado de registro do seu espaço de trabalho antes do lançamento. Um guia de país é um resumo de referência, não uma evidência de que seu remetente está aprovado.
O que devo fazer com uma falha de opt-out?
Preserve a preferência. Um envio para um par remetente-destinatário suprimido por Bird é recusado no API com E12077; essa recusa não cria mensagem nem evento de mensagem. Um relatório downstream de recipient_opted_out é diferente: é um resultado para uma mensagem aceita e faz Bird registrar uma supressão para o par.
As palavras-chave de cancelamento aceitas podem criar bloqueios por par remetente-destinatário. Esses eventos não representam todas as preferências do espaço de trabalho nem todas as solicitações recebidas pelo atendimento ao cliente. Inclua essas preferências mais amplas na seleção do público. Não troque de remetente para contornar um cancelamento.
O que devo verificar antes de tentar novamente?
- Prontidão do remetente. Confirme o tipo de remetente, o registro e o acesso ao destino necessários para esse tráfego.
- Permissão e relevância. Confirme que a pessoa concordou com essa finalidade e não retirou essa permissão.
- Conteúdo e links. Identifique o negócio claramente, use links apropriados e revise os requisitos de conteúdo do destino. Alterar apenas um link não estabelece elegibilidade de entrega.
- Tráfego e timing. Compare os envios com falha com seu padrão normal, enfileiramento e os limites da rota. Reenviar repetidamente o mesmo conteúdo rejeitado pode gerar custo sem corrigir a causa.
- A falha reportada. Investigue recusas permanentes antes de enviar novamente. Para uma resposta API ambígua, reutilize a chave de idempotência original dentro da janela de replay; não transforme incerteza em uma segunda solicitação automaticamente.
O roteamento de SMS aplica controles de destino antes da transferência à operadora. Uma integração de SMS acompanha cada solicitação aceita pelo registro da mensagem e pelos eventos de entrega.
Em resumo
Uma entrega com falha é um ponto de partida para investigação.
O evento, o erro normalizado e os detalhes do provedor descrevem a falha. Uma causa desconhecida não comprova filtragem pela operadora.
O registro é um requisito, não uma garantia de entrega.
Verifique o remetente, o destino, o conteúdo, a permissão e o padrão de tráfego antes de decidir o que alterar.
Um opt-out é uma preferência a ser preservada.
Distinga uma recusa de API para um par suprimido de um relatório de opt-out downstream, e respeite o escopo completo da solicitação da pessoa.
Mantenha a evidência junto com a mensagem.
Salve o ID da mensagem, o destino, o remetente, o horário, o evento e os detalhes do erro para que você possa investigar um padrão ou abrir um caso de suporte útil.