Client protocol

Clients send JSON frames {"op": …, "rid": …, …fields} over /ws and get {"type": "res", "rid", "ok", …} back; pushes are described in Events. The client SDKs send these for you. Errors use the error codes.

Any request may carry "trace": "00-<trace id>-<parent id>-<flags>" (W3C traceparent). Agents’ traces are continued; a person’s app gets a new server trace that links to theirs (Tracing).

hello

Handshake (docs/en/design/messaging.md). Every field is optional so clients that predate negotiation keep working.

Field	Type	Required	Description
protocol	number[]
client	ClientInfo
features	string[]

list_convs

The caller’s conversations with their last message, unread count, members and mute state.

No fields.

create_conv

Creates a conversation: dm (exactly one other member), group or task; the caller is its owner.

Field	Type	Required	Description
kind	string	yes
title	string	yes
members	string[]	yes
assignee	string		Task channels: the member responsible for the task.

add_member

Owner or admin adds a member (an agent owner may add their agent where allowed).

Field	Type	Required	Description
conv_id	string	yes
user_id	string	yes
history	number		Earlier messages the new member may see (docs/en/design/sync-and-clients.md); default from the server configuration.

remove_member

Owner / admin removes a member; anyone removes an agent they own.

Field	Type	Required	Description
conv_id	string	yes
user_id	string	yes

leave

The caller leaves a group; the owner transfers ownership or dissolves instead.

Field	Type	Required	Description
conv_id	string	yes

set_role

Owner only: admin or member.

Field	Type	Required	Description
conv_id	string	yes
user_id	string	yes
role	string	yes

transfer_owner

The owner makes another member (a person) the owner; the old owner becomes an admin.

Field	Type	Required	Description
conv_id	string	yes
user_id	string	yes

dissolve

Owner only: everyone loses access and the content is deleted.

Field	Type	Required	Description
conv_id	string	yes

block

The caller blocks a user: no direct messages, invitations or new conversations from them.

Field	Type	Required	Description
user_id	string	yes

unblock

Lifts a block.

Field	Type	Required	Description
user_id	string	yes

list_blocks

Users the caller has blocked.

No fields.

find_user

Exact user name; only users the caller may discover are returned.

Field	Type	Required	Description
name	string	yes

send

Sends a message. client_msg_id makes retries safe: the same id returns the first result.

Field	Type	Required	Description
conv_id	string	yes
client_msg_id	string	yes
text	string	yes	For a custom kind: the plain-text fallback.
kind	string
payload	JSON
reply_to	string
causation_id	string
on_behalf_of	string
to_user	string		Ephemeral: visible only to this user (plus the sender and, for an agent, its owner). Goes to the side channel, takes no conv_seq.
to	string[]		Routing envelope (docs/en/design/agents.md): members named, topics, intent, references.
topics	string[]
intent	string
refs	string[]
sources	JSON[]		Sources an answer is based on (docs/en/design/agents.md).
thread_id	string		Replies in the thread of this root message (MSG-19).
also_in_conv	boolean		A thread reply that also shows in the conversation.

edit

Edits a message: the sender (or the sending agent’s owner), within the app’s edit window.

Field	Type	Required	Description
msg_id	string	yes
text	string	yes
payload	JSON		Custom kinds only: replaces the payload when given.
base_version	number		The version the edit is based on: refused with conflict when the message has changed since.

signal

Ephemeral event to the online members: no storage, no seq.

Field	Type	Required	Description
conv_id	string	yes
kind	string	yes
data	JSON

recall

Recalls (deletes for everyone) a message: the sender, the agent’s owner, an owner or admin.

Field	Type	Required	Description
msg_id	string	yes

pull

Agents: events of a conversation after a seq (people use sync).

Field	Type	Required	Description
conv_id	string	yes
after_seq	number
limit	number
as_agent	string		Owner observing through one of their agents.

pull_side

Side-channel events (whispers, progress, ephemeral messages) after a side seq.

Field	Type	Required	Description
conv_id	string	yes
after_side_seq	number

read

Marks the conversation read up to seq on all of the caller’s devices.

Field	Type	Required	Description
conv_id	string	yes
seq	number	yes

sync

Receive what this device has not acknowledged yet (docs/en/design/sync-and-clients.md).

Field	Type	Required	Description
limit	number

ack

