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.

NameTypeRequiredDescription
organization_idintegerNoOrganization to list. Required when you use messageSearchTerm.
statusstringNoopen or closed.
channelstringNoOne channel, e.g. whatsapp. Use channel[$ne]=playground to hide AI playground threads like the inbox does.
channelsstringNoComma-separated list of channels and/or specific WhatsApp numbers: whatsapp,instagram or whatsapp:12,sms (whatsapp:<whatsapp_channel_id>). Matches any entry.
assigned_user_idinteger | nullNoHuman owner. assigned_user_id=null returns unassigned threads.
assigned_ai_assistant_idinteger | nullNoAI assistant. null returns threads without AI.
pipeline_idintegerNoConversation pipeline. Only conversations of the channels the pipeline accepts are returned (channel scope).
pipeline_stage_idinteger | nullNoStage. null returns threads without a stage.
incoming_pipeline_idintegerNoIncoming 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_idintegerNoThreads of one WhatsApp number.
contact_idintegerNoThreads of one contact.
tag_idstringNoOne contact tag ID or a comma-separated list (7,12). Matches threads whose contact has any of the tags.
unread_count[$gt]integerNounread_count[$gt]=0 returns unread threads only.
waitingResponseOnlybooleanNotrue returns threads whose last incoming message is newer than the last outgoing one.
searchTermstringNoSearches contact first/last/full name, WhatsApp profile name, WhatsApp phone ID, WhatsApp username and Instagram profile name.
messageSearchTermstringNoSearches 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)NoDate ranges with $gte, $lte.
$limitintegerNoPage size. Default 10, maximum 50.
$skipintegerNoRecords to skip.
$sort[field]1 | -1NoSort, e.g. $sort[last_interaction_at]=-1 (newest activity first, like the inbox).
$select[]stringNoReturn 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.