OpenMax
Free Trial

Apps API · Conversations

Conversations: 28 endpoints

← All groups

GET /api/v1/conversations

List conversations

Scope: messages:conversation:read · Called with: appToken · operationId: list-conversations

Required app scope: messages:conversation:read.

Returns the current user's conversation list. Response wrapped in standard envelope.

Parameters

Name In Type Required Description
cursor query string Pagination cursor (opaque, from previous response; omit for first page)
limit query integer (int32) Items per page (default: 20, max: 100)
order_by query string Sort expression, e.g. created_at:desc
include_archived query boolean Include archived conversations
include_done query boolean Include done conversations
search_name query string Filter by conversation name (substring match)

Responses

POST /api/v1/conversations/dm

Find or create DM

Scope: messages:conversation:create · Called with: appToken · operationId: find-or-create-dm

Required app scope: messages:conversation:create.

Returns the existing DM with the peer member, or creates one. Response wrapped in standard envelope.

Request body

application/json · FindOrCreateDMRequestBody

Field Type Required Description
peer_member_id string (uuid) yes Peer OrgMember/Participant UUID

Responses

POST /api/v1/conversations/dm/subconversations

Find or create a context sub-conversation under a DM

Scope: messages:conversation:create · Called with: appToken · operationId: create-dm-subconversation

Required app scope: messages:conversation:create.

Convenience entry for callers that do not know (or, as an app, cannot read) the main DM id: finds or creates the caller's main DM with peer_member_id and finds or creates the sub-conversation under it. Owner, key, rollout and error rules are those of create-subconversation. The response carries the sub-conversation only, never the DM. Response wrapped in standard envelope.

Request body

application/json · CreateDMSubConversationRequestBody

Field Type Required Description
context_key string yes As for create-subconversation.
peer_member_id string (uuid) yes The DM peer (OrgMember/Participant UUID). The caller's main DM with this member is found or created and the sub-conversation hangs under it.
title string Display title. On an existing unarchived sub-conversation it replaces the title.

Responses

POST /api/v1/conversations/groups

Create group conversation

Scope: messages:conversation:create · Called with: appToken · operationId: create-group

Required app scope: messages:conversation:create.

Creates a group conversation. Response wrapped in standard envelope.

Request body

application/json · CreateGroupRequestBody

Field Type Required Description
avatar_media_id string Avatar media UUID
description string Group description
member_ids array of string yes Initial OrgMember/Participant UUIDs
metadata object Optional metadata
name string yes Group name

Responses

DELETE /api/v1/conversations/{conversation_id}

Delete a group conversation

Scope: messages:conversation:write · Called with: appToken · operationId: delete-group

Required app scope: messages:conversation:write.

Deletes a group conversation. Only the group OWNER may delete it (others get 403). Response wrapped in standard envelope.

Parameters

Name In Type Required Description
conversation_id path string (uuid) yes Conversation UUID

Responses

GET /api/v1/conversations/{conversation_id}

Get conversation

Scope: messages:conversation:read · Called with: appToken · operationId: get-conversation

Required app scope: messages:conversation:read.

Returns a conversation. Response wrapped in standard envelope.

Parameters

Name In Type Required Description
conversation_id path string (uuid) yes Conversation UUID

Responses

PATCH /api/v1/conversations/{conversation_id}

Update group conversation

Scope: messages:conversation:write · Called with: appToken · operationId: update-group-conversation

Required app scope: messages:conversation:write.

Updates a group conversation's name, description, or avatar. Returns the updated conversation. Response wrapped in standard envelope.

Parameters

Name In Type Required Description
conversation_id path string (uuid) yes Conversation UUID

Request body

application/json · UpdateGroupConversationRequestBody

Field Type Required Description
avatar_media_id string Avatar media UUID
description string Group description
name string Group name

Responses

POST /api/v1/conversations/{conversation_id}/archive

Archive (delete) a group conversation

Scope: messages:conversation:write · Called with: appToken · operationId: archive-conversation

