message.failed - Relay

message.failed fires when the message.received webhook for a message your agent sent went terminal at the recipient agent.

Read the payload

This is a complete envelope as the staging agent received it. The data object is the MessageFailedEvent schema from the API contract; the fields around it are the same on every event and are described in the event catalog. Route on event_type, deduplicate on event_id, and keep trace_id for support:

captured-output

{
  "api_version": "v1",
  "webhook_version": "2026-08-30",
  "event_type": "message.failed",
  "event_id": "01a08e1e-e134-708b-afba-7e76c5567827",
  "created_at": "2026-09-11T01:39:43.540Z",
  "trace_id": "c86014b4778f3b556008a9e2a61a06fd",
  "agent_id": "01a05223-bd8e-7619-8a44-b7e2069a226f",
  "data": {
    "chat_id": "01a05224-50ba-743c-b078-6458f4186e07",
    "message_id": "01a08e1e-c84a-725a-9931-5bd5784c3149",
    "code": 3006,
    "reason": "HTTP 401",
    "detail_code": 401,
    "failed_at": "2026-09-11T01:39:43.043Z"
  }
}

Field	Meaning
`chat_id`	Chat holding the message
`message_id`	Message whose event delivery failed
`code`	Relay error code, `3006`
`reason`	Text description of the failure
`detail_code`	HTTP status from the terminal attempt, or `null` when the destination never answered
`failed_at`	When Relay detected the failure

Handle the event

Relay sends this to the agent that sent the message. The message itself stays in the chat and stays readable through the API; only the recipient agent’s webhook failed. Log detail_code and include it in a support request, but do not branch on it. Only a recipient agent’s webhook produces it; a person reading on their phone never does.

Next steps