List conversations with filtering and pagination

get

https://api.customerly.io/v2/conversations

Retrieves conversations from your workspace with powerful filtering capabilities. You can filter by:

Assignment: specific teammate (account_id) or team (team_id)
Status: opened, closed, snoozed, or spam
AI status: conversations handled by Aura AI assistant (assumed_resolved, confirmed_resolved, escalated, etc.)
Priority tags: None, In Progress, Waiting, Priority
Time range: filter by creation date using Unix timestamps
Search: find conversations by contact name/email or message content

Results are paginated using cursor-based pagination. Use the returned cursor value
in subsequent requests to fetch the next page.

Response field values

tag - Priority tag assigned to the conversation:

none: No tag assigned
in_progress: Being actively worked on
waiting: Waiting for customer response or external action
priority: High priority, requires immediate attention

origin_channel - Channel where the conversation started:

in_app: Live chat widget on your website/app
email: Email integration
facebook: Facebook Messenger
whatsapp: WhatsApp Business

initiated_by - Who started the conversation:

contact: Contact initiated the conversation
account: Teammate started the conversation
campaign: Triggered by a marketing campaign
workflow: Triggered by an automation workflow

managed_by - How the conversation is being handled:

none: No handler assigned yet
full_human: Handled entirely by human agents
full_ai: Handled entirely by Aura AI assistant
mixed_human_ai: Combination of AI and human handling

assigner.type - Type of assignment:

account: Assigned to a specific teammate
team: Assigned to a team inbox

last_message.sender_type - Type of sender for the last message:

account: Message sent by a teammate
contact: Message sent by the contact

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Query Params

account_id

integer

The account id

ai_status

string

enum

The AI status of a conversation:
ai_involved: AI has participated in the conversation
ai_not_involved: AI has not participated
confirmed_resolved: Contact confirmed the AI resolved their issue
assumed_resolved: AI assumed the issue was resolved (no contact feedback)
escalated: Conversation was escalated to a human agent

Allowed:

chatflow_id

integer

The chatflow id

created_at_end_time

integer

The end time for searching when conversation was created (Unix timestamp in the timezone specified by timezone). Filter has hour-level granularity: the timestamp is floored to the start of its hour.

created_at_start_time

integer

The start time for searching when conversation was created (Unix timestamp in the timezone specified by timezone). Filter has hour-level granularity: the timestamp is floored to the start of its hour.

cursor

integer

The cursor used for pagination

escalated_at_end_time

integer

The end time for searching when conversation was escalated (Unix timestamp in the timezone specified by timezone). Filter has hour-level granularity: the timestamp is ceiled to the end of its hour. Requires escalation_type.

escalated_at_start_time

integer

The start time for searching when conversation was escalated (Unix timestamp in the timezone specified by timezone). Filter has hour-level granularity: the timestamp is floored to the start of its hour. Requires escalation_type.

escalation_type

string

enum

The AI escalation type:
low_confidence: AI had low confidence in its answer
missing_information: AI lacked required information
human_requested: Contact explicitly requested a human
outside_mission: Request was outside AI scope
exception: An error occurred during AI processing

has_mentioned

boolean

If the current account is mentioned in the conversation

has_scheduled_message

boolean

If the conversation has a scheduled message by current account

keyword

string

Search keyword

per_page

integer

Defaults to 15

The number of element per page

search_type

string

enum

Search keyword in:
contacts: Search in contacts' name/email
messages: Search in conversations' messages

Allowed:

order

string

enum

Defaults to newest_first

The order direction of the conversations:
newest_first: Most recent conversations first (default)
oldest_first: Oldest conversations first

Allowed:

status

string

enum

The status of a conversation:
opened: Active conversations requiring attention
snoozed: Temporarily paused conversations
closed: Resolved/archived conversations

Allowed:

tag

string

enum

The tag attributed to a conversation:
none: No tag
in_progress: In Progress
waiting: Waiting
priority: Priority

Allowed:

team_id

integer

The team id

timezone

string

The contact browser timezone

topic_id

integer

The topic id

segment_id

integer

The conversation segment id

polymorphic_contact_id

string

Contact identifier. Can be: numeric ID (e.g., '12345'), custom user ID with 'cuid:' prefix (e.g., 'cuid:user_123'), custom lead ID with 'clid:' prefix (e.g., 'clid:lead_456'), WhatsApp with 'wa:' prefix (e.g., 'wa:+1234567890'), or email with 'uem:' or 'lem:' prefix (e.g., 'uem:[email protected]' for users or 'lem:[email protected]' for leads)

Responses

401

Authentication required

403

Permission denied

404

Segment not found

422

The request is not valid

200List of conversations