DLR (Delivery Receipt) é o recibo que a operadora devolve informando o destino final de um SMS. Ele é assíncrono: chega segundos ou minutos depois do envio, e é ele que distingue uma mensagem aceita para envio de uma mensagem efetivamente entregue no celular.
DLR (Delivery Receipt) é o recibo que a operadora devolve informando o destino final de um SMS. Ele é assíncrono: chega segundos ou minutos depois do envio, e é ele que distingue uma mensagem aceita para envio de uma mensagem efetivamente entregue no celular.
Um SMS passa por estados até chegar a um desfecho. Na fila: aceito pela plataforma, ainda não despachado. Agendada: vai sair na data marcada. Enviado: aceito pela operadora, aguardando o recibo — este é o ponto em que a maioria das integrações erra, porque "enviado" ainda não é "entregue". Entregue: confirmado no aparelho, e é o único desfecho de sucesso.
Entre a aceitação pela operadora e a chegada no aparelho pode haver aparelho desligado, fora de área, número inexistente, bloqueio ou expiração da janela de retentativa. Se o seu fluxo depende de confirmação — um OTP, por exemplo — trate apenas "Entregue" como sucesso e escute o webhook, em vez de assumir entrega no retorno da chamada de envio.
Erro Envio e Erro Entrega: a operadora rejeitou no despacho ou não conseguiu concluir. Inválida: o número não existe ou está mal formatado. Bloqueada: o destino recusa mensagens daquele tipo. Não Entregue e Expirada: a operadora tentou e desistiu dentro da janela. Blacklist: o destinatário pediu opt-out e a plataforma barrou antes de gastar crédito. Sem Crédito: faltou saldo no momento do despacho. Recência e Recência Mensal: o número recebeu mensagens recentes demais e entrou em bloqueio de frequência. Cancelada: o envio falhou e o crédito já foi devolvido ao saldo.
Configure uma URL de webhook na conta e você passa a receber o evento sms.status a cada mudança de estado, além de sms.reply quando o destinatário responde. Cada requisição vem assinada com HMAC-SHA256 no cabeçalho X-SMSGo-Signature, então confira a assinatura antes de confiar no corpo. Também é possível consultar sob demanda em GET /v1/sms/{id}/numbers, que devolve o status por número, paginado.
Normalmente segundos. Mas o DLR é assíncrono e depende da operadora: aparelho desligado ou fora de área pode atrasar minutos, e a operadora continua tentando até a janela expirar.
Falha do provedor gera estorno, e o envio fica com o status Cancelada — que é justamente o marcador de que o crédito voltou para o saldo. Já uma mensagem barrada por blacklist não chega a ser despachada.
O status Inválida indica número inexistente ou mal formatado. Vale limpar a base a partir desses retornos: reenviar para número inválido só repete o custo.
Não, e é melhor não fazer isso. Configure o webhook e receba a mudança quando ela acontece. A consulta por GET serve para reconciliação, não para acompanhamento em tempo real.
Sem cartão de crédito. Sem mensalidade. Créditos não expiram.
Criar conta grátis