Required app scope: messages:conversation:write.

Archives a group conversation, hiding it from all members' lists. Restricted to the conversation OWNER. Response wrapped in standard envelope. Note: this is a soft archive, not a hard delete — messages and history are retained.

Parameters

Name In Type Required Description
conversation_id path string (uuid) yes Conversation UUID

Responses

GET /api/v1/conversations/{conversation_id}/connectors

List enabled connectors for a conversation

Scope: connections:connection:read · Called with: appToken · operationId: list-conversation-connectors

Required app scope: connections:connection:read.

Returns the connectors enabled for the given conversation, scoped to the caller's org. Connectors whose connection was deleted or is no longer granted to an agent member of the conversation are omitted and recorded as disabled, so a later re-grant does not silently re-enable them (503 CONNECT_CONNECTOR_GRANT_UNAVAILABLE if grants cannot be verified). Used by the OpenMax web app's connector panel and by agent runtimes when they mount tools. 403 APP_TOKEN_NOT_ALLOWED for an app access token in an organization with sub-conversations rolled out. Response wrapped in standard envelope.

Parameters

Name In Type Required Description
conversation_id path string (uuid) yes Conversation UUID

Responses

PATCH /api/v1/conversations/{conversation_id}/connectors/{connector_id}

Enable or disable a connector on a conversation

Scope: connections:connection:write · Called with: appToken · operationId: toggle-conversation-connector

Required app scope: connections:connection:write.

Persists whether a connector is enabled for the given conversation. Scoped to the caller's org. Enabling requires the connection to still exist and be granted to an agent member of the conversation (422 CONNECT_CONNECTOR_NOT_GRANTED otherwise; 503 CONNECT_CONNECTOR_GRANT_UNAVAILABLE if that cannot be verified, or while a grant revocation/disconnect of the connection is in progress — retry); disabling is never gated. 403 APP_TOKEN_NOT_ALLOWED for an app access token in an organization with sub-conversations rolled out. Response wrapped in standard envelope.

Parameters

Name In Type Required Description
conversation_id path string (uuid) yes Conversation UUID
connector_id path string yes Connector identifier

Request body

application/json · PatchConversationConnectorRequestBody

Field Type Required Description
enabled boolean yes Whether the connector is enabled for this conversation

Responses

POST /api/v1/conversations/{conversation_id}/done

Mark conversation as done

Scope: messages:conversation.preference:write · Called with: appToken · operationId: done-conversation

Required app scope: messages:conversation.preference:write.

Marks a conversation as done for the current user. Response wrapped in standard envelope.

Parameters

Name In Type Required Description
conversation_id path string (uuid) yes Conversation UUID

Responses

POST /api/v1/conversations/{conversation_id}/leave

Leave a group conversation

Scope: messages:conversation:write · Called with: appToken · operationId: leave-group

Required app scope: messages:conversation:write.

The caller leaves a group: a non-owner just leaves; an owner must hand ownership over — pass new_owner_id to choose a human successor, or omit it to let the server pick a random remaining human member, or delete the group when only agents/nobody remain. The server enforces membership and that a group keeps a human owner. Response wrapped in standard envelope.

Parameters

Name In Type Required Description
conversation_id path string (uuid) yes Conversation UUID

Request body

application/json · LeaveGroupRequestBody

Field Type Required Description
new_owner_id string (uuid) When the leaving member is the group owner, the human member to hand ownership to. Omit to let the platform pick a random remaining human member, or delete the group when only agents/nobody remain.

Responses

GET /api/v1/conversations/{conversation_id}/members

List conversation members

Scope: messages:conversation.member:read · Called with: appToken · operationId: list-conversation-members

Required app scope: messages:conversation.member:read.

Returns conversation members. Response wrapped in standard envelope.

Parameters

Name In Type Required Description
conversation_id path string (uuid) yes Conversation UUID

Responses

POST /api/v1/conversations/{conversation_id}/members

Add conversation member

Scope: messages:conversation.member:write · Called with: appToken · operationId: add-conversation-member

