OpenMax
Free Trial

Apps API · Messages

Messages: 19 endpoints

← All groups

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

List conversation changes

Scope: messages:message:read · Called with: 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.

Parameters

Name In Type Required Description
conversation_id path string (uuid) yes 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.

Responses

POST /api/v1/conversations/{conversation_id}/interaction-requests

Ask for an interaction

Scope: messages:message:send · Called with: 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.

Parameters

Name In Type Required Description
conversation_id path string yes Conversation the card is posted into

Request body

application/json · RequestInteractionRequestBody

Field Type Required Description
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 yes 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.

Responses

POST /api/v1/conversations/{conversation_id}/mention-read

Mark @mentions read

Scope: messages:read_state:write · Called with: 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.

Parameters

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

Request body

application/json · MarkMentionsReadRequestBody

Field Type Required Description
message_ids array of string yes 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.

Responses

POST /api/v1/conversations/{conversation_id}/mention-read-all

Mark every @mention in a conversation read

Scope: messages:read_state:write · Called with: 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.

Parameters

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

Responses

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

List messages

Scope: messages:message:read · Called with: 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.

Parameters

Name In Type Required Description
conversation_id path string (uuid) yes 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)

Responses

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

Send message

Scope: messages:message:send · Called with: 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.

Parameters

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

Request body

application/json · SendMessageRequestBody

Field Type Required Description
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 yes Client idempotency key. At most 64 characters; a longer value is rejected.
content MessageContentItem yes 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 yes Message type

Responses

POST /api/v1/conversations/{conversation_id}/messages/batch-get

Batch get messages

Scope: messages:message:read · Called with: 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.

Parameters

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

Request body

application/json · BatchGetMessagesRequestBody

Field Type Required Description
message_ids array of string yes IDs of messages in this conversation to fetch, at most 100 (message ids are int64, carried as decimal strings)

Responses

POST /api/v1/conversations/{conversation_id}/messages/search

Search messages in a conversation

Scope: messages:message:read · Called with: 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.

Parameters

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

Request body

application/json · SearchMessagesRequestBody

Field Type Required Description
cursor string Pagination cursor
limit integer (int32) Items per page (default: 20, max: 100)
query string yes Search query

Responses

GET /api/v1/conversations/{conversation_id}/messages/{message_id}

Get message

Scope: messages:message:read · Called with: 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.

Parameters

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

Responses

GET /api/v1/conversations/{conversation_id}/unread-mentions

List the caller's unread @mentions in a conversation

Scope: messages:read_state:read · Called with: 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.

Parameters

Name In Type Required Description
conversation_id path string (uuid) yes 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.

Responses

DELETE /api/v1/messages/{message_id}

Recall message

Scope: messages:message:write · Called with: 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.

Parameters

Name In Type Required Description
message_id path string yes Message UUID

Responses

PUT /api/v1/messages/{message_id}

Edit message

Scope: messages:message:write · Called with: 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.

Parameters

Name In Type Required Description
message_id path string yes Message UUID

Request body

application/json · EditMessageRequestBody

Field Type Required Description
content MessageContentItem yes 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.

Responses

POST /api/v1/messages/{message_id}/card-actions/{action_id}/interactions

Invoke a card action

Scope: messages:card:interact · Called with: 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.

Parameters

Name In Type Required Description
message_id path string yes The card message's ID (an int64 carried as a decimal string)
action_id path string yes Card-local id of the clicked action; must be a kind=operation action
Idempotency-Key header string yes 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.

Responses

POST /api/v1/messages/{message_id}/card-choices/interactions

Answer a display card

Scope: messages:card:interact · Called with: 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.

Parameters

Name In Type Required Description
message_id path string yes The card message's ID (an int64 carried as a decimal string)
Idempotency-Key header string yes 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.

Request body

application/json · SettleCardChoiceRequestBody

Field Type Required Description
selected_action_ids array of string yes Card-local ids of the chosen options. For selection_mode=single this is exactly one id.
selection_mode string yes How many options the card accepts. The protocol reserves 'multiple'; the platform serves only 'single' today and fails closed on anything else.

Responses

GET /api/v1/messages/{message_id}/card-interactions

List card interactions

Scope: messages:message:read · Called with: 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.

Parameters

Name In Type Required Description
message_id path string yes 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)

Responses

POST /api/v1/messages/{message_id}/card-interactions

Answer or act on a card

Scope: messages:card:interact · Called with: 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.

Parameters

Name In Type Required Description
message_id path string yes The card message's ID (an int64 carried as a decimal string)
Idempotency-Key header string yes 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.

Request body

application/json · SubmitCardInteractionRequestBody

Field Type Required Description
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 yes Which kind of card interaction this is; selects the one payload object that must accompany it.

Responses

GET /api/v1/messages/{message_id}/edits

List message edit history

Scope: messages:message:read · Called with: 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.

Parameters

Name In Type Required Description
message_id path string yes Message UUID

Responses

POST /api/v1/messages/{message_id}/reactions

Add message reaction

Scope: messages:reaction:write · Called with: 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.

Parameters

Name In Type Required Description
message_id path string yes Message UUID

Request body

application/json · AddMessageReactionRequestBody

Field Type Required Description
reaction_code string yes Reaction code from the server-side reaction registry (e.g. thumbs_up, heart)

Responses

DELETE /api/v1/messages/{message_id}/reactions/{reaction_code}

Remove message reaction

Scope: messages:reaction:write · Called with: 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.

Parameters

Name In Type Required Description
message_id path string yes Message UUID
reaction_code path string yes Reaction code from the server-side reaction registry

Responses