Message events - Timely.ai

These events track the lifecycle of each message — from the moment a contact sends it to the read confirmation. Use them to sync conversation history, trigger content-based automations, or monitor delivery failures.

Event list

Event	When it fires
`message.received`	A message arrives from a contact on any channel
`message.sent`	The AI agent or human agent sends a message
`message.delivered`	The channel confirms the message was delivered to the device
`message.read`	The contact viewed the message (when the channel supports it)
`message.failed`	The send failed — channel unavailable, invalid number, etc.

`message.received`

When it fires

A new message from a contact arrives on any channel connected to the workspace. This includes text, image, audio, video, document, and location.

Payload

{
  "event": "message.received",
  "event_id": "evt_01HX4A1K9MFQR4YZDNV7P9WCE",
  "timestamp": "2026-04-19T14:30:00Z",
  "workspace_id": "ws_abc123",
  "data": {
    "message_id": "msg_01HX4A1K",
    "conversation_id": "conv_01HX3B2K",
    "contact_id": "cont_456",
    "channel_id": "chan_789",
    "channel_type": "whatsapp",
    "content": "Oi, gostaria de saber sobre os planos",
    "type": "text",
    "direction": "inbound",
    "media_url": null,
    "media_mime_type": null,
    "location": null,
    "received_at": "2026-04-19T14:30:00Z"
  }
}

Key fields

Field	Type	Description
`message_id`	string	Unique message ID
`conversation_id`	string	ID of the conversation the message belongs to
`contact_id`	string	ID of the sending contact
`content`	string \| null	Message text (null for media without a caption)
`type`	enum	`text`, `image`, `audio`, `video`, `document`, `location`, `sticker`
`direction`	enum	`inbound` (from the contact)
`media_url`	string \| null	Pre-signed media URL (expires in 24h)
`media_mime_type`	string \| null	File MIME type, e.g. `image/jpeg`
`location`	object \| null	`{ lat, lng, label }` when `type` is `location`

Usage example

Use message.received to integrate with your CRM, trigger external automations, or route messages to your own support system. If type is something other than text, check media_url to access the file.

`message.sent`

When it fires

The AI agent or a human agent sends a message to the contact — whether via inbox, API, or automation.

Payload

{
  "event": "message.sent",
  "event_id": "evt_01HX4B3M2PGTS6YADOV8Q1XDF",
  "timestamp": "2026-04-19T14:30:45Z",
  "workspace_id": "ws_abc123",
  "data": {
    "message_id": "msg_01HX4B3M",
    "conversation_id": "conv_01HX3B2K",
    "contact_id": "cont_456",
    "channel_id": "chan_789",
    "channel_type": "whatsapp",
    "content": "Olá! Temos três planos disponíveis...",
    "type": "text",
    "direction": "outbound",
    "sent_by": "agt_101",
    "sent_by_type": "agent",
    "media_url": null,
    "sent_at": "2026-04-19T14:30:45Z"
  }
}

Key fields

Field	Type	Description
`direction`	enum	Always `outbound`
`sent_by`	string	ID of who sent it (agent or attendant)
`sent_by_type`	enum	`agent` (AI) \| `attendant` (human) \| `api` \| `automation`
`sent_at`	string	ISO 8601 timestamp of sending

Usage example

Use sent_by_type to separate metrics for messages sent by AI vs. humans in your performance dashboard.

`message.delivered`

When it fires

The channel (WhatsApp, Instagram, etc.) confirms the message reached the contact’s device. Not all channels support delivery confirmation — widget and Telegram do not emit this event.

Payload

{
  "event": "message.delivered",
  "event_id": "evt_01HX4C5P4RHTW7ZBEPV9S2YEG",
  "timestamp": "2026-04-19T14:31:02Z",
  "workspace_id": "ws_abc123",
  "data": {
    "message_id": "msg_01HX4B3M",
    "conversation_id": "conv_01HX3B2K",
    "contact_id": "cont_456",
    "channel_id": "chan_789",
    "channel_type": "whatsapp",
    "delivered_at": "2026-04-19T14:31:02Z"
  }
}

Key fields

Field	Type	Description
`message_id`	string	ID of the message confirmed as delivered
`delivered_at`	string	ISO 8601 timestamp of the delivery confirmation

`message.read`

When it fires

The contact opened and viewed the message. Available only on channels that return read status — WhatsApp Business API and Instagram Direct.

Payload

{
  "event": "message.read",
  "event_id": "evt_01HX4D7Q5SJUW8ZCFQWA3ZFH",
  "timestamp": "2026-04-19T14:32:10Z",
  "workspace_id": "ws_abc123",
  "data": {
    "message_id": "msg_01HX4B3M",
    "conversation_id": "conv_01HX3B2K",
    "contact_id": "cont_456",
    "channel_id": "chan_789",
    "channel_type": "whatsapp",
    "read_at": "2026-04-19T14:32:10Z"
  }
}

Key fields

Field	Type	Description
`message_id`	string	ID of the viewed message
`read_at`	string	ISO 8601 timestamp of the read

The message.read event is generated at the individual message level. If the contact opens the conversation, you may receive several read events in sequence for previously unread messages.

`message.failed`

When it fires

Sending a message failed. This can happen due to a number not registered on WhatsApp, a disconnected channel, an expired Instagram session, or any other channel error.

Payload

{
  "event": "message.failed",
  "event_id": "evt_01HX4E9R6TKXV9ADGRXB4AGI",
  "timestamp": "2026-04-19T14:30:51Z",
  "workspace_id": "ws_abc123",
  "data": {
    "message_id": "msg_01HX4B3M",
    "conversation_id": "conv_01HX3B2K",
    "contact_id": "cont_456",
    "channel_id": "chan_789",
    "channel_type": "whatsapp",
    "error_code": "131026",
    "error_message": "Message undeliverable — number not registered on WhatsApp",
    "failed_at": "2026-04-19T14:30:51Z"
  }
}

Key fields

Field	Type	Description
`error_code`	string	Error code returned by the channel
`error_message`	string	Human-readable error description
`failed_at`	string	ISO 8601 timestamp of the failure

Usage example

Monitor message.failed with alerts. Many consecutive failures on the same channel_id indicate the channel may be disconnected — check the channel.error event in parallel.

​Event list

​message.received

​When it fires

​Payload

​Key fields

​Usage example

​message.sent

​When it fires

​Payload

​Key fields

​Usage example

​message.delivered

​When it fires

​Payload

​Key fields

​message.read

​When it fires

​Payload

​Key fields

​message.failed

​When it fires

​Payload

​Key fields

​Usage example

Event list

`message.received`

When it fires

Payload

Key fields

Usage example

`message.sent`

When it fires

Payload

Key fields

Usage example

`message.delivered`

When it fires

Payload

Key fields

`message.read`

When it fires

Payload

Key fields

`message.failed`

When it fires

Payload

Key fields

Usage example