Required app scope: messages:conversation.member:write.

Adds a member to a conversation. Returns 409 COMM_CONVERSATION_MEMBER_ALREADY_EXISTS when the member is already in the conversation. Response wrapped in standard envelope.

Parameters

Name In Type Required Description
conversation_id path string (uuid) yes Conversation UUID

Request body

application/json · AddMemberRequestBody

Field Type Required Description
member_id string (uuid) yes OrgMember/Participant UUID
role string: UNSPECIFIED, MEMBER, ADMIN, OWNER, PUBLISHER, SUBSCRIBER Member role

Responses

DELETE /api/v1/conversations/{conversation_id}/members/{member_id}

Remove conversation member

Scope: messages:conversation.member:write · Called with: appToken · operationId: remove-conversation-member

Required app scope: messages:conversation.member:write.

Removes a member from a conversation. Self-removal (leave) is blocked for the conversation owner when human members remain — the owner must transfer ownership first. Response wrapped in standard envelope.

Parameters

Name In Type Required Description
conversation_id path string (uuid) yes Conversation UUID
member_id path string (uuid) yes OrgMember/Participant UUID

Responses

POST /api/v1/conversations/{conversation_id}/members:batch-add

Batch add conversation members

Scope: messages:conversation.member:write · Called with: appToken · operationId: batch-add-conversation-members

Required app scope: messages:conversation.member:write.

Adds multiple members to a conversation and returns per-member results. Partial success is reported in the response body; transport errors are reserved for invalid request-level input. A member already in the conversation is reported as a failed row with status 409 and code COMM_CONVERSATION_MEMBER_ALREADY_EXISTS. Response wrapped in standard envelope.

Parameters

Name In Type Required Description
conversation_id path string (uuid) yes Conversation UUID

Request body

application/json · BatchAddConversationMembersRequestBody

Field Type Required Description
member_ids array of string yes OrgMember/Participant UUIDs to add
role string: UNSPECIFIED, MEMBER, ADMIN, OWNER, PUBLISHER, SUBSCRIBER Role applied to every added member

Responses

POST /api/v1/conversations/{conversation_id}/members:batch-remove

Batch remove conversation members

Scope: messages:conversation.member:write · Called with: appToken · operationId: batch-remove-conversation-members

Required app scope: messages:conversation.member:write.

Removes multiple members from a conversation and returns per-member results. This endpoint is for removing other members; callers should use the leave endpoint for self-removal and owner succession. Partial success is reported in the response body. Response wrapped in standard envelope.

Parameters

Name In Type Required Description
conversation_id path string (uuid) yes Conversation UUID

Request body

application/json · BatchRemoveConversationMembersRequestBody

Field Type Required Description
member_ids array of string yes OrgMember/Participant UUIDs to remove

Responses

POST /api/v1/conversations/{conversation_id}/mute

Mute conversation

Scope: messages:conversation.preference:write · Called with: appToken · operationId: mute-conversation

Required app scope: messages:conversation.preference:write.

Mutes a conversation for the current user. The flag is stored on the caller's conversation membership, so the mute follows the user across devices and does not affect other members. Idempotent. Muting changes notification state only: messages still arrive and unread counts still advance; is_muted is reported on the conversation list. Response wrapped in standard envelope.

Parameters

Name In Type Required Description
conversation_id path string (uuid) yes Conversation UUID

Responses

POST /api/v1/conversations/{conversation_id}/pin

Pin conversation

Scope: messages:conversation.preference:write · Called with: appToken · operationId: pin-conversation

Required app scope: messages:conversation.preference:write.

Pins a conversation to the top of the current user's list. The pin order is the caller's own (re-pinning an already-pinned conversation refreshes its order). Response wrapped in standard envelope.

Parameters

Name In Type Required Description
conversation_id path string (uuid) yes Conversation UUID

Responses

GET /api/v1/conversations/{conversation_id}/resources

List a conversation's images, files and links

