# Estado de mensagem (DLR) e payloads de webhook de entrada (MO)

> 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.

- URL canônico: https://www.broadnet.me/pt/reference/message-status-and-inbound-webhooks
- Idioma: pt
- Última atualização: 2026-07-19
- Editor: BroadNet (https://www.broadnet.me)

Os esquemas de payload dos dois callbacks de mensagens centrais: o evento de estado de entrega (DLR) com o seu message id, enum de estado, motivo de erro e timestamps, e o evento de mensagem de entrada (MO) — mais uma taxonomia de tipos de evento e como um DLR HTTP mapeia num recibo deliver_sm SMPP.

## 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.

*Corpo do webhook de estado de entrega (DLR)*

```json
{
  "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.

*Valores canónicos de estado de entrega*

| 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.

*Corpo do webhook de entrada (MO)*

```json
{
  "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.

*Tipos de evento de mensagens comuns*

| 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.

*Mapeamento de campos do relatório de entrega SMPP para DLR HTTP*

| 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.

## Fontes

- [IETF RFC 9110 — HTTP Semantics](https://datatracker.ietf.org/doc/html/rfc9110)
- [IETF RFC 8288 — Web Linking (Link header)](https://datatracker.ietf.org/doc/html/rfc8288)

## Relacionados

- [Entrega e fiabilidade de webhooks](https://www.broadnet.me/pt/reference/webhook-delivery-and-reliability)
- [Verificação de assinatura de webhook](https://www.broadnet.me/pt/reference/webhook-signature-verification)
- [Relatórios de entrega SMPP (DLR)](https://www.broadnet.me/pt/reference/smpp-delivery-receipts-dlr)
- [SMPP deliver_sm](https://www.broadnet.me/pt/reference/smpp-deliver-sm)
- [Guia de webhooks da BroadNet](https://www.broadnet.me/pt/developers/webhooks)