List Conversations

Beta

GET/v1/messaging/conversations

This endpoint is idempotent. Learn more

Returns the caller's conversations, most recently active first.

A customer portal user sees only their own support case with the vendor, and an empty list until they have contacted support.

Permissions requiredValues:messaging:read

The role behind your API key or agent must grant every one of these permissions.

cursoroptional string

Opaque cursor token identifying where the page of results starts.

Use the cursor value embedded in a previous response's next_page_url or previous_page_url to fetch the adjacent page. Omit to start from the first page.

limitoptional integer

Maximum number of results to return in a single page.

qoptional string

Free-text search term used to filter results.

Which fields are matched against the term varies by endpoint.

typeoptional stringenumValues:direct_messagegroupsystem

Filter by conversation type.

audienceoptional stringenumValues:internalcustomer

Filter by whether the conversation is team-only or customer-facing.

internal: threads the customer never sees — direct messages, group threads, and record discussions.
customer: external customer-service cases the customer takes part in, from the portal or a bridged email thread.

statusoptional stringenumValues:activehidden

Filter by whether the caller has hidden the conversation from their own list.

topic_resource_typeoptional stringenumValues:accountactorentity

Restrict to conversations attached to a business record of this type, together with topic_resource_id.

Matches both conversations anchored to the record and conversations that merely link it, which is what powers the "discussions on this record" view.

topic_resource_idoptional string

The id of the business record, together with topic_resource_type.

workflow_statusoptional stringenumValues:newopenwaiting_internal

Filter the support inbox to a single triage lane.

new: opened but nobody has triaged it yet.
open: actively being worked.
waiting_internal: blocked on the internal team.
waiting_external: blocked on a reply from the customer.
needs_approval: a drafted reply is waiting for a human to approve it.
resolved: closed out.

The working inbox hides resolved cases unless you ask for this lane explicitly.

assignee_resource_idoptional string

Filter the support inbox to cases owned by this assignee, an account user or an account group.

unassignedoptional boolean

Restrict the support inbox to cases nobody has been assigned yet.

include_archivedoptional boolean

Return the archived support inbox instead of the working one.

This swaps the view rather than widening it: archived cases are returned and unarchived ones are left out.

include[]optional arrayenumValues:assigneegroupparticipants

Sub-objects to expand in the response. When omitted, sub-objects are returned as null.

objectstringenumValues:list

Resource type identifier.

page_infoobject

Pagination metadata.

next_page_urlstringnullable

Relative URL that fetches the next page of results.

previous_page_urlstringnullable

Relative URL that fetches the previous page of results.

has_next_pageboolean

Whether more results exist after this page.

has_prev_pageboolean

Whether results exist before this page.

dataarray of conversation

Resources in this page.

idstring

Conversation ID.

objectstringenumValues:conversation

Resource type identifier.

typestringenumValues:direct_messagegroupsystem

What kind of conversation this is.

direct_message: a 1:1 thread between two users.
group: a named thread with multiple user or agent members (including customer-facing support cases).
system: a system channel that delivers automated account alerts.

audiencestringenumValues:internalcustomer

Whether this is a team-only conversation (internal) or a customer-facing case (customer).

A customer never sees an internal conversation, even one that is about them; within a customer case they see only the messages that were sent to them, not the team's internal notes on the case.

titlestringnullable

The display title of a group conversation.

Direct messages carry no stored title; clients derive one from the participants.

workflow_statusstringnullableenumValues:newopenwaiting_internal

The triage lane of a customer-facing case.

Only conversations with a customer audience have a triage lane. It drives the support inbox and is independent of status, which is about visibility rather than progress.

new: opened but not yet triaged.
open: actively being worked.
waiting_internal: blocked on the internal team.
waiting_external: blocked on an external reply.
needs_approval: a drafted reply is awaiting human approval.
resolved: closed out.

groupmessaging_groupExpandablenullable

The reusable roster this conversation was started from.

This is provenance only: the roster's members were copied into the conversation when it was created, so later edits to the roster never add or remove participants here, and deleting the roster only clears this reference.

idstring

Messaging group ID.

objectstringenumValues:messaging_group

Resource type identifier.

namestring

The roster's display name.

memberslistnullable

The roster's members (users and agents).

Always returned as null in this endpoint.

created_atstring (date-time)

Creation timestamp.

updated_atstring (date-time)

Last updated timestamp.

statusstringenumValues:activearchivedhidden

The conversation's state from the caller's point of view.