Scope: messages:message:read · Called with: appToken · operationId: list-conversation-resources

Required app scope: messages:message:read.

Lists the images, files and links carried by the messages of one conversation, newest message first (message_at desc, then id). The caller must be able to read the conversation's messages (a member, or an observer within the owner's tenure), else 403; a missing conversation is 404. Files fenced for deletion are never listed. Filters: kind, sender_id, since (inclusive) and until (exclusive) on message_at, query. Keep paging with pagination.next_cursor and the same filters; it is empty on the last page. Response wrapped in standard envelope.

Parameters

Name In Type Required Description
conversation_id path string (uuid) yes Conversation UUID
kind query string Only these kinds, comma-separated: image, file, link (e.g. image,file). Omit for all kinds
sender_id query string (uuid) Only resources sent by this member. Omit for every sender
since query string (date-time) Only resources whose message_at is at or after this time (inclusive, RFC3339)
until query string (date-time) Only resources whose message_at is before this time (exclusive, RFC3339). Must not be earlier than since
query query string Case-insensitive literal substring of the file name, URL or link text
cursor query string pagination.next_cursor of the previous page, sent with the same filters; omit for the first page
limit query integer (int32) Items per page (default: 30, max: 100)

Responses

GET /api/v1/conversations/{conversation_id}/subconversations

List a conversation's context sub-conversations

Scope: messages:conversation:read · Called with: appToken · operationId: list-subconversations

Required app scope: messages:conversation:read.

Lists the context sub-conversations under a parent the caller can read, each with the caller's unread_count. An app access token lists only its own app's sub-conversations (the filter comes from the credential; there is no owner query). Other callers list every owner's. 404 when the parent does not exist or the caller cannot read it. Response wrapped in standard envelope.

Parameters

Name In Type Required Description
cursor query string Pagination cursor (opaque, from previous response; omit for first page)
limit query integer (int32) Items per page (default: 50, max: 100). The order is fixed; there is no order_by.
conversation_id path string (uuid) yes Parent conversation UUID
include_archived query boolean Include archived sub-conversations

Responses

POST /api/v1/conversations/{conversation_id}/subconversations

Find or create a context sub-conversation

Scope: messages:conversation:create · Called with: appToken · operationId: create-subconversation

Required app scope: messages:conversation:create.

Finds or creates the context sub-conversation (parent, owner, context_key) under a DM or group the caller is a member of; idempotent, an archived match is returned as is (read-only). The owner comes from the credential only: an app access token owns the sub-conversation as its own app (an owner in the body is ignored); any other caller acts as the platform and may only create reply topics (context_key message:). 404 when the parent does not exist or the caller is not a member of it (not told apart); 400 COMM_INVALID_CONTEXT_KEY for a malformed key; 409 COMM_SUBCONVERSATION_LIMIT_REACHED past 200 unarchived sub-conversations per parent and app; 403 SUBCONVERSATION_OWNER_NOT_ALLOWED when a non-app caller names an app owner; 403 SUBCONVERSATION_NOT_ENABLED outside the organizations sub-conversations are rolled out to. The response carries the sub-conversation only, never the parent. Response wrapped in standard envelope.

Parameters

Name In Type Required Description
conversation_id path string (uuid) yes Parent conversation UUID (a DM or a group the caller is a member of)

Request body

application/json · CreateSubConversationRequestBody

Field Type Required Description
context_key string yes The owner's key for this sub-conversation: 1-128 characters of [a-z0-9:_-] (400 COMM_INVALID_CONTEXT_KEY otherwise). A caller that is not an app access token acts as the platform and may only create reply topics, message: of a message in the parent.
owner SubConversationOwnerInput Ignored for app access tokens; see the field docs. The owner is always taken from the credential.
title string Display title. On an existing unarchived sub-conversation it replaces the title.

Responses

POST /api/v1/conversations/{conversation_id}/undone

Mark conversation as undone

Scope: messages:conversation.preference:write · Called with: appToken · operationId: undone-conversation

