Data model
The data passed between the host and the components — messages, conversations, members, attachments, read state, and the types for sending, editing, paging and drafts — field by field.
Data model
The host's capabilities send and receive the types on this page, exported from @openmaxai/chat/host. ChatMemberKind, ChatMentionInput and names for the nested objects (each entry of mentions, reactions and agent_collab_participants; card_state, dm, group, last_message_preview) are exported there too Planned. How each method is used and what to do on errors: Host capabilities.
All of these types are defined by the SDK and refer to no backend's types, OpenMax's included. Fields are named in two styles:
- Messages, conversations, attachments, conversation participants:
ChatMessage,ChatConversation,ChatAttachment,ChatConversationParticipant. Field names are the same as OpenMax's, in snake case (sender_id,created_at). For another backend, the adapter maps your records into these fields; see Known limitations. - Other types: send input, pages, members, drafts, read snapshots and so on, in camel case (
conversationId,nextCursor).
Fields marked "No" under Required may be left out; what happens then is in the description. Times are ISO 8601 strings (such as "2026-10-05T10:00:00Z") unless noted.
Messages
ChatMessage
One record in a conversation.
| Field | Type | Required | Meaning |
|---|---|---|---|
id |
string |
Yes | Message id |
conversation_id |
string |
Yes | The conversation it belongs to |
seq |
number |
Yes | Sequence number within the conversation: an integer, from 1 up, no repeats. Ordering, gap filling and read positions all use it; a timestamp cannot stand in. See Realtime and sync · Sequence numbers |
type |
See Message types | Yes | Decides how it is drawn |
sender_id |
string |
Yes | Member id of the sender, matching ChatParticipant.memberId |
sender_type |
"UNSPECIFIED" | "HUMAN" | "AGENT" | "SYSTEM" |
Yes | Sender category. The UI tells people from agents by the member's kind, not by this field |
content |
string |
No | The body; see Body |
content_version |
number |
Yes | Body version, starting at 1. Must grow on every edit; the UI redraws the message when it changes |
fallback_text |
string |
No | One line shown when the message cannot be drawn: unknown types, cards, structured messages |
attachments |
ChatAttachment[] | null |
No | Attachments in display order; see ChatAttachment |
mentions |
See Mentions | No | Who this message @-mentions |
parent_id |
string |
No | Reply: id of the quoted message. When it is outside the loaded range, the UI fetches it with messaging.loadMessage |
reactions |
See Reactions | No | Reactions, totalled per emoji |
created_at |
string |
Yes | Creation time. Date dividers and the edit window use it |
timestamp |
string |
Yes | Message time recorded by the server. The UI shows created_at |
edited_at |
string |
No | Time of the last edit; when set, the bubble shows "(edited)" |
deleted_at |
string |
No | Recall time; when set, the message is drawn as a recall notice and its body and reactions are hidden |
recalled_by |
string |
No | Member id of whoever recalled it |
recalled_by_role |
"sender" | "admin" |
No | Recalled by the sender, or by the group owner or an admin |
pinned_at Planned |
string |
No | When it was pinned; when set, the time row shows a pin. See Message thread · Pinning |
pinned_by Planned |
string |
No | Member id of whoever pinned it |
client_msg_id |
string |
No | Deduplication key given by the sender, returned as-is on reads. Optimistic sending uses it to swap the local copy for the server's; see ChatStoreSendStartedEvent |
metadata |
Record<string, unknown> |
No | Passed-through metadata. When a system message's metadata.system_action is "member_left" (someone left) or "owner_changed" (new group owner), the UI writes the text itself from member names |
metadata.quote_excerpts |
{ version: 1, items: [{ message_id, text, offset?, truncated? }] } |
No | The text the sender selected from the quoted message (message_id equals parent_id; text is plain text, at most 1000 code points). When that message is recalled, the backend may rewrite an item to { message_id, recalled: true }, and the quote shows "recalled". The UI treats a missing block, version other than 1, a bad shape, or message_id ≠ parent_id as no excerpt and shows the whole-message quote; unknown fields are ignored |
metadata.forwarded_from |
{ version: 1, sender_id, sender_type, sender_name, sent_at?, source_kind? } |
No | Set by the server on a forwarded copy: the original author, a snapshot taken at forward time. The bubble shows no source label (a forwarded copy renders like an ordinary message) and offers no edit. A missing block, version other than 1 or a bad shape reads as not forwarded |
metadata.run_id Planned |
string |
No | Which run an agent's final reply belongs to |
metadata.stream_message_id Planned |
string |
No | Which streaming preview this reply replaces: the messageId of that text's TEXT_MESSAGE_* events. See Message thread · Streaming output |
card_body and others |
No | Fields of card messages; see Card fields | |
chat_history_preview |
Record<string, unknown> |
No | "CHAT_HISTORY" only: the list projection of a merged forward (cws.chat_history.preview.v1: title, record count, the first records). The full record list is the body (cws.chat_history.v1) of the single message from messaging.loadMessage |
priority |
number |
Yes | 1 urgent, 2 high, 3 normal. Not used by the UI |
org_id |
string |
Yes | Organization. Not used by the UI |
delivery_status |
"sending" | "sent" | "failed" | "blocked" |
No | Local send state, written by the SDK, never by the host. blocked means the server's content filter stopped it |
blocked_refusal_text |
string |
No | Explanation shown after a blocked message, written by the SDK |
Message types
type |
How it is drawn |
|---|---|
"TEXT" |
Text bubble; the body is Markdown and goes to render.renderMessageText, which draws it as Markdown Planned |
"IMAGE", "FILE" |
Images or files from attachments; the body is the caption. A message whose attachments are all images is "IMAGE", otherwise "FILE" |
"AGENT_TEXT" |
Agent reply; the body goes to render.renderMarkdown |
"AGENT_STRUCTURED" |
Drawn by the message-display plugin that claims it; shows fallback_text when no plugin does |
"CARD" |
Interactive card, content in card_body |
"SYSTEM" |
One centered line of system notice |
"CHAT_HISTORY" |
A merged forward: a chat history card with a localized title, up to 4 "sender: content" lines and the record count, read from the body or chat_history_preview. Clicking opens the full records; with only the preview, the UI fetches the message once with messaging.loadMessage. Shows fallback_text when neither is readable |
"AUDIO", "VIDEO", "AGENT_STREAM", "AGENT_CARD", "INTERACTION_RECEIPT", "UNSPECIFIED" |
No dedicated rendering; shows the body or fallback_text |
Every message is first offered to the installed message-display plugins (except the built-in kinds); a plugin that claims it draws the body. See Custom message rendering.
Body
content is a string, in either form:
- A JSON object, such as
{"text":"hello"}.textis the body; for image and file messages it is the caption. - Plain text, such as
hello. The whole string is the body.
The UI takes the body from the JSON text, then fallback_text, then the raw content.
Mentions
mentions is an array of:
| Field | Type | Required | Meaning |
|---|---|---|---|
mentioned_id |
string |
Yes | Member id of the mentioned person |
username |
string |
No | Name captured when mentioned; may be out of date |
is_mention_all |
boolean |
Yes | This row comes from expanding @all / @all agents, not a direct mention |
The server does not parse @ text in the body; this array is the only source of mentions, and render uses it to tell whether a message mentions the current user. How to send mentions: SendMessageInput.
Reactions
reactions is an array, one entry per emoji:
| Field | Type | Required | Meaning |
|---|---|---|---|
code |
string |
Yes | Emoji code, such as thumbs_up |
count |
number |
Yes | How many people reacted with it |
reacted_by_me |
boolean |
Yes | Whether the current user did |
reactor_ids |
string[] | null |
No | Member ids of reactors, at most the first 20; count can be larger |
unicode_fallback |
string |
Yes | Character shown when the UI does not know the code |
Codes in the emoji picker: thumbs_up, smile, heart, tada, eyes, joy, fire, white_check_mark, ok_hand, x, hourglass, warning.
Card fields
| Field | Type | Required | Meaning |
|---|---|---|---|
card_body |
Record<string, unknown> |
No | The full card (cws.card.v1); structure in Interactive cards · Card structure |
card_preview |
Record<string, unknown> |
No | A trimmed preview (cws.card.preview.v1) with no action buttons. Only one of it and card_body is present |
card_truncated |
boolean |
No | card_preview was sent; the UI shows "Expand", which calls cards.expandBody |
card_state |
See below | No | The latest answer; absent when nobody has answered |
card_superseded |
boolean |
No | A later card replaced this one; an answered card follows card_state |
card_expired |
boolean |
No | The answer window has passed |
card_state: action_id (which button), actor_id (who), result_at (click time), status (answer status, whose only value is "succeeded"), all required. How the result line looks: Interactive cards · Results.
Conversations
ChatConversation
| Field | Type | Required | Meaning |
|---|---|---|---|
id |
string |
Yes | Conversation id |
type |
"DM" | "GROUP" | "STRAT" | "BROADCAST" | "BRIDGE" |
Yes | See Conversation types |
name |
string | null |
Yes | Group name. Usually null for a DM, where the UI shows the other person's name |
avatar_url |
string | null |
No | Group avatar. DMs use dm.peer_avatar_url |
last_message_at |
string |
Yes | Time of the last message; the conversation list sorts by it |
last_message_preview |
See Last message | No | The preview shown in the list |
unread_count |
number |
Yes | Unread messages for the current user |
unread_mention |
"none" | "direct" | "all" |
No | Whether there is an unread @: direct is @me, all is @all; direct wins |
last_read_seq |
number |
No | The seq the current user has read up to. Anchors the unread divider when the conversation opens; see Message thread |
pinned |
boolean |
No | The current user pinned it |
done |
boolean |
No | The current user hid it; hidden from the default list, shown in search |
muted |
boolean |
No | The current user muted it. Not counted in the total unread count; the conversation's own unread count is shown as usual |
owner_id |
string |
No | Member id of the group owner |
can_mention_all |
boolean |
No | Whether the current user may @all. Treated as no when absent |
is_observed |
boolean |
No | The current user is an observer: they see this conversation only because they observe one of its members (such as their own agent). Not counted as unread, and not counted in the total unread count |
observed_member_ids |
string[] |
No | Member ids being observed |
agent_collab_participants |
See below | No | Participants of an agent collaboration; the list shows them as "A ⇄ B" |
dm |
See DM details | No | Present when type is "DM" |
group |
{ description: string; admin_count: number } |
No | Present when type is "GROUP". description is the group description, shown and edited in the group info panel |
created_at, member_count, archived_at, is_observer, last_message_id, read_receipt_mode, can_send, read_only_reason, agent_member_id, broadcast, bridge |
Not used by the UI |
created_at, member_count and is_observer are required by the type; the rest are optional.
Each agent_collab_participants entry: member_id, kind ("agent" \| "human" \| "system"), display_name, avatar_url?, status ("active" \| "suspended" \| "departed").
Pinned and hidden are the current user's own state; change them with conversations.setPinned and conversations.setHidden, see Host capabilities · conversations.
Conversation types
type |
What it is | In the list |
|---|---|---|
"DM" |
Direct message. Carries the Agent badge when the other side is an agent (dm.peer_kind is "agent") |
Shown |
"GROUP" |
Group chat | Shown, with the "Group" badge |
"BRIDGE" |
A collaboration between agents that the current user observes read-only | Shown, with the "Agent collaboration" badge |
"BROADCAST" |
Channel | Not shown |
"STRAT" |
Reserved for the server | Shown, no badge |
DM details
dm:
| Field | Type | Required | Meaning |
|---|---|---|---|
peer_member_id |
string |
Yes | Member id of the other person |
peer_display_name |
string |
No | Their name |
peer_avatar_url |
string | null |
No | Their avatar |
peer_kind |
"human" | "agent" | "system" |
No | Person, agent or system |
peer_status |
"active" | "suspended" | "departed" |
No | Their status in the organization; departed marks them as gone in the list |
can_send |
boolean |
No | When false, the composer is replaced by a read-only banner |
read_only_reason |
"peer_suspended" | "peer_departed" | "system_dm_readonly" |
No | Why it is read-only; picks the banner text |
billing_suspended |
boolean |
No | The other agent is stopped for billing reasons; only true counts, absent means not stopped. A notice only; sending stays allowed |
billing_suspension_reason |
string |
No | Why; picks the notice text. Unknown values get the generic text |
Last message
last_message_preview:
| Field | Type | Required | Meaning |
|---|---|---|---|
id |
number |
Yes | Message id |
sender_id |
string |
Yes | Sender |
sender_type |
string |
Yes | Sender category |
type |
string |
Yes | Message type; images and files show as "[Image]" and "[File]" |
content |
string | null |
No | Body |
fallback_text |
string | null |
No | One line for when the body cannot be drawn |
timestamp |
number |
Yes | Milliseconds since the Unix epoch |
edited_at |
number | null |
No | Milliseconds |
When there is a draft, the list shows the draft instead, taken from drafts.previews().
ChatConversationPage
Returned by conversations.list.
| Field | Type | Required | Meaning |
|---|---|---|---|
conversations |
readonly ChatConversation[] |
Yes | This page of conversations |
nextCursor |
string |
No | Present when there is another page; passed back as-is to the next list |
CreateConversationInput
Argument of messaging.createConversation.
| Field | Type | Required | Meaning |
|---|---|---|---|
memberIds |
readonly string[] |
Yes | Member ids, including the current user. "Message someone" in the conversation list passes the current user and the other person |
title |
string |
No | Conversation name |
Groups are created with groupManagement.createGroup, which takes a ChatCreateGroupInput.
ChatCreateGroupInput
| Field | Type | Required | Meaning |
|---|---|---|---|
title |
string |
Yes | Group name |
description |
string |
No | Group description; left out (not an empty string) when the user typed none |
memberIds |
readonly string[] |
Yes | Member ids to add |
ChatGroupProfileUpdate
Argument of groupManagement.updateGroupProfile. The group info panel saves the name and the description separately, one field at a time.
| Field | Type | Required | Meaning |
|---|---|---|---|
name |
string |
No | New group name |
description |
string |
No | New group description |
ChatGroupMembersChangeResult
The result of groupManagement.addMembers / removeMembers. The server judges each person; the two lists together are every id passed in.
| Field | Type | Required | Meaning |
|---|---|---|---|
succeeded |
readonly string[] |
Yes | Member ids added / removed this time |
failed |
readonly { memberId: string; kind: ChatErrorKind; message?: string }[] |
Yes | The ones that did not go through: member id, failure kind (the same table as ChatSdkError's kind), and a user-facing message |
ChatGroupLeaveOptions
Options for groupManagement.leave.
| Field | Type | Required | Meaning |
|---|---|---|---|
newOwnerId |
string |
No | Who gets the group when the owner leaves; when not given the server decides |
ChatGroupLeaveResult
The result of groupManagement.leave: which branch the server took.
| Field | Type | Required | Meaning |
|---|---|---|---|
dissolved |
boolean |
Yes | After I left nobody could take the group (only Agents or nobody left) and the server dissolved it |
newOwnerId |
string |
No | Who the group went to when the owner left; absent when not the owner or when dissolved |
Members
The same person comes in different types in different places:
| Type | Comes from | Used for |
|---|---|---|
ChatParticipant |
identity.getMember, identity.listMembers |
Names and avatars on messages, @ candidates |
ChatDirectoryMember |
identity.searchDirectory |
Picking people to message, to create a group with or to add; organization members among @ candidates |
ChatConversationParticipant |
The participants prop of ChatInfoPanel |
The member list of the group info panel, picking a new owner |
ChatMemberProfile |
profileCard.loadProfile |
Profile card |
kind takes the same values on all of them: "human" | "agent" | "system", type name ChatMemberKind. The UI uses it to tell people from agents (for example the agent bubble color) and reads nothing else into it.
ChatParticipant
| Field | Type | Required | Meaning |
|---|---|---|---|
memberId |
string |
Yes | Member id |
displayName |
string |
Yes | Name |
avatarUrl |
string |
No | Avatar URL |
kind |
ChatMemberKind |
No | Treated as a person when absent |
displaySubtitle |
string |
No | One line under the name; the UI shows it without interpreting it |
modelLabel |
string | null |
No | The agent's current model, a read-only label next to the name; the host computes the text. Absent or null shows nothing |
ChatDirectoryMember
| Field | Type | Required | Meaning |
|---|---|---|---|
memberId |
string |
Yes | Member id |
displayName |
string |
Yes | Name |
avatarUrl |
string |
No | Avatar URL |
kind |
ChatMemberKind |
No | Treated as a person when absent |
isActive |
boolean |
Yes | Still an active member of the organization. Pickers list active members only; the host folds disabled, not-yet-joined and similar states into false |
billingSuspended |
boolean |
No | The member (an Agent) is stopped for billing reasons. The create-group and add-member pickers then show the suspension instead of online / offline. Absent or anything but true means not suspended; leave it out when your directory cannot tell |
creditCapReached |
boolean |
No | The member (an Agent) is stopped because its credit cap (daily or monthly) is reached. The same pickers then draw the same paused dot and say "credit cap" (on avatars that carry identity, that is with the presence port); a billing suspension wins when both are true. Absent or anything but true means not capped |
ChatDirectoryPage
| Field | Type | Required | Meaning |
|---|---|---|---|
members |
readonly ChatDirectoryMember[] |
Yes | This page of members |
nextCursor |
string |
No | Present when there is another page |
ChatConversationParticipant
A member for the group info panel, already joined with the organization directory.
| Field | Type | Required | Meaning |
|---|---|---|---|
member_id |
string |
Yes | Member id |
kind |
"human" | "agent" | "system" |
Yes | Person, agent or system |
display_name |
string |
Yes | Name |
avatar_url |
string | null |
Yes | Avatar URL |
online_status |
"online" | "starting" | "stopping" | "offline" | "error" | "unknown" |
No | Presence |
owner_member_id |
string |
No | The agent's owner |
ChatMemberProfile
The data of a profile card: ChatProfileEntity plus three fields. ChatProfileEntity is also used for the owner row and the "agents they own" list on the card.
| Field | Type | Required | Meaning |
|---|---|---|---|
memberId |
string |
Yes | Member id |
displayName |
string |
Yes | Name |
avatarUrl |
string | null |
No | Avatar URL |
kind |
ChatMemberKind |
No | "agent" shows the agent card, anything else the person card |
subtitle |
string | null |
No | Ready-made subtitle, such as a role or a model name |
onlineStatus |
string | null |
No | ChatMemberProfile only: presence on the agent card, passed as-is to the status dot |
ownerMemberId |
string |
No | ChatMemberProfile only: the agent's owner; the UI calls loadProfile again for the owner's data |
agentIdentityId |
string |
No | ChatMemberProfile only: "Copy agent ID" appears only when set |
Attachments
ChatAttachment
One attachment on a message. It carries no URL: the UI turns artifact_id into a usable URL with attachments.resolveUrls.
| Field | Type | Required | Meaning |
|---|---|---|---|
artifact_id |
string |
Yes | Attachment id, as returned by the upload |
file_name |
string |
Yes | File name |
content_type |
string |
Yes | MIME type; types starting with image/ are drawn as images |
size_bytes |
number |
Yes | Size in bytes |
ChatUploadTask
Progress of one upload, returned by attachments.getTask.
| Field | Type | Required | Meaning |
|---|---|---|---|
taskId |
string |
Yes | Task id |
progress |
number |
Yes | 0 to 100 |
status |
"pending" | "uploading" | "finalizing" | "done" | "failed" | "cancelled" |
Yes | finalizing: the bytes are sent and the server is still processing; it cannot be cancelled then |
speed |
number |
No | Bytes per second; no speed is shown when absent or 0 |
error |
string |
No | Why it failed |
ChatImageViewerSlide
One image passed to mediaViewer.open; see Image viewer.
| Field | Type | Required | Meaning |
|---|---|---|---|
src |
string |
Yes | Image URL |
alt |
string |
No | Alternative text |
description |
string |
No | The message's caption |
messageId |
string |
Yes | The message it is in |
attachmentIndex |
number |
Yes | Index among all of the message's attachments (not just its images) |
Sending, editing and paging
SendMessageInput
Argument of messaging.sendMessage.
| Field | Type | Required | Meaning |
|---|---|---|---|
conversationId |
string |
Yes | Target conversation |
text |
string |
Yes | Body, as Markdown source; an empty string when there are only attachments. There is no split between title and body; see Composer · Expanded editor Planned |
attachments |
readonly ChatAttachment[] |
No | Whole attachment entries. Left out (not an empty array) when there are none. The host passes them to the backend and sets the content type from them: "image" when all are images, otherwise "file" (sendContentTypeFor) |
replyToMessageId |
string |
No | Id of the quoted message, stored as parent_id |
mentions |
readonly ChatMentionInput[] |
No | Structured mentions. Left out when nobody is mentioned. The host must pass them to the backend, or mentioned people get no notification |
clientMessageId |
string |
No | Deduplication key for this message: the client_msg_id of the local copy in the message area, reused on retry. The SDK's message area always sets it. The host passes it to the backend as the deduplication key, and the backend returns it as client_msg_id on messages read back. Without it, the host generates its own key. Experimental: the name and shape may change. See ChatStoreSendStartedEvent |
ChatMentionInput is { type: "member"; memberId: string } (@someone) or { type: "all" | "all_agents" } (@all, @all agents).
ChatSendOutcome
sendMessage may return void or this:
| Field | Type | Required | Meaning |
|---|---|---|---|
blocked |
ChatSendBlocked |
No | The server's content filter stopped the message: it was neither stored nor delivered |
ChatSendBlocked:
| Field | Type | Required | Meaning |
|---|---|---|---|
refusalText |
string |
Yes | Explanation for the sender; must not be empty |
seq |
number |
No | Display position; the local placeholder is kept when absent |
timestamp |
string |
No | Time; the local created_at is kept when absent |
A blocked message stays only on the sender's side, with the explanation and a delete button, and cannot be retried.
ChatThreadPage
Returned by messaging.loadThread.
| Field | Type | Required | Meaning |
|---|---|---|---|
messages |
readonly ChatMessage[] |
Yes | In ascending seq order (oldest first); the UI does not reorder |
nextCursor |
string |
No | Present when there are older messages; absent means the start was reached. Only the server can tell; do not infer it from the page size |
headChangeSeq |
number |
No | The latest change-log number read in the same snapshot as the page; the change watermark starts from it, see the change log under Host capabilities · messaging. Leave it out when you don't have it rather than making up 0 |
ChatThreadSincePage
One of the return shapes of messaging.loadThreadSince (a plain array also works).
| Field | Type | Required | Meaning |
|---|---|---|---|
messages |
readonly ChatMessage[] |
Yes | Messages with seq greater than afterSeq, in ascending seq order |
hasNewer |
boolean |
Yes | Whether the server has newer messages after this batch. With false the UI stops after merging the batch instead of asking once more. Only the server can tell; do not infer it from the batch size; when unsure, return true |
headChangeSeq |
number |
No | The latest change-log number read in the same snapshot as the page; the change watermark starts from it, see the change log under Host capabilities · messaging. Leave it out when you don't have it rather than making up 0 |
ChatMessageEditInput
Argument of messaging.editMessage.
| Field | Type | Required | Meaning |
|---|---|---|---|
text |
string |
Yes | New body |
attachments |
readonly ChatAttachment[] |
Yes | All attachments of the message after the edit, in display order: kept ones first, new uploads after. An empty array when there are none. The host must not reorder them |
Body and attachments are never both empty: that would be a recall, and the editor disables Save.
ChatMessageEdit
One revision returned by messaging.listMessageEdits, in ascending time order.
| Field | Type | Required | Meaning |
|---|---|---|---|
id |
string |
Yes | Revision id |
createdAt |
string |
Yes | Revision time |
text |
string |
Yes | The body at the time, already extracted from content |
Read state and unread
| Data | Where | Used for |
|---|---|---|
| Unread count per conversation | ChatConversation.unread_count |
Unread count in the list |
| Unread @ or not | ChatConversation.unread_mention |
@ marker in the list |
| How far the current user has read | ChatConversation.last_read_seq |
The unread divider on open. Report new positions to your backend through the onVisibleSeqChange prop of MessageThread |
| How far each member has read and received | ChatReadCursorSnapshot, then the read and delivery signals |
DM check marks, group read counts |
| Unread @ list | ChatUnreadMentionsPage |
The "@me" jump in the message thread |
Signal fields: Realtime and sync · Realtime signals.
ChatReadCursorSnapshot
Returned by messaging.loadReadCursors, fetched once when a conversation opens.
| Field | Type | Required | Meaning |
|---|---|---|---|
cursors |
readonly { memberId: string; readUntilSeq: number; ackUntilSeq: number }[] |
Yes | The seq each member has read and received up to (inclusive). ackUntilSeq is never below readUntilSeq |
memberCount |
number |
Yes | Actual member count, possibly more than cursors |
truncated |
boolean |
Yes | In a large group cursors is cut short, shorter than memberCount |
ChatUnreadMentionsPage
Returned by mentions.listUnread.
| Field | Type | Required | Meaning |
|---|---|---|---|
mentions |
readonly ChatUnreadMention[] |
Yes | Unread mentions; may be just one page |
totalMe |
number |
Yes | Total @me count, regardless of paging |
totalAll |
number |
Yes | Total @all count, regardless of paging |
ChatUnreadMention: messageId, type ("me" | "all"), senderId, seq, timestamp, all required. The jump order follows seq, not time.
Drafts
ChatComposerDraft
| Field | Type | Required | Meaning |
|---|---|---|---|
html |
string |
Yes | HTML of the composer content, keeping @mention nodes |
replyTo |
ChatMessage | null |
No | The message being quoted; null means none, absent means this host does not store quotes |
files |
readonly File[] |
No | Picked files not yet sent. File cannot be serialized; drop it when persisting, so it does not survive a reload |
excerpts |
readonly ChatQuoteExcerpt[] |
No | Text selected from replyTo and quoted (messageId, text, optional offset / truncated). [] means none, absent means this host does not store them; at most one today, and its messageId equals replyTo.id |
When reading old drafts back from local storage, check them yourself: replyTo needs at least a string id; drop entries that fail. Drop an excerpt whose messageId or text is not a string, whose text is empty, or whose messageId is not replyTo.id.
Types of other capabilities
| Type | Capability | Fields |
|---|---|---|
ChatWorkItem |
workItems |
id, kind ("project" | "issue", i.e. ChatWorkItemKind), label (text shown), resourceUri (the address in the sent string), projectId? (the issue's project) |
ChatWorkItemPage |
workItems |
items, nextCursor? |
ChatConversationResource |
conversationResources |
Union by kind (ChatConversationResourceKind). Every row (ChatConversationResourceBase): id, conversationId, messageId, messageSeq, senderId, messageAt (the message's time). ChatConversationAttachmentResource (kind "image" | "file"): artifactId (required, without artifact://), fileName?, contentType?, sizeBytes?. ChatConversationLinkResource (kind "link"): url, host?, title? |
ChatConversationResourcesQuery |
conversationResources |
conversationId; optional kinds, senderId, since / until (RFC 3339 timestamps with a time zone, such as 2026-11-10T08:00:00Z; the OpenMax backend rejects date-only or zone-less strings (HTTP 422, a ChatSdkError of kind validation through the OpenMax adapter), and the in-memory adapter rejects them the same way; compared with messageAt; since inclusive, until exclusive), query, cursor, limit (at most 100: a larger value is treated as 100, not rejected; one that is not a positive integer counts as absent) |
ChatConversationResourcePage |
conversationResources |
items, nextCursor? |
ChatMessageSearchQuery |
messageSearch |
conversationId, query; optional cursor, limit (at most 100, as above) |
ChatMessageSearchHit |
messageSearch |
messageId, conversationId, seq, senderId, createdAt, snippet (ChatMessageSearchSnippetPart[]: { text, match }, plain text) |
ChatMessageSearchPage |
messageSearch |
hits (may be shorter than asked, even empty), nextCursor? |
ChatAgentModelState |
agentConfig |
visible and configurable (whether the current user may change it) are required; desiredModel?, effectiveModel?, desiredModelName?, effectiveModelName?, applyState? ("ready" | "applying" | "failed", ready when absent), availableModels?, lastError? |
ChatAgentModelOption |
agentConfig |
key (value sent to the server), displayName |
ChatAgentGroupPolicy |
agentGroupPolicy |
groupScope (ChatAgentGroupScope: "open" | "allowlist" | "disabled"), groupAllowlist (conversation ids, [] when empty), replyModes (conversation id → ChatAgentGroupReplyMode: "smart" | "mention"; mention when absent) |
ChatAgentPolicyApplyOutcome |
agentGroupPolicy |
{ outcome: "applied" | "unconfirmed" | "offline" | "aborted" }, or { outcome: "rejected", reason: ChatAgentPolicyRejectReason } ("forbidden" | "groupScopeDisabled" | "groupNotInAllowlist" | "unknown") |
ForwardRequestBody |
forward |
message_ids (one source conversation; 1–20 for forwardMessages, 1–100 for mergeForwardMessages), targets (1–10 ForwardTargetInput: conversation_id, client_msg_id of 1–64 characters, unique per target), note? (ForwardNoteInput: text, mentions?) |
ForwardResponseData<R> |
forward |
results (one R per target, in request order), succeeded_count, failed_count |
ForwardTargetResult, MergeForwardTargetResult |
forward |
conversation_id, note (ForwardNoteResult: status "succeeded" | "failed" | "blocked" | "skipped" | "absent"), and by status: "succeeded" with messages (ForwardedCopy[]: source_message_id, message_id, seq, blocked, refusal_text?) or message (MergedForwardCard: message_id, seq, blocked, refusal_text?); "failed" with error (ForwardTargetError: code, status, detail?) |
ChatCardActionInput, ChatCardChoiceInput, ChatCardActionResult, ChatCardActionErrorKind |
cards |
See Interactive cards |
ChatInboundSignal and its variants |
inboundDelivery |
See Realtime and sync |
ChatInboundTypingSignal |
inboundDelivery |
A variant of ChatInboundSignal: { kind: "typing", conversationId, memberId, active }. Hosts may leave it out; when they send it, the message area does not catch up on it. memberId can be the current user, and receivers filter that out themselves; after active: true, no new one within 6 seconds counts as stopped. See Realtime and sync |
ChatInboundDisconnectedSignal Planned |
inboundDelivery |
A planned variant of ChatInboundSignal, { kind: "disconnected" }; see Realtime and sync |
ChatConnectionStatus Planned |
— | "idle" | "connecting" | "connected" | "reconnecting" | "offline" | "unauthorized" | "failed": the state of the realtime connection |
ChatRenderErrorArea Planned |
— | The areas of the error boundaries; see Render errors |
desiredModel is what the user chose and effectiveModel is what is running; while switching they differ and applyState is applying.
Agent runs
Planned
Runs in the message store: ChatAgentRun, ChatAgentRunPart, ChatAgentSubagent. The realtime event ChatAgentEventSignal: Custom backend · Signals handed to the SDK.
