OpenMax
免费试用

Apps API · Conversations

Conversations: 28 个接口

← 全部分组

GET /api/v1/conversations

List conversations

权限(scope): messages:conversation:read · 调用方式: appToken · operationId: list-conversations

Required app scope: messages:conversation:read.

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

参数

名字 位置 类型 必填 说明
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)

回包

POST /api/v1/conversations/dm

Find or create DM

权限(scope): messages:conversation:create · 调用方式: 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.

请求体

application/json · FindOrCreateDMRequestBody

字段 类型 必填 说明
peer_member_id string (uuid) 是 Peer OrgMember/Participant UUID

回包

POST /api/v1/conversations/dm/subconversations

Find or create a context sub-conversation under a DM

权限(scope): messages:conversation:create · 调用方式: 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.

请求体

application/json · CreateDMSubConversationRequestBody

字段 类型 必填 说明
context_key string 是 As for create-subconversation.
peer_member_id string (uuid) 是 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.

回包

POST /api/v1/conversations/groups

Create group conversation

权限(scope): messages:conversation:create · 调用方式: appToken · operationId: create-group

Required app scope: messages:conversation:create.

Creates a group conversation. Response wrapped in standard envelope.

请求体

application/json · CreateGroupRequestBody

字段 类型 必填 说明
avatar_media_id string Avatar media UUID
description string Group description
member_ids array of string 是 Initial OrgMember/Participant UUIDs
metadata object Optional metadata
name string 是 Group name

回包

DELETE /api/v1/conversations/{conversation_id}

Delete a group conversation

权限(scope): messages:conversation:write · 调用方式: 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.

参数

名字 位置 类型 必填 说明
conversation_id path string (uuid) 是 Conversation UUID

回包

GET /api/v1/conversations/{conversation_id}

Get conversation

权限(scope): messages:conversation:read · 调用方式: appToken · operationId: get-conversation

Required app scope: messages:conversation:read.

Returns a conversation. Response wrapped in standard envelope.

参数

名字 位置 类型 必填 说明
conversation_id path string (uuid) 是 Conversation UUID

回包

PATCH /api/v1/conversations/{conversation_id}

Update group conversation

权限(scope): messages:conversation:write · 调用方式: 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.

参数

名字 位置 类型 必填 说明
conversation_id path string (uuid) 是 Conversation UUID

请求体

application/json · UpdateGroupConversationRequestBody

字段 类型 必填 说明
avatar_media_id string Avatar media UUID
description string Group description
name string Group name

回包

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

Archive (delete) a group conversation

权限(scope): messages:conversation:write · 调用方式: 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.

参数

名字 位置 类型 必填 说明
conversation_id path string (uuid) 是 Conversation UUID

回包

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

List enabled connectors for a conversation

权限(scope): connections:connection:read · 调用方式: 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.

参数

名字 位置 类型 必填 说明
conversation_id path string (uuid) 是 Conversation UUID

回包

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

Enable or disable a connector on a conversation

权限(scope): connections:connection:write · 调用方式: 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.

参数

名字 位置 类型 必填 说明
conversation_id path string (uuid) 是 Conversation UUID
connector_id path string 是 Connector identifier

请求体

application/json · PatchConversationConnectorRequestBody

字段 类型 必填 说明
enabled boolean 是 Whether the connector is enabled for this conversation

回包

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

Mark conversation as done

权限(scope): messages:conversation.preference:write · 调用方式: 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.

参数

名字 位置 类型 必填 说明
conversation_id path string (uuid) 是 Conversation UUID

回包

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

Leave a group conversation

权限(scope): messages:conversation:write · 调用方式: 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.

参数

名字 位置 类型 必填 说明
conversation_id path string (uuid) 是 Conversation UUID

请求体

application/json · LeaveGroupRequestBody

字段 类型 必填 说明
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.

回包

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

List conversation members

权限(scope): messages:conversation.member:read · 调用方式: appToken · operationId: list-conversation-members

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

Returns conversation members. Response wrapped in standard envelope.

参数

名字 位置 类型 必填 说明
conversation_id path string (uuid) 是 Conversation UUID

回包

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

Add conversation member

权限(scope): messages:conversation.member:write · 调用方式: 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.

