Fires when the platform or carrier gives up on delivering the message and the failure is not retryable under normal conditions.

​
Payload

{
  "id": "evt_xxxxx",
  "event": "message.failed",
  "timestamp": "2026-03-28T09:01:00Z",
  "data": {
    "message_id": "msg_a1b2c3d4",
    "agent_id": "ag_live_xxxx",
    "to": "+4917612345678",
    "status": "failed",
    "failed_at": "2026-03-28T09:01:30Z",
    "failure_reason": "UNKNOWN_RCS_USER"
  }
}
​
message_id
string
Outbound message identifier.
​
agent_id
string
RCS agent that sent the message.
​
to
string
Recipient phone number in E.164 format.
​
status
string
Always failed for this event.
​
failed_at
string
ISO 8601 time when the failure was finalized.
​
failure_reason
string
Machine-readable reason code. See the table below for common values.

​
Common failure_reason values

ValueMeaning
UNKNOWN_RCS_USERNumber is not RCS-capable
CARRIER_NOT_LAUNCHEDAgent not yet live on the recipient’s carrier
MESSAGE_EXPIREDTTL elapsed before delivery
REJECTED_SPAMCarrier or Google flagged the content
ACCOUNT_SUSPENDEDAgent or workspace suspended