Shared chats and membership
Use this reference with the complete developer tour and TypeScript types. The example at the end runs after the tour setup.
startChat
Section titled “startChat”Create one shared conversation for the chosen participants and its first message.
startChat(input: StartChatInput, key?: string): Promise<{ conversation_id: string; messages: Message[]; }>| Parameter | Type and default | Usage |
|---|---|---|
input |
StartChatInput (required) |
Typed operation input. See its declaration in the language types reference. |
key |
string (default crypto.randomUUID()) |
Saved idempotency key. Retain for an unknown write outcome; a newly generated key starts a new operation. |
Returns: SendResult; an approval or choices on the first message also creates a requested decision.
Permissions, lifecycle and errors: Participants share the history they can currently access. Use individual targets with mutual view permission. Mentions address members without hiding messages from others.
Declared return type: Promise<{ conversation_id: string; messages: Message[]; }>.
Working TypeScript example. Input/output fields are in the types reference.
conversation
Section titled “conversation”Read a currently authorized conversation and its visible history.
conversation(id: string): Promise<Conversation>| Parameter | Type and default | Usage |
|---|---|---|
id |
string (required) |
Existing stable resource ID, returned by the corresponding create/read operation. |
Returns: Conversation with participants, messages, shared, version, manager_id and history_start where applicable.
Permissions, lifecycle and errors: New members normally see future history only. Current removal or policy changes can revoke messages and files. Conversation version controls membership changes, not request decisions.
Declared return type: Promise<Conversation>.
Working TypeScript example. Input/output fields are in the types reference.
changeChatMembership
Section titled “changeChatMembership”Add or remove members, rename, leave, or transfer management of a shared chat.
changeChatMembership(conversationId: string, input: ChatMembershipInput, key?: string): Promise<ChatMembershipResult>| Parameter | Type and default | Usage |
|---|---|---|
conversationId |
string (required) |
Canonical conversation ID. Use it to continue the same authorized history. |
input |
ChatMembershipInput (required) |
Typed operation input. See its declaration in the language types reference. |
key |
string (default crypto.randomUUID()) |
Saved idempotency key. Retain for an unknown write outcome; a newly generated key starts a new operation. |
Returns: ChatMembershipResult: conversation_id, version, and optional left.
Permissions, lifecycle and errors: operation is add/remove/rename/leave. members contains principal IDs. share_history defaults false and must be an intentional disclosure. On leave or removal of the manager, supply next_manager when required. Refetch version on conflict.
Declared return type: Promise<ChatMembershipResult>.
Working TypeScript example. Input/output fields are in the types reference.
Example
Section titled “Example”Run this region after the shared setup. Assertions check the returned data; the full tour is a runnable program.
const chat = await owner.startChat({ targets, body: '👋 @Billing 2 check these orders.', mentions: [{ principal_id: billingId, start: 2, end: 12 }] }, runId + '/chat');const history = await owner.conversation(chat.conversation_id);assert.ok(typeof history.version === 'number');const changed = await owner.changeChatMembership(chat.conversation_id, { operation: 'rename', version: history.version, title: 'Checkout reconciliation' }, runId + '/rename');assert.ok(changed.version > history.version);