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 | content_rejected | 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. Um motivo não mapeado também produz esse evento com o código de erro unknown. Esse resultado significa que Bird não conseguiu classificar o motivo da operadora. Ele não prova de forma independente que o destino é permanentemente inalcançável.
Posso definir quando a operadora para de tentar?
Você não pode definir o prazo de entrega da operadora pelo endpoint de envio do Bird.
Bird rejeita qualquer validity_period fornecido com HTTP 422 SMSUnsupportedFeature. Esse campo controlaria por quanto tempo a operadora continua tentando entregar o texto.
O campo de resposta correspondente não é retornado. Bird produz sms.expired quando uma operadora reporta expiração. Sua aplicação não pode inferir o período de espera da operadora a partir de um campo ausente.
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.