active: a normal, visible conversation.
archived: archived for the whole account.
hidden: the caller dismissed the conversation from their own list while everyone else still sees it, which takes precedence over an account-level archive.

legal_holdstringenumValues:releasedheld

Whether the conversation is under legal hold.

While held, the conversation is exempt from automatic retention purging and from redaction until the hold is released.

assigneeactorExpandablenullable

The owner of the case: either a user actor (an individual team member) or a group actor (a team).

idstring

Unique identifier of the actor.

objectstringenumValues:actor

Resource type identifier.

typestringenumValues:userapi_keyagent

Actor type.

user: a human user account.
api_key: a programmatic caller authenticating with an API key.
agent: an automated agent acting on the account's behalf.
group: a shared group identity, such as a "Customer Service" persona, rather than a single individual.

namestringnullable

The actor's display name.

handlestringnullable

Human-readable handle identifying the actor.

For user actors: the user's email address.
For api_key actors: the redacted key value.

Other actor types carry no handle.

avatar_urlstringnullable

URL of the actor's profile photo, if one is set.

Only populated for user actors.

rolerolenullable

The role the actor holds in the account, which determines what it is permitted to do.

Always returned as null in this endpoint.

participantslistExpandablenullable

The participants of the conversation.

Only current members are listed; anyone who left or was removed is omitted, even though their past messages remain in the thread.

objectstringenumValues:list

Resource type identifier.

page_infoobject

Pagination metadata.

next_page_urlstringnullable

Relative URL that fetches the next page of results.

previous_page_urlstringnullable

Relative URL that fetches the previous page of results.

has_next_pageboolean

Whether more results exist after this page.

has_prev_pageboolean

Whether results exist before this page.

dataarray of conversation_participant

Resources in this page.

idstring

Participant ID.

objectstringenumValues:conversation_participant

Resource type identifier.

typestringenumValues:useragentsystem

The kind of participant.

user: an account user (a teammate).
agent: an AI agent.
system: the system itself, which posts automated messages.
customer: an external customer in a support case.

rolestringenumValues:owneradminmember

The participant's permission level in the conversation.

owner: can rename or delete the conversation and manage its members and their roles.
admin: can add or remove members and rename the conversation.
member: can post, react, mute, and leave.
viewer: read-only access.

membershipstringenumValues:activeleftremoved

The participant's membership in the conversation.

active: currently a member.
left: voluntarily left the conversation.
removed: removed by an admin.
hidden: still a member but has hidden the conversation from their own list.

Membership records are kept rather than deleted, so re-adding someone who left or was removed reactivates their original record and their earlier messages stay attributed to them.

notificationsstringenumValues:unmutedmuted

The participant's notification preference for the conversation.

unmuted: receives notifications for new messages.
muted: new-message notifications are suppressed, though a direct @mention still raises an in-app alert (never an email), and the conversation still counts toward the unread total.

actoractornullable

The user or agent behind this participant.

A customer participant resolves to the user actor of the person who opened the case; the system participant that posts automated messages has no actor.

Always returned as null in this endpoint.

agent_trigger_policystringnullableenumValues:mentionkeywordalways

For agent participants, when the agent is invoked in response to messages.

mention: only when the agent is @mentioned.
keyword: when a message contains one of the agent's trigger keywords.
always: on every human message in the conversation.

agent_trigger_keywordsarray of string

For agent participants with a keyword or mention policy, the keywords that trigger it.

Matching is case-insensitive and looks anywhere in the message body: under keyword the bare word is matched, under mention it must appear as @keyword. Replying directly to one of the agent's own messages always reaches it, so an agent with no keywords still answers replies but nothing else.

read_cursorread_cursor

The participant's read position in the conversation (read receipts): how far they have read.

Always returned as null in this endpoint.

topicentityExpandablenullable

The app record this conversation is anchored to, such as a sales order.

Anchored conversations surface as the discussion thread on that record.

idstring

Unique identifier for the entity.

objectstringenumValues:entity

Resource type identifier.

typestringenumValues:accountactorentity

The resource kind that this entity references, as an object-type value (e.g. user, account).

Unlike object — which is always entity — this names the underlying resource the id points to.

namestringnullable

