Apps API · Messages
Messages: 19 个接口
GET /api/v1/conversations/{conversation_id}/changes
List conversation changes
权限(scope): messages:message:read · 调用方式: appToken · operationId: list-conversation-changes
Required app scope: messages:message:read.
Returns one page of the conversation change log after since_change_seq: edits, recalls, silent deletes, reaction changes and card settlements of existing messages. New messages are not listed here; fetch them with list-messages after_seq. Refetch the listed messages with batch-get-messages. Requires a member identity and read access to the conversation. Response wrapped in standard envelope.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
conversation_id |
path | string (uuid) | 是 | Conversation UUID |
since_change_seq |
query | integer (int64) | Exclusive cursor: the caller has seen every change <= this value; the response lists the changes after it. 0 is a valid position meaning nothing seen yet. There is no head-only mode: initialize the watermark from head_change_seq of list-messages, batch-get-messages or this endpoint. | |
limit |
query | integer (int32) | Change-log entries scanned per page (default 100). The page can hold fewer changes than this because a message appears at most once per page. |
回包
200OK —application/json·DataResponseConversationChangesResultBodydefaultError —application/problem+json·D8Error
POST /api/v1/conversations/{conversation_id}/interaction-requests
Ask for an interaction
权限(scope): messages:message:send · 调用方式: appToken · operationId: request-interaction
Required app scope: messages:message:send.
Posts a card that asks the humans in a conversation for an interaction, and returns the card's id along with the server-generated option ids. The caller describes what it wants in semantic terms — a title, a body, the choices — and the platform builds the card. It supplies no operation, URL, method, handler key or business parameters, and does not name the option ids. Response wrapped in standard envelope.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
conversation_id |
path | string | 是 | Conversation the card is posted into |
请求体
application/json · RequestInteractionRequestBody
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
agent_run |
object | Optional opaque agent run summary attached to the card (agent execution visibility, schema_version 2). Kept unchanged, only for agent senders, only when its encoded size is at most 16 KiB and only while agent activity is enabled; otherwise it is dropped silently and the card is still sent. | |
choice |
ChoiceInteractionInput |
Required when interaction_type is choice | |
client_msg_id |
string | Caller-generated dedup key for the send itself. At most 64 characters; a longer value is rejected. | |
form |
FormInteractionInput |
Required when interaction_type is form | |
interaction_type |
string: choice, form |
是 | Which kind of interaction this requests. The protocol reserves select_resource and domain_gate; an unknown value is refused here because this endpoint has to pick a variant for it. |
回包
200OK —application/json·DataResponseInteractionRequestResultBodydefaultError —application/problem+json·D8Error
POST /api/v1/conversations/{conversation_id}/mention-read
Mark @mentions read
权限(scope): messages:read_state:write · 调用方式: appToken · operationId: mark-mentions-read
Required app scope: messages:read_state:write.
Marks the listed messages' @mentions read for the caller. Idempotent: ids already read are counted out of marked rather than erroring, and an empty list is a valid no-op that still runs the access check. Response wrapped in standard envelope.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
conversation_id |
path | string (uuid) | 是 | Conversation UUID |
请求体
application/json · MarkMentionsReadRequestBody
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
message_ids |
array of string | 是 | Message ids whose @mention the caller has read. An empty list is a valid no-op. A non-numeric id is rejected outright rather than skipped, so the reported count can never be smaller than what the caller asked for. |
回包
200OK —application/json·DataResponseMarkMentionsReadResultBodydefaultError —application/problem+json·D8Error
POST /api/v1/conversations/{conversation_id}/mention-read-all
Mark every @mention in a conversation read
权限(scope): messages:read_state:write · 调用方式: appToken · operationId: mark-all-mentions-read
Required app scope: messages:read_state:write.
Marks ALL of the caller's unread @mentions in this conversation read, including ones beyond the current page of unread-mentions. Backs the client's "mark all read" gesture: that gesture must not be replayed through mention-read, which can only carry the ids the client currently holds — one page — while the badge counts every unread mention. Idempotent; returns how many mentions it marked read. Response wrapped in standard envelope.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
conversation_id |
path | string (uuid) | 是 | Conversation UUID |
回包
200OK —application/json·DataResponseMarkMentionsReadResultBodydefaultError —application/problem+json·D8Error
GET /api/v1/conversations/{conversation_id}/messages
List messages
权限(scope): messages:message:read · 调用方式: appToken · operationId: list-messages
Required app scope: messages:message:read.
Returns messages with seq-based pagination. When neither before_seq nor after_seq is provided, returns the most recent messages (latest window). Results are always in ascending seq order regardless of pagination direction. pagination.next_cursor always continues toward older messages (pass it as before_seq). Supply around_seq to fetch a window centered on a given seq (e.g. a conversation's last_read_seq) in a single request; that window can be continued in both directions — see the around_seq parameter for details. Response wrapped in standard envelope.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
conversation_id |
path | string (uuid) | 是 | Conversation UUID |
before_seq |
query | integer (int64) | Return messages with seq less than this value (scroll up / load older). Results are always returned in ascending seq order. | |
after_seq |
query | integer (int64) | Return messages with seq greater than this value (scroll down / load newer). Results are always returned in ascending seq order. | |
around_seq |
query | integer (int64) | Center a window on this seq (e.g. a conversation's last_read_seq) in a single request. The window contains messages straddling around_seq: roughly the lower half are the read context with seq < around_seq and the upper half are the anchor message (seq == around_seq) plus the unread messages with seq > around_seq. Results are returned in ascending seq order. The response carries anchor_found / anchor_seq and a cursor for each direction: pagination.next_cursor continues older (pass it as before_seq) and pagination.newer_cursor continues newer (pass it as after_seq); each is empty only when that side has no more messages. A hard-deleted anchor still returns its neighborhood with anchor_found=false; an around_seq past the newest message returns the latest window with anchor_found=false and no anchor_seq. Takes precedence over before_seq/after_seq when set (> 0); has no effect when <= 0. | |
limit |
query | integer (int32) | Items per page (default: 20) |
回包
200OK —application/json·ListMessagesResponseBodydefaultError —application/problem+json·D8Error
POST /api/v1/conversations/{conversation_id}/messages
Send message
权限(scope): messages:message:send · 调用方式: appToken · operationId: send-message
Required app scope: messages:message:send.
Sends a message to a conversation using the full MessageContent shape. Response wrapped in standard envelope.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
conversation_id |
path | string (uuid) | 是 | Conversation UUID |
请求体
application/json · SendMessageRequestBody
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
agent_run |
object | Optional opaque agent run summary (agent execution visibility, schema_version 2). Kept unchanged, only for agent senders, only when its encoded size is at most 16 KiB and only while agent activity is enabled; otherwise it is dropped silently and the message is still sent. Replaces the retired metadata.agent_run key, which is now stripped from metadata. | |
client_msg_id |
string | 是 | Client idempotency key. At most 64 characters; a longer value is rejected. |
content |
MessageContentItem |
是 | Message content |
fallback_text |
string | Preview/fallback text — the short plaintext the conversation list shows for non-text messages. Required for card messages; omit and the platform derives it from the card body: the card title in black lenticular brackets (U+3010 / U+3011) followed by the summary. Capped at 8192 UTF-8 bytes by the platform. | |
mentions |
array of MentionInput |
Structured @mention targets. The platform does not parse @names from the message text; this array is the only mention source. | |
metadata |
object | Optional metadata | |
parent_id |
string | Parent message ID for reply | |
priority |
integer (int32) | 1=urgent, 2=high, 3=normal; omit defaults to normal. In a DM to your own agent, normal is floored to high. | |
thread_id |
string (uuid) | Thread UUID | |
ttl |
integer (int32) | Time to live in seconds | |
type |
string: UNSPECIFIED, TEXT, IMAGE, FILE, AUDIO, VIDEO, SYSTEM, AGENT_TEXT, AGENT_STRUCTURED, AGENT_CARD, AGENT_STREAM |
是 | Message type |
回包
200OK —application/json·DataResponseSendMessageResultBodydefaultError —application/problem+json·D8Error
POST /api/v1/conversations/{conversation_id}/messages/batch-get
Batch get messages
权限(scope): messages:message:read · 调用方式: appToken · operationId: batch-get-messages
Required app scope: messages:message:read.
Returns the current version of up to 100 messages of one conversation, rendered exactly like list-messages, plus the change-log head as of those messages. Ids beyond the card cap come back in deferred_ids; deleted or foreign ids in missing_ids. Requires a member identity and read access to the conversation. Response wrapped in standard envelope.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
conversation_id |
path | string (uuid) | 是 | Conversation UUID |
请求体
application/json · BatchGetMessagesRequestBody
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
message_ids |
array of string | 是 | IDs of messages in this conversation to fetch, at most 100 (message ids are int64, carried as decimal strings) |
回包
200OK —application/json·DataResponseBatchGetMessagesResultBodydefaultError —application/problem+json·D8Error
POST /api/v1/conversations/{conversation_id}/messages/search
Search messages in a conversation
权限(scope): messages:message:read · 调用方式: appToken · operationId: search-conversation-messages
Required app scope: messages:message:read.
Searches messages within a single conversation using full-text search. Returns matching messages with highlighted snippets. Results are limited to this conversation. Only currently visible messages are returned: every hit is re-checked against the current message and recalled, deleted and since-edited messages are dropped, so a page can hold fewer than limit items, even none. Keep paging while pagination.next_cursor is non-empty; a short page is not the last page. No total count is returned. Response wrapped in standard envelope.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
conversation_id |
path | string (uuid) | 是 | Conversation UUID |
请求体
application/json · SearchMessagesRequestBody
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
cursor |
string | Pagination cursor | |
limit |
integer (int32) | Items per page (default: 20, max: 100) | |
query |
string | 是 | Search query |
回包
200OK —application/json·CursorListResponseMessageSearchHitItemBodydefaultError —application/problem+json·D8Error
GET /api/v1/conversations/{conversation_id}/messages/{message_id}
Get message
权限(scope): messages:message:read · 调用方式: appToken · operationId: get-message
Required app scope: messages:message:read.
Returns a message with expanded content (the content is always included). Response wrapped in standard envelope.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
conversation_id |
path | string (uuid) | 是 | Conversation UUID |
message_id |
path | string | 是 | Message UUID |
回包
200OK —application/json·DataResponseGetMessageResultBodydefaultError —application/problem+json·D8Error
GET /api/v1/conversations/{conversation_id}/unread-mentions
List the caller's unread @mentions in a conversation
权限(scope): messages:read_state:read · 调用方式: appToken · operationId: list-unread-mentions
Required app scope: messages:read_state:read.
Returns the caller's still-unread @mentions in one conversation, oldest first, for the @mention jump queue. The response carries per-type totals that are NOT subject to the page limit — render counts from those, not from the array length. Response wrapped in standard envelope.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
conversation_id |
path | string (uuid) | 是 | Conversation UUID |
limit |
query | integer (int32) | Max entries per page (default: server default 200, ceiling 500). Note the totals in the response are NOT limited by this. |
回包
200OK —application/json·DataResponseMentionQueueResultBodydefaultError —application/problem+json·D8Error
DELETE /api/v1/messages/{message_id}
Recall message
权限(scope): messages:message:write · 调用方式: appToken · operationId: recall-message
Required app scope: messages:message:write.
Recalls the caller's own message: its content is removed and members see it as recalled (message.recalled WS event). Response wrapped in standard envelope.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
message_id |
path | string | 是 | Message UUID |
回包
200OK —application/json·DataResponseRecallMessageResultBodydefaultError —application/problem+json·D8Error
PUT /api/v1/messages/{message_id}
Edit message
权限(scope): messages:message:write · 调用方式: appToken · operationId: edit-message
Required app scope: messages:message:write.
Replaces the content of the caller's own message within the platform's 15-minute edit window. The previous revision is archived (see list-message-edits) and members converge via the message.updated WS event. Response wrapped in standard envelope.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
message_id |
path | string | 是 | Message UUID |
请求体
application/json · EditMessageRequestBody
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
content |
MessageContentItem |
是 | Replacement content (full MessageContent shape) |
fallback_text |
string | Replacement preview/fallback text — the short plaintext the conversation list shows for non-text messages. Omit to leave the stored value unchanged. Capped at 8192 UTF-8 bytes by the platform. | |
type |
string: UNSPECIFIED, TEXT, IMAGE, FILE, AUDIO, VIDEO, SYSTEM, AGENT_TEXT, AGENT_STRUCTURED, AGENT_CARD, AGENT_STREAM |
Replacement message kind, e.g. editing an image message into pure text so neither the bubble nor the conversation-list preview renders it as an image. Omit to leave the kind unchanged. |
回包
200OK —application/json·DataResponseEditMessageResultBodydefaultError —application/problem+json·D8Error
POST /api/v1/messages/{message_id}/card-actions/{action_id}/interactions
Invoke a card action
权限(scope): messages:card:interact · 调用方式: appToken · operationId: invoke-card-action
Required app scope: messages:card:interact.
Performs one click on an interactive card's action button and returns the resulting interaction record. The server resolves (message_id, action_id) into a verified action, runs that action as the clicking member, and records the interaction only after the action succeeds. A business failure records nothing and is returned as-is — the card stays clickable and the retry is absorbed by the business's idempotency. The caller supplies no business parameters; they come from the resolve step. Response wrapped in standard envelope.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
message_id |
path | string | 是 | The card message's ID (an int64 carried as a decimal string) |
action_id |
path | string | 是 | Card-local id of the clicked action; must be a kind=operation action |
Idempotency-Key |
header | string | 是 | One value per click, generated by the caller and passed through unchanged. It is the business execution key as well as the interaction dedup key, so a retry of the same click must reuse it. Max 64 UTF-8 bytes. |
X-Correlation-Id |
header | string | Optional opaque key echoed into the interaction record and its event. Max 64 UTF-8 bytes. |
回包
200OK —application/json·DataResponseCardInteractionResultBodydefaultError —application/problem+json·D8Error
POST /api/v1/messages/{message_id}/card-choices/interactions
Answer a display card
权限(scope): messages:card:interact · 调用方式: appToken · operationId: settle-card-choice
Required app scope: messages:card:interact.
Records one answer to a display card's quick-reply options. Unlike invoking an operation action this is a single hop: a choice has no business call behind it, so the interaction record is the whole effect and there is no window where an effect exists without a record. The first answer to a card wins; a later answer returns that first record with replayed=true rather than an error, and selected_action_ids carries the answer that won rather than the one just submitted. Response wrapped in standard envelope.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
message_id |
path | string | 是 | The card message's ID (an int64 carried as a decimal string) |
Idempotency-Key |
header | string | 是 | One value per click, generated by the caller. A retry of the same click must reuse it. Max 64 UTF-8 bytes. |
X-Correlation-Id |
header | string | Optional opaque key echoed into the interaction record and its event. Max 64 UTF-8 bytes. |
请求体
application/json · SettleCardChoiceRequestBody
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
selected_action_ids |
array of string | 是 | Card-local ids of the chosen options. For selection_mode=single this is exactly one id. |
selection_mode |
string | 是 | How many options the card accepts. The protocol reserves 'multiple'; the platform serves only 'single' today and fails closed on anything else. |
回包
200OK —application/json·DataResponseCardChoiceResultBodydefaultError —application/problem+json·D8Error
GET /api/v1/messages/{message_id}/card-interactions
List card interactions
权限(scope): messages:message:read · 调用方式: appToken · operationId: list-card-interactions
Required app scope: messages:message:read.
Returns the audit trail of one card message — every recorded click, newest first. Repeat clicks are kept, while the card_state embedded in the message only reflects the latest settled one. Response wrapped in standard envelope.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
message_id |
path | string | 是 | The card message's ID (an int64 carried as a decimal string) |
cursor |
query | string | Pagination cursor (opaque, from previous response; omit for first page) | |
limit |
query | integer (int32) | Items per page (default: 50, max: 200) |
回包
200OK —application/json·CursorListResponseCardInteractionAuditItemBodydefaultError —application/problem+json·D8Error
POST /api/v1/messages/{message_id}/card-interactions
Answer or act on a card
权限(scope): messages:card:interact · 调用方式: appToken · operationId: submit-card-interaction
Required app scope: messages:card:interact.
Records one interaction with a card message: a quick-reply choice, a form submit, or an operation action click, selected by interaction_type. Each type behaves exactly as its dedicated endpoint does (card-choices/interactions and card-actions/{action_id}/interactions remain and share the same handling). A choice or form card is settled by its first answer; a later answer returns that first record with replayed=true and the winning answer, rather than an error. Response wrapped in standard envelope.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
message_id |
path | string | 是 | The card message's ID (an int64 carried as a decimal string) |
Idempotency-Key |
header | string | 是 | One value per click or submit, generated by the caller. A retry of the same one must reuse it. For an action it is also the business execution key. Max 64 UTF-8 bytes. |
X-Correlation-Id |
header | string | Optional opaque key echoed into the interaction record and its event. Max 64 UTF-8 bytes. |
请求体
application/json · SubmitCardInteractionRequestBody
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
action |
CardActionSubmitInput |
Required when interaction_type is action | |
choice |
CardChoiceSubmitInput |
Required when interaction_type is choice | |
form |
CardFormSubmitInput |
Required when interaction_type is form | |
interaction_type |
string: choice, form, action |
是 | Which kind of card interaction this is; selects the one payload object that must accompany it. |
回包
200OK —application/json·DataResponseCardInteractionSubmitResultBodydefaultError —application/problem+json·D8Error
GET /api/v1/messages/{message_id}/edits
List message edit history
权限(scope): messages:message:read · 调用方式: appToken · operationId: list-message-edits
Required app scope: messages:message:read.
Returns the archived pre-edit revisions of a message, oldest first. Readable by conversation members and observers. Response wrapped in standard envelope.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
message_id |
path | string | 是 | Message UUID |
回包
200OK —application/json·DataResponseListMessageEditsResultBodydefaultError —application/problem+json·D8Error
POST /api/v1/messages/{message_id}/reactions
Add message reaction
权限(scope): messages:reaction:write · 调用方式: appToken · operationId: add-message-reaction
Required app scope: messages:reaction:write.
Adds the caller's reaction to a message. Idempotent: re-adding an existing reaction succeeds without effect. The response carries no reaction state, only the change_seq of the write; clients converge via the message.reaction.added WS event or by refetching messages. Response wrapped in standard envelope.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
message_id |
path | string | 是 | Message UUID |
请求体
application/json · AddMessageReactionRequestBody
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
reaction_code |
string | 是 | Reaction code from the server-side reaction registry (e.g. thumbs_up, heart) |
回包
200OK —application/json·DataResponseReactionChangeResultBodydefaultError —application/problem+json·D8Error
DELETE /api/v1/messages/{message_id}/reactions/{reaction_code}
Remove message reaction
权限(scope): messages:reaction:write · 调用方式: appToken · operationId: remove-message-reaction
Required app scope: messages:reaction:write.
Removes the caller's reaction from a message. Idempotent: removing an absent reaction succeeds without effect. Clients converge via the message.reaction.removed WS event or by refetching messages. Response wrapped in standard envelope.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
message_id |
path | string | 是 | Message UUID |
reaction_code |
path | string | 是 | Reaction code from the server-side reaction registry |
回包
200OK —application/json·DataResponseReactionChangeResultBodydefaultError —application/problem+json·D8Error
