Dois payloads de webhook transportam eventos de mensagens. Um evento de estado de entrega (DLR) reporta o desfecho de uma mensagem — message_id, um enum de estado (accepted, delivered, undelivered, expired, rejected), um motivo de erro e timestamps. Um evento de entrada (MO) reporta uma mensagem que um subscritor lhe enviou. Ambos são os equivalentes HTTP dos recibos deliver_sm SMPP e das mensagens mobile-originated.
- A sua aplicaçãoEnvia via REST API ou SMPP
- Plataforma BroadNetValida, encaminha e fatura cada mensagem
- SMSC da operadoraConexão direta com a operadora
- Dispositivo do assinanteA mensagem é entregue
Duas famílias de eventos: estado e entrada
Uma plataforma de mensagens emite dois callbacks fundamentalmente diferentes. Um evento de estado de entrega (DLR, delivery receipt) é o seguimento assíncrono de uma mensagem que enviou: diz-lhe o que finalmente lhe aconteceu na rede do operador. Um evento de entrada (MO, mobile-originated) é não solicitado — uma mensagem que um subscritor enviou para um dos seus números ou uma resposta a uma campanha. Partilham o transporte de webhook e a assinatura, mas os seus esquemas e o seu significado diferem, pelo que um consumidor robusto ramifica com base num discriminador de tipo de evento antes de fazer parse do resto. Ambos são a expressão na camada HTTP daquilo que o SMPP entrega como PDUs deliver_sm: uma flag de recibo distingue um DLR de um MO no fio, e a mesma distinção é um campo de evento explícito sobre HTTP.
Payload de estado de entrega (DLR)
Um payload de estado de entrega correlaciona-se com o envio original pelo message_id atribuído pelo servidor e reporta um estado retirado de uma pequena enumeração, mais o motivo e os timestamps que lhe permitem medir latência e reconciliar a faturação. O enum de estado é o coração disto: distingue um estado intermédio accepted/enroute dos estados terminais e separa um delivered positivo das várias formas como uma mensagem pode falhar. Os estados negativos terminais trazem um código de erro e um motivo legível para que um consumidor possa decidir se o destino está permanentemente mau (suprimi-lo) ou se a falha foi transitória (seguro reenviar). Os timestamps incluem normalmente quando a plataforma aceitou a mensagem e quando ocorreu o estado terminal.
{
"event": "message.delivered",
"message_id": "01HZY8Q3M6",
"to": "+15551234567",
"status": "delivered",
"error": null,
"reason": null,
"submitted_at": "2026-07-19T09:15:22Z",
"done_at": "2026-07-19T09:15:25Z",
"sequence": 3
}A enumeração de estado de entrega
Normalizar os valores de estado é o que permite a um consumidor tratar todos os operadores, porque as respostas de rede em bruto variam enormemente. Um enum canónico mapeia-as para um punhado de estados com semântica clara: se o estado é terminal e se é um sucesso. Os estados intermédios (accepted, enroute) podem ser substituídos por um evento posterior para o mesmo message id, que é exatamente a razão pela qual os payloads trazem uma sequência ou um timestamp e pela qual os consumidores aplicam a regra de auto-ordenação da fiabilidade de webhooks — um accepted tardio nunca deve sobrepor-se a um delivered anterior.
| status | Terminal | Significado |
|---|---|---|
| accepted | No | A plataforma aceitou a mensagem para entrega |
| enroute | No | Entregue à operadora, aguardando relatório de entrega |
| delivered | Sim | Entrega ao aparelho confirmada |
| undelivered | Sim | A operadora não conseguiu entregar (ver erro/motivo) |
| expired | Sim | Prazo de validade expirado antes da entrega |
| rejected | Sim | Recusado (número inválido, remetente bloqueado, filtro de spam) |
| unknown | Sim | A operadora não devolveu um estado final definitivo |
Payload de mensagem de entrada (MO)
Um evento de entrada transporta o conteúdo da mensagem mais o encaminhamento necessário para responder e para correlacionar uma conversa. Os campos críticos são from (o MSISDN do subscritor em E.164), to (o número ou short/long code para o qual mensagearam) e o text; a par deles, um message id para a própria mensagem de entrada, um timestamp de receção e — porque o SMS de entrada está sujeito às mesmas regras de codificação e segmentação que o de saída — o encoding e, para uma mensagem multipart, a referência de concatenação e os índices das partes, para que o consumidor possa remontar o texto completo. Os eventos de entrada são o que aciona campanhas por palavra-chave, conversas bidirecionais e fluxos de conformidade STOP/HELP.
{
"event": "message.inbound",
"message_id": "01HZY8R7T0",
"from": "+15551234567",
"to": "44160",
"text": "STOP",
"encoding": "GSM7",
"received_at": "2026-07-19T09:20:11Z",
"concat": { "ref": null, "part": 1, "total": 1 }
}Taxonomia de tipos de evento
Além de DLR e MO, uma plataforma emite eventos de ciclo de vida e de conta, e um esquema de nomenclatura consistente — uma string pontuada resource.action — permite a um consumidor subscrevê-los e encaminhá-los de forma limpa. Os eventos de estado de entrega são variações de message.<status>; o evento de entrada é message.inbound. Agrupar pelo prefixo do recurso significa que um consumidor pode fazer match de message.* para tudo o que diga respeito a uma mensagem e reservar outros prefixos para eventos de conta ou de número. Todos os eventos devem ainda trazer um event id estável (usado como nonce da assinatura e como chave de desduplicação) e a string de tipo, para que o discriminador e a chave de idempotência estejam sempre presentes.
| Tipo de evento | Família | Disparado quando |
|---|---|---|
| message.accepted | Status (DLR) | Mensagem aceita para entrega |
| message.delivered | Status (DLR) | Entrega ao aparelho confirmada |
| message.undelivered | Status (DLR) | A operadora não conseguiu entregar |
| message.expired | Status (DLR) | Período de validade expirado |
| message.rejected | Status (DLR) | Mensagem recusada a montante |
| message.inbound | Entrada (MO) | Um assinante lhe enviou uma mensagem |
Mapear DLR HTTP para deliver_sm SMPP
O callback de estado de entrega HTTP e o delivery receipt SMPP são a mesma informação em duas codificações, e uma plataforma que faz a ponte entre REST e SMPP traduz entre eles. No SMPP um recibo chega como uma PDU deliver_sm cujo esm_class o marca como recibo; o seu campo short-message transporta um recibo em texto com os campos id, stat e err, e a TLV message_state transporta o estado numérico. O DLR HTTP eleva-os para JSON: o token stat do SMPP mapeia para o enum de estado canónico, o valor err mapeia para o campo error, e os tempos submit/done do recibo mapeiam para submitted_at/done_at. Compreender este mapeamento é o que permite a um único caminho de código de tratamento de entrega servir ambos os transportes; o formato do recibo SMPP e a PDU deliver_sm estão documentados em detalhe na referência de SMPP.
| Campo do recibo SMPP | Campo DLR de HTTP | Nota |
|---|---|---|
| id (recibo) | message_id | Correlaciona-se ao submit_sm / POST original |
| stat (DELIVRD/UNDELIV/EXPIRED/REJECTD) | status | O token mapeia para o enum canónico |
| err | error | Código de erro da operadora/rede |
| message_state TLV | status (valor numérico subjacente) | Estado numérico SMPP por trás do token |
| data de envio / data de conclusão | submitted_at / done_at | Carimbos de data/hora de latência e reconciliação |
Perguntas frequentes
O que está num payload de webhook de estado de entrega (DLR)?
O message_id atribuído pelo servidor que o correlaciona com o seu envio, um estado retirado de um enum canónico (accepted, enroute, delivered, undelivered, expired, rejected, unknown), um código de erro e um motivo legível para as falhas, e timestamps de quando a mensagem foi submetida e de quando ocorreu o estado terminal.
Como é que um evento de entrada (MO) difere de um DLR?
Um DLR é o resultado assíncrono de uma mensagem que enviou. Um evento de entrada (MO) é não solicitado — uma mensagem que um subscritor enviou para o seu número ou uma resposta a uma campanha — trazendo from, to, o text, o encoding e, para mensagens multipart, campos de concatenação. Partilham transporte e assinatura, mas têm esquemas diferentes, pelo que os consumidores ramificam primeiro pelo tipo de evento.
Porquê normalizar o enum de estado de entrega?
Porque as respostas em bruto dos operadores variam enormemente. Mapeá-las para um pequeno enum canónico com semântica clara de terminal-e-sucesso permite a um consumidor tratar todos os operadores de forma uniforme, e permite-lhe decidir só pelo estado se deve suprimir um destino mau, reenviar uma falha transitória ou registar uma entrega confirmada.
Como impeço que um 'accepted' tardio sobreponha um 'delivered' anterior?
Use os campos de auto-ordenação. Os payloads de DLR trazem um timestamp e muitas vezes um número de sequência; o consumidor compara-os com o último estado que registou para esse message id e descarta qualquer evento mais antigo do que aquilo que já tem, para que um estado intermédio fora de ordem nunca atropele um terminal.
Como é que um DLR HTTP mapeia num recibo deliver_sm SMPP?
Transportam a mesma informação. No SMPP o recibo é uma PDU deliver_sm marcada no esm_class, com os campos id, stat e err e uma TLV message_state. O DLR HTTP mapeia stat para o enum de estado, err para error, e os timestamps do recibo para submitted_at/done_at — para que um único caminho de tratamento de entrega sirva ambos os transportes.
Que campos me permitem remontar um SMS de entrada multipart?
Os campos de concatenação: uma referência que liga as partes entre si, o índice da parte e a contagem total. Como o SMS de entrada obedece às mesmas regras de codificação e segmentação que o de saída, uma mensagem de entrada longa chega como vários eventos MO que o consumidor costura por ordem usando esses campos.
Especificações de origem
Os padrões publicados nos quais esta página se baseia. Abre num novo separador.