Positions this device has stored durably.

Field	Type	Required	Description
acks	AckItem[]	yes

set_mute

none, all or mentions, optionally until a time (ms).

Field	Type	Required	Description
conv_id	string	yes
mode	string	yes
until	number

unread

Unread counts of the caller’s conversations.

No fields.

heads

The latest seq of each conversation (a client checks its position; a tail push lost on the way shows up here, docs/en/design/cluster.md).

Field	Type	Required	Description
conv_ids	string[]	yes

set_prefs

The caller’s preferences: whether reading on one device silences the others.

Field	Type	Required	Description
read_silences_others	boolean

observe

An owner reads a conversation as one of their agents sees it (audited).

Field	Type	Required	Description
conv_id	string	yes
agent_id	string	yes
after_seq	number
limit	number

focus

The conversation open on screen: its streaming replies arrive as live deltas.

Field	Type	Required	Description
conv_id	string
as_agent	string

stream_start

An agent starts a streamed reply; the message shows at once as streaming.

Field	Type	Required	Description
conv_id	string	yes
client_msg_id	string	yes
reply_to	string
causation_id	string
thread_id	string		Streams the reply into this thread (MSG-19).
also_in_conv	boolean

stream_append

Appends text to a stream; idx numbers the chunks from 0 (out of order is refused).

Field	Type	Required	Description
msg_id	string	yes
idx	number	yes
text	string	yes

stream_end

Ends a stream: the message becomes final.

Field	Type	Required	Description
msg_id	string	yes

stream_cancel

Stops a stream: the agent itself, a person in the conversation (Stop) or the owner.

Field	Type	Required	Description
msg_id	string	yes

whisper

An owner whispers to their agent in a conversation: only the agent and the owner see it.

Field	Type	Required	Description
conv_id	string	yes
agent_id	string	yes
text	string	yes

approve

Publishes an agent’s draft (optionally edited): its owner or an approver.

Field	Type	Required	Description
draft_id	string	yes
text	string

reject

Discards an agent’s draft.

Field	Type	Required	Description
draft_id	string	yes

escalate

A reviewing agent hands a draft to the people who approve it (docs/en/design/agents.md).

Field	Type	Required	Description
draft_id	string	yes
note	string

takeover

An owner takes over their agent in a conversation: the agent stops acting there.

Field	Type	Required	Description
conv_id	string	yes
agent_id	string	yes

release

Ends a takeover: the agent acts again.

Field	Type	Required	Description
conv_id	string	yes
agent_id	string	yes

set_agent_policy

An owner sets how their agent acts in a conversation: approval of drafts (true / false or rules, docs/en/design/agents.md), when it wakes, its topics. The conversation’s managers set required_approval for any agent there.

Field	Type	Required	Description
conv_id	string	yes
agent_id	string	yes
approval	ApprovalArg
required_approval	ApprovalArg
trigger	Trigger
topics	string[]		Topics an agent in topics mode subscribes to.

reset_guard

An owner resets their agent’s tripped guardrail (loop breaker) in a conversation.

Field	Type	Required	Description
conv_id	string	yes
agent_id	string	yes

list_drafts

Drafts waiting for the caller’s approval.

No fields.

update_conv

Rename a conversation or replace its custom fields (owner, admin).

Field	Type	Required	Description
conv_id	string	yes
title	string
fields	JSON
pin_policy	string		Who may pin messages in a group: members or admins (MSG-21).

read_thread

Marks a thread read up to seq on all of the caller’s devices (MSG-19).

Field	Type	Required	Description
conv_id	string	yes
thread_id	string	yes
seq	number	yes

follow_thread

Follows a thread: its replies notify the caller.

Field	Type	Required	Description
conv_id	string	yes
thread_id	string	yes

unfollow_thread

Stops following a thread.

Field	Type	Required	Description
conv_id	string	yes
thread_id	string	yes

list_threads

The threads the caller follows, unread first, then by latest reply (one conversation, or all of the caller’s).

Field	Type	Required	Description
conv_id	string
before	number		Only threads whose latest reply is older than this time (ms).
limit	number

pull_thread

A thread’s root and the replies after a seq.

Field	Type	Required	Description
conv_id	string	yes
thread_id	string	yes
after_seq	number
limit	number

react

Adds a reaction to a message (MSG-20); adding one twice changes nothing.

