# Mensagem que falhou

**Evento:** `message.failed` · **Transporte:** POST para o seu receptor

Só as falhas de envio da inbox: a mensagem não saiu (o canal recusou, a fila passou do prazo ou a campanha não conseguiu enviar). Serve para quem só quer saber dos problemas, sem receber entregas e leituras. A mesma falha também chega em `message.status` com `failed`. Assine `message.failed` num webhook (`POST /webhooks`).

`data.message` é a mensagem inteira, com `status: failed`, o `error` (código e motivo), o seu `track_source` e `track_id` e o `campaign_id`, para saber qual envio falhou; `data.chat`, a conversa. O envio direto (sem fila nem `options.async`) que falha volta na própria resposta, sem este evento.

**Estado:** Disponível

## Compatibilidade de canais

| Canal | Compatível | Observação |
|---|---|---|
| WhatsApp (Web) | Sim |  |
| WhatsApp (API oficial) | Sim |  |
| Instagram | Não | A falha do envio volta na resposta de `POST /messages`. |
| Messenger | Não | A falha do envio volta na resposta de `POST /messages`. |
| Telegram | Não | A falha do envio volta na resposta de `POST /messages`. |

### Fora da janela de 24 horas (API oficial)

```json
{
  "id": "evt_01JAB3M7Q2W8R4T6V9X0YZ1K2C",
  "type": "message.failed",
  "created_at": "2026-10-17T12:00:00.000Z",
  "inbox": {
    "id": "r0269625d29bfbd",
    "name": "loja",
    "phone": "5511888888888",
    "channel": "whatsapp_cloud"
  },
  "data": {
    "message": {
      "id": "3EB05DCE1D4036FCE241C6",
      "chat_id": "5511999999999@s.whatsapp.net",
      "author": {
        "id": "5511888888888@s.whatsapp.net",
        "name": "Loja"
      },
      "direction": "out",
      "sent_by": "api",
      "sent_at": "2026-10-17T12:00:00.000Z",
      "category": "unsent",
      "type": "text",
      "text": "Seu pedido saiu para entrega.",
      "track_source": "crm",
      "track_id": "42",
      "status": "failed",
      "error": {
        "error": "131047",
        "message": "Fora da janela de 24 horas: use um modelo (template)."
      }
    },
    "chat": {
      "id": "5511999999999@s.whatsapp.net",
      "lid": "123456789012345@lid",
      "type": "direct"
    }
  }
}
```

## Referências

- [Eventos e webhooks](/docs/webhook)
- [Contrato OpenAPI completo](/openapi-bundled.json)