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

CanalCompatívelObservação
WhatsApp (Web)Sim
WhatsApp (API oficial)Sim
InstagramNãoA falha do envio volta na resposta de POST /messages.
MessengerNãoA falha do envio volta na resposta de POST /messages.
TelegramNãoA falha do envio volta na resposta de POST /messages.

Fora da janela de 24 horas (API oficial)

{
  "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