Field	Type	Required	Description
conv_id	string	yes
msg_id	string	yes
key	string	yes

unreact

Removes the caller’s reaction; removing one that is not there changes nothing.

Field	Type	Required	Description
conv_id	string	yes
msg_id	string	yes
key	string	yes

list_reactions

Who reacted to a message with a key, oldest first.

Field	Type	Required	Description
conv_id	string	yes
msg_id	string	yes
key	string	yes
after_seq	number		Only reactions after this seq.
limit	number

pin

Pins a message to the conversation (MSG-21); pinning it again changes nothing.

Field	Type	Required	Description
conv_id	string	yes
msg_id	string	yes

unpin

Unpins a message.

Field	Type	Required	Description
conv_id	string	yes
msg_id	string	yes

list_pins

The conversation’s pinned messages, latest pin first.

Field	Type	Required	Description
conv_id	string	yes
before_seq	number		Only pins older than this seq.
limit	number

msg_summary

The thread summary, reactions and pin of up to 100 messages of a conversation, as the caller sees them.

Field	Type	Required	Description
conv_id	string	yes
msg_ids	string[]	yes

list_devices

This user’s devices (one per client token).

No fields.

logout_device

Revokes one device’s token and disconnects it (also this device).

Field	Type	Required	Description
device_id	string	yes

create_agent

A new agent owned by the caller, with its first key (docs/en/design/agents.md–§2.3).

Field	Type	Required	Description
name	string	yes

list_agents

The caller’s agents and their keys (never the secrets).

No fields.

list_roles

The app’s agent roles (docs/en/design/agents.md): name, description, version.

No fields.

set_agent_role

The owner gives one of their agents a role (null: none).

Field	Type	Required	Description
agent_id	string	yes
role	string

get_config

An agent’s configuration (role, skills, MCP, APIs), as in welcome.

No fields.

friend_request

Asks to be friends (docs/en/design/agents.md); with someone who takes anyone (the app’s agents) it is done at once.

Field	Type	Required	Description
user_id	string	yes
message	string

friend_accept

Accepts a request from user_id.

Field	Type	Required	Description
user_id	string	yes

friend_decline

Declines a request from user_id.

Field	Type	Required	Description
user_id	string	yes

friend_remove

Ends a friendship (or withdraws my waiting request).

Field	Type	Required	Description
user_id	string	yes

list_friends

Friends and the requests waiting both ways.

No fields.

set_friend_policy

Who may add me: anyone, confirm (the default) or nobody.

Field	Type	Required	Description
policy	string	yes

list_app_agents

The app’s agents people can add as friends.

No fields.

agent_key

A new key for one of the caller’s agents; revoke_others revokes every other key in the same write.

Field	Type	Required	Description
agent_id	string	yes
revoke_others	boolean

revoke_agent_key

Revokes one key of one of the caller’s agents.

Field	Type	Required	Description
agent_id	string	yes
device_id	string	yes

request_human

An agent asks a person to approve, answer or choose (docs/en/design/agents.md).

Field	Type	Required	Description
conv_id	string	yes
kind	string	yes
title	string	yes
options	string[]
context	JSON
assignees	string[]
ttl_secs	number
client_req_id	string	yes

decide

A person decides a request: approve, reject, answer or choose.

Field	Type	Required	Description
request_id	string	yes
decision	string	yes
text	string
choice	string

cancel_request

The asking agent withdraws a pending request.

Field	Type	Required	Description
request_id	string	yes

get_request

A request and its outcome; waits up to wait_secs (≤ 25) for a decision.

Field	Type	Required	Description
request_id	string	yes
wait_secs	number

inbox

What waits for my decision across conversations: requests, my agents’ drafts and hand-offs (docs/en/design/chat-components.md), oldest first.

Field	Type	Required	Description
limit	number		At most this many (default 100, 1..500); more says if there were more.

update_task

Moves a task channel to a state (docs/en/design/agents.md).

Field	Type	Required	Description
conv_id	string	yes
state	string
assignee	string
note	string

claim

Takes a request (intent: request) for oneself; the first wins.

Field	Type	Required	Description
msg_id	string	yes

release_claim

Gives back a claimed request.

Field	Type	Required	Description
msg_id	string	yes

floor_grant

Gives a coordinated agent the floor for a while.