Required app scope: messages:conversation.preference:write.

Marks a conversation as undone (not done) for the current user. Response wrapped in standard envelope.

Parameters

Name In Type Required Description
conversation_id path string (uuid) yes Conversation UUID

Responses

POST /api/v1/conversations/{conversation_id}/unmute

Unmute conversation

Scope: messages:conversation.preference:write · Called with: appToken · operationId: unmute-conversation

Required app scope: messages:conversation.preference:write.

Unmutes a conversation for the current user. Idempotent. Response wrapped in standard envelope.

Parameters

Name In Type Required Description
conversation_id path string (uuid) yes Conversation UUID

Responses

POST /api/v1/conversations/{conversation_id}/unpin

Unpin conversation

Scope: messages:conversation.preference:write · Called with: appToken · operationId: unpin-conversation

Required app scope: messages:conversation.preference:write.

Unpins a conversation for the current user, returning it to the normal list order. Idempotent. Response wrapped in standard envelope.

Parameters

Name In Type Required Description
conversation_id path string (uuid) yes Conversation UUID

Responses

List a conversation's Issues

Scope: work:issue:read · Called with: appToken · operationId: list-conversation-work-links

Required app scope: work:issue:read.

Lists the Issues linked to a conversation, e.g. link_role=origin for the Issues created from it, each with its link and the Issue itself. The caller must be able to read the conversation (same rule as get-conversation: a member, or an observer of a member); otherwise 403, and 404 for an unknown conversation. Issues of a private project the caller may not access are never listed. Archived and terminated Issues are listed with their status (and archived_at / terminated_at); status / statuses keep only Issues in those statuses. Paging walks the conversation's links: a page can hold fewer than limit items, even none (an Issue filtered by status or no longer readable is left out), while pagination.next_cursor still leads on; keep paging while next_cursor is non-empty. No total count is returned. Response wrapped in standard envelope.

Parameters

Name In Type Required Description
conversation_id path string (uuid) yes Conversation UUID
work_type query string: issue Linked work type; only issue is supported (default issue)
link_role query string: origin, discussion, delivery, approval, handoff Only links of this role, e.g. origin for the Issues created from the conversation; omit for every role
status query string: backlog, in_progress, pending_plan, delivered, accepted, terminated Only Issues in this status
statuses query string Comma-separated inclusion filter for Issue statuses; takes precedence over status
cursor query string Pagination cursor (opaque, from a previous response's next_cursor; omit for the first page). It keeps the first page's limit.
limit query integer (int32) Links read per page (default: 20, max: 50)

Responses

PATCH /api/v1/subconversations/{subconversation_id}

Retitle a context sub-conversation

Scope: messages:conversation:write · Called with: appToken · operationId: update-subconversation

Required app scope: messages:conversation:write.

Sets the display title. Owner only: an app access token for its own app's sub-conversations, any other member for platform reply topics (403 SUBCONVERSATION_OWNER_NOT_ALLOWED otherwise). 404 when it is not a sub-conversation the caller belongs to; 409 COMM_SUBCONVERSATION_ARCHIVED when it is archived. Response wrapped in standard envelope.

Parameters

Name In Type Required Description
subconversation_id path string (uuid) yes Sub-conversation UUID

Request body

application/json · UpdateSubConversationRequestBody

Field Type Required Description
title string yes New display title; empty clears it.

Responses

POST /api/v1/subconversations/{subconversation_id}/archive

Archive a context sub-conversation

Scope: messages:conversation:write · Called with: appToken · operationId: archive-subconversation

Required app scope: messages:conversation:write.

Makes the sub-conversation read-only with archived_reason owner (its owner's object was deleted); idempotent, and an app_uninstalled archive becomes an owner archive so a reinstall does not lift it. Owner only, as for update-subconversation (403 SUBCONVERSATION_OWNER_NOT_ALLOWED otherwise). Response wrapped in standard envelope.

Parameters

Name In Type Required Description
subconversation_id path string (uuid) yes Sub-conversation UUID

Responses