参数

名字 位置 类型 必填 说明
conversation_id path string (uuid) 是 Conversation UUID

请求体

application/json · AddMemberRequestBody

字段 类型 必填 说明
member_id string (uuid) 是 OrgMember/Participant UUID
role string: UNSPECIFIED, MEMBER, ADMIN, OWNER, PUBLISHER, SUBSCRIBER Member role

回包

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

Remove conversation member

权限(scope): messages:conversation.member:write · 调用方式: 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.

参数

名字 位置 类型 必填 说明
conversation_id path string (uuid) 是 Conversation UUID
member_id path string (uuid) 是 OrgMember/Participant UUID

回包

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

Batch add conversation members

权限(scope): messages:conversation.member:write · 调用方式: 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.

参数

名字 位置 类型 必填 说明
conversation_id path string (uuid) 是 Conversation UUID

请求体

application/json · BatchAddConversationMembersRequestBody

字段 类型 必填 说明
member_ids array of string 是 OrgMember/Participant UUIDs to add
role string: UNSPECIFIED, MEMBER, ADMIN, OWNER, PUBLISHER, SUBSCRIBER Role applied to every added member

回包

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

Batch remove conversation members

权限(scope): messages:conversation.member:write · 调用方式: 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.

参数

名字 位置 类型 必填 说明
conversation_id path string (uuid) 是 Conversation UUID

请求体

application/json · BatchRemoveConversationMembersRequestBody

字段 类型 必填 说明
member_ids array of string 是 OrgMember/Participant UUIDs to remove

回包

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

Mute conversation

权限(scope): messages:conversation.preference:write · 调用方式: 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.

参数

名字 位置 类型 必填 说明
conversation_id path string (uuid) 是 Conversation UUID

回包

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

Pin conversation

权限(scope): messages:conversation.preference:write · 调用方式: 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.

参数

名字 位置 类型 必填 说明
conversation_id path string (uuid) 是 Conversation UUID

回包

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

List a conversation's images, files and links

权限(scope): messages:message:read · 调用方式: 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.

参数

名字 位置 类型 必填 说明
conversation_id path string (uuid) 是 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)

回包

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

List a conversation's context sub-conversations

权限(scope): messages:conversation:read · 调用方式: 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.

参数

名字 位置 类型 必填 说明
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) 是 Parent conversation UUID
include_archived query boolean Include archived sub-conversations

回包

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

Find or create a context sub-conversation

权限(scope): messages:conversation:create · 调用方式: 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.

参数

名字 位置 类型 必填 说明
conversation_id path string (uuid) 是 Parent conversation UUID (a DM or a group the caller is a member of)

请求体

application/json · CreateSubConversationRequestBody

字段 类型 必填 说明
context_key string 是 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.

回包

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

Mark conversation as undone

权限(scope): messages:conversation.preference:write · 调用方式: 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.

参数

名字 位置 类型 必填 说明
conversation_id path string (uuid) 是 Conversation UUID

回包

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

Unmute conversation

权限(scope): messages:conversation.preference:write · 调用方式: appToken · operationId: unmute-conversation

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

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

参数

名字 位置 类型 必填 说明
conversation_id path string (uuid) 是 Conversation UUID

回包

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

Unpin conversation

权限(scope): messages:conversation.preference:write · 调用方式: 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.

参数

名字 位置 类型 必填 说明
conversation_id path string (uuid) 是 Conversation UUID

回包

List a conversation's Issues

权限(scope): work:issue:read · 调用方式: 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.

参数

名字 位置 类型 必填 说明
conversation_id path string (uuid) 是 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)

回包

PATCH /api/v1/subconversations/{subconversation_id}

Retitle a context sub-conversation

权限(scope): messages:conversation:write · 调用方式: 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.

参数

名字 位置 类型 必填 说明
subconversation_id path string (uuid) 是 Sub-conversation UUID

请求体

application/json · UpdateSubConversationRequestBody

字段 类型 必填 说明
title string 是 New display title; empty clears it.

回包

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

Archive a context sub-conversation

权限(scope): messages:conversation:write · 调用方式: 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.

参数

名字 位置 类型 必填 说明
subconversation_id path string (uuid) 是 Sub-conversation UUID

回包