Human-readable display name for the entity (e.g. a user's full name, a sales order number).

handlestringnullable

Secondary human-readable identifier (e.g. email address, username, redacted API key value).

unreadinteger

Number of messages the caller has not yet read.

last_message_atstring (date-time)nullable

When the most recent message was sent.

last_messagechat_messageExpandablenullable

The most recent message in the conversation.

idstring

Message ID.

objectstringenumValues:chat_message

Resource type identifier.

kindstringenumValues:chatsystem_eventagent

What this message represents.

chat: written by a person.
system_event: a record of something that happened in the conversation, such as someone joining or a record being linked.
agent: written by an AI agent taking part in the conversation.
scheduled: came from a send queued ahead of time.
alert: an automated alert surfaced in the conversation.
email: a message carried over the case's bridged email thread, either one that arrived from the customer or a reply sent back out to them.

statusstringenumValues:draftscheduledsent

Where the message stands in its life.

draft: a proposed reply to the customer, still editable and waiting for approval before anyone outside sees it.
scheduled: queued to go out at a future time.
sent: delivered, and part of the conversation everyone reads.
canceled: a scheduled message stopped before it went out.
rejected: a draft discarded instead of being sent.
failed: a scheduled message that could not be delivered.
superseded: a draft replaced by a newer one for the same thread.

Only a sent message occupies a place in the conversation; the others are records of messages that never reached it.

visibilitystringenumValues:internalexternalsystem

Who can see this message.

internal: a note only your team can see.
external: sent to or received from an outside party, such as the customer on a support case, and part of the official record of that exchange.
system: an event both your team and the customer see.

A customer reading their own case is never served internal messages.

conversationconversationnullable

The conversation this message belongs to.

Always returned as null in this endpoint.

sequenceinteger

The message's position in the conversation timeline, counting up from the first message.

A sequence is assigned only when a message is delivered, so a draft or a not-yet-sent scheduled message reports 0. Listing a conversation's messages pages backwards through this ordering.

bodystringnullable

Message body.

A message made up of nothing but attachments or a linked record carries no body, and a deleted message has its body cleared.

subjectstringnullable

The email subject line.

On an email-bridged case, this is the subject of the inbound email, or the subject a customer reply is sent out with.

senderactorExpandablenullable

The party the message is displayed as coming from.

On a customer-facing case the customer sees every reply from your side as a single branded "Customer Service" party rather than the individual person or agent behind it, and an inbound email is shown as the outside address it arrived from. Everywhere else this is the user or agent that wrote the message. Pure system messages have no sender.

idstring

Unique identifier of the actor.

objectstringenumValues:actor

Resource type identifier.

typestringenumValues:userapi_keyagent

Actor type.

user: a human user account.
api_key: a programmatic caller authenticating with an API key.
agent: an automated agent acting on the account's behalf.
group: a shared group identity, such as a "Customer Service" persona, rather than a single individual.

namestringnullable

The actor's display name.

handlestringnullable

Human-readable handle identifying the actor.

For user actors: the user's email address.
For api_key actors: the redacted key value.

Other actor types carry no handle.

avatar_urlstringnullable

URL of the actor's profile photo, if one is set.

Only populated for user actors.

rolerolenullable

The role the actor holds in the account, which determines what it is permitted to do.

Always returned as null in this endpoint.

authoractorExpandablenullable

The user or agent that actually wrote the message.

Absent on system messages, and on a vendor-side reply read by a customer — the real author behind the branded "Customer Service" party is never revealed to them.

idstring

Unique identifier of the actor.

objectstringenumValues:actor

Resource type identifier.

typestringenumValues:userapi_keyagent

Actor type.

user: a human user account.
api_key: a programmatic caller authenticating with an API key.
agent: an automated agent acting on the account's behalf.
group: a shared group identity, such as a "Customer Service" persona, rather than a single individual.

namestringnullable

The actor's display name.

handlestringnullable

Human-readable handle identifying the actor.

For user actors: the user's email address.
For api_key actors: the redacted key value.

Other actor types carry no handle.

avatar_urlstringnullable

URL of the actor's profile photo, if one is set.

Only populated for user actors.

rolerolenullable

The role the actor holds in the account, which determines what it is permitted to do.

Always returned as null in this endpoint.

attachmentslistExpandablenullable

Files, images, links, or resources attached to the message.

objectstringenumValues:list

Resource type identifier.

page_infoobject

Pagination metadata.

next_page_urlstringnullable

Relative URL that fetches the next page of results.

previous_page_urlstringnullable

Relative URL that fetches the previous page of results.

has_next_pageboolean

Whether more results exist after this page.

has_prev_pageboolean

Whether results exist before this page.

dataarray of message_attachment

Resources in this page.

idstring

Attachment ID.

objectstringenumValues:message_attachment

Resource type identifier.

kindstringenumValues:fileimagelink

The kind of attachment, which determines how it is stored and which of the fields below are populated.

file: an uploaded non-image file.
image: an uploaded image.
link: an external URL reference, with no stored file.
resource: a reference to an in-app resource, such as an order.

filenamestringnullable

The filename the attachment was uploaded under.

Carried only by file and image attachments.

content_typestringnullable

The MIME type of the uploaded content.

Carried only by file and image attachments.

size_bytesintegernullable

The size of the uploaded content in bytes.

Carried only by file and image attachments, and only when the sender supplied it with the message.

urlstringnullable

Where to fetch the attachment: a signed download URL for file and image attachments, or the target address for link attachments.

Download URLs are signed for one hour and regenerated each time the message is read, so follow the URL promptly instead of persisting it. resource attachments have no URL — use resource to resolve them.

resourceentitynullable

The in-app record a resource attachment points to, such as a sales order.

Always returned as null in this endpoint.

created_atstring (date-time)

Creation timestamp.

reply_tochat_messagenullable

The message this one replies to.

Always returned as null in this endpoint.

resourceentityExpandablenullable

The record this message links to, such as the order it is about.

idstring

Unique identifier for the entity.

objectstringenumValues:entity

Resource type identifier.

typestringenumValues:accountactorentity

The resource kind that this entity references, as an object-type value (e.g. user, account).

Unlike object — which is always entity — this names the underlying resource the id points to.

namestringnullable

Human-readable display name for the entity (e.g. a user's full name, a sales order number).

handlestringnullable

Secondary human-readable identifier (e.g. email address, username, redacted API key value).

channelstringenumValues:messageemail

How the message reached its audience, or how a draft will be sent once it is approved.

message: appears in the conversation itself.
email: goes out as email on the thread of the inbox the case is bridged to.

scheduled_atstring (date-time)nullable

When a message queued for a future send is due to go out.

agent_runagent_runnullable

The agent run that produced this message, for deep-linking from an agent reply to its run.

Always returned as null in this endpoint.

streaming_statestringnullableenumValues:streamingcomplete

The streaming state of an agent reply.

streaming means the body is still being generated and keeps growing as realtime updates arrive; complete means it is final.

client_message_idstringnullable

The dedupe key the client supplied when sending, echoed back so an optimistic local copy can be matched to the stored message.

edited_atstring (date-time)nullable

When the message was last edited.

deleted_atstring (date-time)nullable

When the message was deleted.

A deleted message keeps its place in the timeline with its body cleared, so surrounding ordering and replies stay intact.

created_atstring (date-time)

Creation timestamp.

updated_atstring (date-time)

Last update timestamp.

agent_run_failedboolean

Whether this message is an agent reply reporting that the agent's run failed.

The body explains the failure to the reader rather than answering the request.

agent_error_codestringnullableenumValues:expired_tokenapi_key_expiredapi_key_revoked

Machine-readable reason an agent reply failed.

A client can react to the specific code rather than just showing the body — agent_spending_cap_reached, for example, is a cue to offer raising the agent spending limit.

created_atstring (date-time)

Creation timestamp.

updated_atstring (date-time)

Last update timestamp.

Responses

200

Successful response for List Conversations

List Conversations

import OpenMRP from '@openmrp/sdk';

const client = new OpenMRP({
  bearerToken: 'YOUR_API_KEY', // Your API key goes here
});

const listConversation = await client.messaging.conversations.list();

console.log(listConversation.data);

import OpenMRP from '@openmrp/sdk';

const client = new OpenMRP({
  bearerToken: 'YOUR_API_KEY', // Your API key goes here
});

const listConversation = await client.messaging.conversations.list();

console.log(listConversation.data);

200 example

{
  "object": "list",
  "page_info": {
    "next_page_url": "/v1/messaging/conversations?cursor=eyJjIjoiMjAyNi0wNS0xMFQwMDowMDowMFoiLCJzIjoiY3ZfdzM1ejRjazY4eXE3IiwiZCI6ImYifQ.ZYJ2j4EKO3ICw17l8OQMDVIJODqA1j2ZQBMFI7aoGlU",
    "previous_page_url": null,
    "has_next_page": true,
    "has_prev_page": false
  },
  "data": [
    {
      "id": "cv_w35z4ck68yq7",
      "object": "conversation",
      "type": "direct_message",
      "audience": "internal",
      "title": null,
      "workflow_status": null,
      "group": null,
      "status": "active",
      "legal_hold": "released",
      "assignee": null,
      "participants": {
        "object": "list",
        "page_info": {
          "next_page_url": null,
          "previous_page_url": null,
          "has_next_page": false,
          "has_prev_page": false
        },
        "data": [
          {
            "id": "cvpt_be2h3ul14cts",
            "object": "conversation_participant",
            "type": "user",
            "role": "member",
            "membership": "active",
            "notifications": "unmuted",
            "actor": null,
            "agent_trigger_policy": null,
            "agent_trigger_keywords": [],
            "read_cursor": null
          }
        ]
      },
      "topic": null,
      "unread": 2,
      "last_message_at": "2026-05-10T00:23:00Z",
      "last_message": {
        "id": "mg_fdny8633ebgw",
        "object": "chat_message",
        "kind": "chat",
        "status": "sent",
        "visibility": "internal",
        "conversation": null,
        "sequence": 42,
        "body": "Sounds good — shipping it today.",
        "subject": null,
        "sender": {
          "id": "acus_e5zu8bde0z3h",
          "object": "actor",
          "type": "user",
          "name": "Jie Yan",
          "handle": null,
          "avatar_url": null,
          "role": null
        },
        "author": null,
        "attachments": null,
        "reply_to": null,
        "resource": null,
        "channel": "message",
        "scheduled_at": null,
        "agent_run": null,
        "streaming_state": null,
        "client_message_id": null,
        "edited_at": null,
        "deleted_at": null,
        "created_at": "2026-05-10T00:00:00Z",
        "updated_at": "2026-05-10T00:23:00Z",
        "agent_run_failed": false,
        "agent_error_code": null
      },
      "created_at": "2026-05-10T00:00:00Z",
      "updated_at": "2026-05-10T00:23:00Z"
    }
  ]
}

{
  "object": "list",
  "page_info": {
    "next_page_url": "/v1/messaging/conversations?cursor=eyJjIjoiMjAyNi0wNS0xMFQwMDowMDowMFoiLCJzIjoiY3ZfdzM1ejRjazY4eXE3IiwiZCI6ImYifQ.ZYJ2j4EKO3ICw17l8OQMDVIJODqA1j2ZQBMFI7aoGlU",
    "previous_page_url": null,
    "has_next_page": true,
    "has_prev_page": false
  },
  "data": [
    {
      "id": "cv_w35z4ck68yq7",
      "object": "conversation",
      "type": "direct_message",
      "audience": "internal",
      "title": null,
      "workflow_status": null,
      "group": null,
      "status": "active",
      "legal_hold": "released",
      "assignee": null,
      "participants": {
        "object": "list",
        "page_info": {
          "next_page_url": null,
          "previous_page_url": null,
          "has_next_page": false,
          "has_prev_page": false
        },
        "data": [
          {
            "id": "cvpt_be2h3ul14cts",
            "object": "conversation_participant",
            "type": "user",
            "role": "member",
            "membership": "active",
            "notifications": "unmuted",
            "actor": null,
            "agent_trigger_policy": null,
            "agent_trigger_keywords": [],
            "read_cursor": null
          }
        ]
      },
      "topic": null,
      "unread": 2,
      "last_message_at": "2026-05-10T00:23:00Z",
      "last_message": {
        "id": "mg_fdny8633ebgw",
        "object": "chat_message",
        "kind": "chat",
        "status": "sent",
        "visibility": "internal",
        "conversation": null,
        "sequence": 42,
        "body": "Sounds good — shipping it today.",
        "subject": null,
        "sender": {
          "id": "acus_e5zu8bde0z3h",
          "object": "actor",
          "type": "user",
          "name": "Jie Yan",
          "handle": null,
          "avatar_url": null,
          "role": null
        },
        "author": null,
        "attachments": null,
        "reply_to": null,
        "resource": null,
        "channel": "message",
        "scheduled_at": null,
        "agent_run": null,
        "streaming_state": null,
        "client_message_id": null,
        "edited_at": null,
        "deleted_at": null,
        "created_at": "2026-05-10T00:00:00Z",
        "updated_at": "2026-05-10T00:23:00Z",
        "agent_run_failed": false,
        "agent_error_code": null
      },
      "created_at": "2026-05-10T00:00:00Z",
      "updated_at": "2026-05-10T00:23:00Z"
    }
  ]
}

List Conversations

Authorization

Query Parameters

Returns

Responses