Sua solicitação de envio pode ter sucesso antes de o telefone do destinatário receber qualquer coisa. Um relatório posterior da operadora fornece outro resultado, que sua aplicação precisa tratar separadamente da aceitação da solicitação.
O que um aviso de entrega me diz?
Um aviso reporta sucesso de entrega ou um problema de entrega do ponto de vista da rede.
Um resultado de entrega SMS pode chegar enquanto o telefone permanece não lido dentro de uma gaveta. Ele não prova que o destinatário viu a identidade do remetente. Também não comprova que ele leu o texto completo.
A rede envia avisos separadamente da sua resposta a uma solicitação de envio. Ela também pode suprimir alguns relatórios. A referência de avisos SMPP documenta esses controles para conexões com operadoras.
Quais avisos de operadora o Bird expõe?
Você recebe eventos públicos para resultados de entrega reconhecidos. Avisos em buffer permanecem internos.
Um aviso em buffer indica que a operadora está retendo a mensagem. Bird registra isso no log de eventos interno sem alterar o status público da mensagem. Você não vê atualização na timeline pública nem nos seus webhooks.
| Status do aviso da operadora | Evento Bird |
|---|---|
delivered | sms.delivered |
expired | sms.expired |
rejected | sms.rejected |
delivery_failed com motivo recuperável | sms.undelivered |
delivery_failed com motivo permanente ou não mapeado | sms.failed |
buffered | Sem evento público |
Um status de operadora não reconhecido não produz evento. Uma atualização pública ausente, portanto, não comprova que a operadora não enviou um aviso.
Por que um mesmo status de falha produz eventos diferentes?
Bird usa o motivo de falha da operadora para decidir se o problema subjacente pode ser resolvido.
| Motivo da operadora | Código de erro Bird | Classificação |
|---|---|---|
unavailable_subscriber | unreachable | Recuperável |
received_network_error | provider_unavailable | Recuperável |
capacity_limit_reached | provider_unavailable | Recuperável |
unknown_subscriber | invalid_destination | Permanente |
opted_out | recipient_opted_out | Permanente |
carrier_rejected | sender_unregistered, content_rejected ou blocked_by_carrier | Permanente |
Uma falha recuperável produz sms.undelivered. A mensagem ainda é final: Bird não faz nova tentativa automaticamente. Alcançar o destinatário exige outro envio após o problema subjacente ser resolvido.
Uma falha permanente produz sms.failed.
SMS pumping é uma fraude que faz o seu produto enviar mensagens pagas para números controlados por um atacante. Bird reporta blocked_by_fraud_protection quando a proteção contra fraude bloqueia pumping suspeito.
Um motivo não mapeado produz sms.failed com o código de erro unknown. Esse resultado significa que Bird não conseguiu classificar o motivo da operadora. Isso não prova, por si só, que o destino é permanentemente inalcançável.
Posso definir quando a operadora para de tentar?
Você pode definir um prazo de entrega com validity_period, de 60 a 172.800 segundos (dois dias), contados a partir do momento em que Bird aceita a mensagem.
Bird não repassa a mensagem à operadora depois desse prazo. Quando a rota oferece suporte, Bird informa o tempo restante à operadora como o período de validade da mensagem. Um código de verificação válido por dez minutos pode defini-lo como 600, de modo que um texto que não chegou à operadora em dez minutos não é enviado.
Uma mensagem que perde o prazo antes de chegar à operadora termina como rejected ou failed. Bird produz sms.expired somente quando uma operadora reporta expiração.
Omita o campo para usar o período de validade do perfil de mensagens em messaging_profile_id, ou as regras da própria operadora quando nenhum dos dois define um. A resposta da mensagem informa o validity_period que foi aplicado.
Como devo tratar avisos na minha aplicação?
Você deve rastrear resultados de entrega separadamente da aceitação da solicitação e de qualquer ação que o destinatário tome.
Trate uma mensagem sem resultado final de entrega como pendente. Leia o código de erro junto com um evento de falha para investigar a causa. Preserve códigos desconhecidos nos seus logs porque o conjunto de códigos de erro é extensível.
Use eventos de entrega para uma métrica de entrega. Para um fluxo de código de verificação ou confirmação, registre sucesso quando o destinatário completar a ação. Um aviso de entrega sozinho não pode fornecer essa medição.
Eventos SMS documenta os payloads de eventos públicos e a timeline da mensagem.
Em resumo
Entrega não comprova leitura.
Um aviso reporta o resultado de entrega da rede sem confirmar que uma pessoa viu o texto.
Alguns avisos não geram evento público.
Bird registra avisos em buffer internamente sem alterar o status público, a timeline ou o fluxo de webhooks.
O motivo determina o evento de falha.
Motivos recuperáveis da operadora produzem sms.undelivered; motivos permanentes ou não mapeados produzem sms.failed.
Um motivo recuperável não dispara outro envio.
Uma mensagem não entregue é final, então outra tentativa exige um envio separado.