Field	Type	Required	Description
conv_id	string	yes
agent_id	string	yes
ttl_secs	number

floor_release

Gives back the floor in a coordinated conversation.

Field	Type	Required	Description
conv_id	string	yes

history

Agents read what they may see of a conversation by seq (after_seq / before_seq / limit, docs/en/design/agents.md); people read pages of messages around an anchor (anchor, before, after, docs/en/design/sync-and-clients.md).

Field	Type	Required	Description
conv_id	string	yes
after_seq	number
before_seq	number
limit	number
anchor	JSON
before	number
after	number

ping

Application-level heartbeat (docs/en/design/sync-and-clients.md): answers the server time.

No fields.

context

An agent’s view of a conversation for its model: summaries and recent messages within max_tokens.

Field	Type	Required	Description
conv_id	string	yes
max_tokens	number
thread_id	string		Only this thread: its root and replies (MSG-19).

search

An agent searches the messages it may see (optionally one conversation).

Field	Type	Required	Description
query	string	yes
conv_id	string
limit	number
filter	SearchFilter

put_summary

An agent stores a summary of a range of seqs (used by context).

Field	Type	Required	Description
conv_id	string	yes
from_seq	number	yes
to_seq	number	yes
text	string	yes

state_get

Agent checkpoints (docs/en/design/agents.md).

Field	Type	Required	Description
key	string	yes
version	number

state_put

Writes a checkpoint; version is the version read (0 creates), so concurrent writes conflict.

Field	Type	Required	Description
key	string	yes
value	JSON	yes
version	number	yes

state_list

Lists checkpoint keys by prefix, in pages.

Field	Type	Required	Description
prefix	string
after	string
limit	number

state_delete

Deletes a checkpoint at the version read.

Field	Type	Required	Description
key	string	yes
version	number	yes

stop_agent

An owner’s emergency stop, resume and destroy (docs/en/design/agents.md–§4.4).

Field	Type	Required	Description
agent_id	string	yes
reason	string

resume_agent

Resumes a stopped agent.

Field	Type	Required	Description
agent_id	string	yes

destroy_agent

Destroys an agent for good (confirm repeats its name): keys revoked, memberships ended, checkpoints deleted.

Field	Type	Required	Description
agent_id	string	yes
confirm	string	yes

handoff

An agent hands the conversation to a person; that person or the owner hands it back (docs/en/design/agents.md).

Field	Type	Required	Description
conv_id	string	yes
to	string
note	string	yes

handback

Hands a handed-off conversation back to the agent.

Field	Type	Required	Description
conv_id	string	yes
agent_id	string	yes
note	string

progress

An agent’s progress report (side channel).

Field	Type	Required	Description
conv_id	string	yes
msg_id	string
kind	string	yes
text	string	yes
data	JSON

feedback

Thumbs up / down / none on an agent’s message.

Field	Type	Required	Description
msg_id	string	yes
rating	string
reason	string

list_feedback

An owner’s view of the feedback on an agent.

Field	Type	Required	Description
agent_id	string	yes
limit	number

report

Reports a message, a user or a conversation (docs/en/design/security.md).

Field	Type	Required	Description
target_kind	string	yes
target_id	string	yes
category	string	yes
text	string

card_answers

The answers to a card so far (docs/en/design/chat-components.md): who answered which block and when; the values only to the one who answered and the sender.

Field	Type	Required	Description
msg_id	string	yes

respond

A member’s response to a card: a button, a picked list row, a filled form, or an answer to the developer’s own block.

Field	Type	Required	Description
msg_id	string	yes
block_id	string	yes
action	string
values	JSON

upload_start

Starts uploading a file to a conversation (docs/en/design/messaging.md): the addresses to PUT its parts (and thumbnail) to.

Field	Type	Required	Description
conv_id	string	yes
name	string	yes
size	number	yes
mime	string
thumb_size	number		Bytes of the thumbnail the client made (images).

upload_parts

More part addresses, from part from.

Field	Type	Required	Description
conv_id	string	yes
file_id	string	yes
from	number

upload_complete

All parts are up: checks them and makes the file usable.

Field	Type	Required	Description
conv_id	string	yes
file_id	string	yes
parts	PartTag[]

file_url

A short-lived address to read a file (thumb or original).

Field	Type	Required	Description
conv_id	string	yes
file_id	string	yes
variant	string