Eventos - D-API

Os webhooks de SMS notificam o status final de entrega de cada mensagem. Cada evento define o valor do campo status. Os exemplos abaixo usam o envelope do webhook de conta; o envelope por campanha carrega os mesmos campos no nível raiz.

Eventos e status resultante

Evento	Quando dispara	`status` resultante
`sms.delivered`	A mensagem foi entregue ao destinatário	`delivered`
`sms.undelivered`	A operadora reportou que a mensagem não foi entregue	`undelivered`
`sms.failed`	Falha de rede após o aceite — a mensagem já foi cobrada	`undelivered`
`sms.expired`	A mensagem expirou antes de ser entregue	`expired`

sms.failed mapeia para o status undelivered. Trata-se de uma falha de rede ocorrida após o aceite do envio: como a cobrança fecha no aceite, a mensagem já foi cobrada.

Campos de `data` (webhook de conta)

messageId

string

required

ID da mensagem. Permite correlacionar o evento com o envio original.

string

required

Número de destino em formato E.164.

status

string

required

Status resultante: delivered, undelivered ou expired.

errorCode

string | null

required

Código de erro normalizado em caso de falha, ou null quando não há erro. Veja a tabela de códigos de erro.

segments

number

required

Quantidade de segmentos (partes) do SMS.

timestamp

string

required

Momento do evento em ISO 8601 (UTC).

Exemplos por evento

sms.delivered — entregue

{
  "event": "sms.delivered",
  "channel": "sms",
  "data": {
    "messageId": "a1b2c3d4-...",
    "to": "+5511999999999",
    "status": "delivered",
    "errorCode": null,
    "segments": 1,
    "timestamp": "2026-01-24T23:00:00.000Z"
  },
  "timestamp": "2026-01-24T23:00:00.000Z"
}

sms.undelivered — não entregue

{
  "event": "sms.undelivered",
  "channel": "sms",
  "data": {
    "messageId": "a1b2c3d4-...",
    "to": "+5511999999999",
    "status": "undelivered",
    "errorCode": "INVALID_NUMBER",
    "segments": 1,
    "timestamp": "2026-01-24T23:00:00.000Z"
  },
  "timestamp": "2026-01-24T23:00:00.000Z"
}

sms.failed — falha de rede após o aceite

{
  "event": "sms.failed",
  "channel": "sms",
  "data": {
    "messageId": "a1b2c3d4-...",
    "to": "+5511999999999",
    "status": "undelivered",
    "errorCode": "NETWORK_ERROR",
    "segments": 1,
    "timestamp": "2026-01-24T23:00:00.000Z"
  },
  "timestamp": "2026-01-24T23:00:00.000Z"
}

sms.expired — expirou

{
  "event": "sms.expired",
  "channel": "sms",
  "data": {
    "messageId": "a1b2c3d4-...",
    "to": "+5511999999999",
    "status": "expired",
    "errorCode": null,
    "segments": 1,
    "timestamp": "2026-01-24T23:00:00.000Z"
  },
  "timestamp": "2026-01-24T23:00:00.000Z"
}

Códigos de erro

Quando há falha, o campo errorCode traz um valor normalizado. Os valores abaixo são os possíveis.

`errorCode`	Significado
`NETWORK_ERROR`	Erro de rede entre o gateway e a operadora
`INVALID_NUMBER`	Número de destino inválido
`LANDLINE`	Número de telefone fixo (não recebe SMS)
`BLACKLIST`	Número em lista de bloqueio (blacklist)
`CANCELED`	Envio cancelado
`NO_WHATSAPP`	Destino sem WhatsApp
`CONTENT_BLOCKED`	Conteúdo da mensagem bloqueado
`NO_COVERAGE`	Sem cobertura para o destino
`REJECTED`	Mensagem rejeitada pela operadora
`NOT_RECEIVED`	Mensagem não recebida pelo destino

Em eventos de sucesso (sms.delivered) ou expiração (sms.expired), o campo errorCode vem como null.

​Eventos e status resultante

​Campos de data (webhook de conta)

​Exemplos por evento

​Códigos de erro

Eventos e status resultante

Campos de `data` (webhook de conta)

Exemplos por evento

Códigos de erro