List conversations
List the conversations of your organization with filters, text search and pagination. This is the same query the inbox and the conversation pipeline board use.
Endpoint
GET/conversations
Query parameters
Any conversation field can be used as a filter with the standard operators. The ones below are the most useful, plus the extra search parameters this resource supports.
| Name | Type | Required | Description |
|---|---|---|---|
organization_id | integer | No | Organization to list. Required when you use messageSearchTerm. |
status | string | No | open or closed. |
channel | string | No | One channel, e.g. whatsapp. Use channel[$ne]=playground to hide AI playground threads like the inbox does. |
channels | string | No | Comma-separated list of channels and/or specific WhatsApp numbers: whatsapp,instagram or whatsapp:12,sms (whatsapp:<whatsapp_channel_id>). Matches any entry. |
assigned_user_id | integer | null | No | Human owner. assigned_user_id=null returns unassigned threads. |
assigned_ai_assistant_id | integer | null | No | AI assistant. null returns threads without AI. |
pipeline_id | integer | No | Conversation pipeline. Only conversations of the channels the pipeline accepts are returned (channel scope). |
pipeline_stage_id | integer | null | No | Stage. null returns threads without a stage. |
incoming_pipeline_id | integer | No | Incoming column of one pipeline: threads with no stage that belong to that pipeline or to no pipeline. Overrides pipeline_id / pipeline_stage_id. Limited to the channels the pipeline accepts. |
whatsapp_channel_id | integer | No | Threads of one WhatsApp number. |
contact_id | integer | No | Threads of one contact. |
tag_id | string | No | One contact tag ID or a comma-separated list (7,12). Matches threads whose contact has any of the tags. |
unread_count[$gt] | integer | No | unread_count[$gt]=0 returns unread threads only. |
waitingResponseOnly | boolean | No | true returns threads whose last incoming message is newer than the last outgoing one. |
searchTerm | string | No | Searches contact first/last/full name, WhatsApp profile name, WhatsApp phone ID, WhatsApp username and Instagram profile name. |
messageSearchTerm | string | No | Searches message text (WhatsApp, Instagram, Messenger and webchat). At least 3 characters, otherwise ignored. Each result gets a matchingMessages array with one sample message. Pass organization_id with it. |
last_interaction_at[$gte] / created_at[$gte] ... | string (date-time) | No | Date ranges with $gte, $lte. |
$limit | integer | No | Page size. Default 10, maximum 50. |
$skip | integer | No | Records to skip. |
$sort[field] | 1 | -1 | No | Sort, e.g. $sort[last_interaction_at]=-1 (newest activity first, like the inbox). |
$select[] | string | No | Return only these fields, e.g. $select[]=id. |
Request
Search by contact name inside one pipeline stage:
Response
json
Each item is a full conversation object (shortened here).
Notes
- Results are limited to your API key's organization. Members restricted to some channel accounts only see those accounts' conversations.
- Unknown query parameters are rejected with
400 Bad Request.
Report an issue with this documentation
Please log in to report issues with our documentation.