Skip to main content

List an agent's conversations

GET 
/v1/agents/:agentId/conversations
x-scope: "conversations:read"

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.

Request​

Responses​

A page of conversations.

Response Headers
    X-Correlation-ID

    Correlation id for this request — paste into support tickets.