agent.failed

EVENTOagent.faileddesde M5envelope v1

Atendente IA falhou.

Quando é emitido

Uma chamada do hook de agente falhou e nada foi enviado (falha fechada), ou a proteção contra loop pausou o chat. Motivos do agente externo: timeout, http_error, network_error, invalid_response, send_failed, loop_guard, internal. Do Atendente LiteZap: também not_configured, daily_cap (limite diário de chamadas atingido) e llm_error (o provedor falhou).

Campos de data

Campo	Tipo	Descrição
chat	string	Chat da mensagem.
message_id	string	Id LiteZap da mensagem (ausente no follow-up de ligação).
reason	string	Código estável do motivo.
error	string	Detalhe (opcional, sem chaves).

O envelope (id, type, version, instance_id, timestamp,data) está em Visão geral. Campos novos podem ser adicionados emdata sem mudar a versão: ignore os que não conhecer.

Exemplos

Corpo do POST

{
  "id": "evt_5f1c9a3e7d2b4086",
  "type": "agent.failed",
  "version": 1,
  "instance_id": "inst_7f3a9c2e5b1d4086",
  "timestamp": "2026-10-18T19:02:11.020Z",
  "data": {
    "chat": "5511999999999@s.whatsapp.net",
    "message_id": "msg_1a2b3c4d5e6f7a8b",
    "reason": "daily_cap",
    "error": "daily limit of 300 provider calls reached (daily_call_cap)"
  }
}

Entrega e ordem

• Por webhook: pelo menos uma vez, com retry por até 24 horas. O mesmo evento pode chegar duas vezes: deduplique porX-LiteZap-Event-Id. Veja Entrega e retentativas.
• A ordem entre eventos não é garantida (retentativas reordenam): use timestamp.
• Por SSE: ao vivo, sem replay. Veja Tempo real com SSE.
• Para assinar só este tipo: "events": ["agent.failed"] no webhook, ou?types=agent.failed no SSE.

Relacionados: agent.handoff

Equivalente na Z-API: (sem equivalente).