List an agent's conversations
list_conversationsList an agent's conversations
The agent's conversations, the most recently active first (pinning is a dashboard view
and doesn't change the order). Each one carries its last message, who wrote it and when,
whether the team has read it, its attention flags, the AI's state and its assignee, so you
can tell which ones have new messages without reading them: poll with active_since
set a few minutes before the newest last_message_at you have seen (messages sent from
the WhatsApp or Meta apps carry the platform's earlier time), page while has_more, and
drop messages you already have by id. active_since follows last_message_at only: a
change of status, read state, flags or assignee doesn't bring a conversation back, and
neither does a customer's photo, voice note, sticker or file sent without a caption until
a later message, such as the AI's answer, moves last_message_at. A conversation with no
message yet (such as a website chat the visitor opened but hasn't written in) isn't
listed; getConversation reads it.
search matches the customer's name or the last message only; nothing searches inside
message history. Deleted conversations never appear. Filtered by status, channel,
is_read, urgent or assigned_to without active_since (and without contact_id), the
list covers the last 90 days of activity before active_before or now; send active_since
to reach further back.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Page size, 1 to 100 (values outside are clamped). Default 20. | |
| cursor | No | Opaque cursor from the previous page's `next_cursor`. Omit for the first page. A cursor the API didn't return is `422 invalid_request`. | |
| search | No | Part of the customer's name or of the last message, 3 to 128 characters, without `, ( ) " * %` or a backslash. | |
| status | No | ||
| urgent | No | The `urgent` flag exactly. The dashboard's "Needs Attention" filter also counts an unhappy `sentiment`. | |
| channel | No | One channel, or several comma-separated, case-insensitive: the values of a conversation's `channel`. | |
| is_read | No | ||
| agent_id | Yes | The agent the resource belongs to. Another company's agent, or the nil UUID, is `404 agent_not_found`; an agent outside the key's agent list is `403 agent_not_authorized`. | |
| contact_id | No | ||
| assigned_to | No | A teammate's `user_id`, or `unassigned`. Not `me`: a key isn't a person. | |
| active_since | No | Only conversations whose last message is at or after this instant (ISO 8601 with an offset, such as `2026-10-15T09:00:00Z`). Sending it also lifts the 90-day window of a filtered list. | |
| active_before | No | Only conversations whose last message is before this instant. |