Shared chats and membership
Use this reference with the complete developer tour and Python types. The example at the end runs after the tour setup.
start_chat
Section titled “start_chat”Create one shared conversation for the chosen participants and its first message.
start_chat(self, *, targets: list[dict[str, str]], body: str, title: str='', approval: bool=False, choices: list[str] | None=None, mentions: list[dict[str, Any]] | None=None, attachment_ids: list[str] | None=None, key: str | None=None)| Parameter | Type and default | Usage |
|---|---|---|
targets |
list[dict[str, str]] (required) |
Explicit targets for a private batch or shared chat. These have different audience semantics. |
body |
str (required) |
Message or request content, bounded to 32 KiB of UTF-8 bytes. |
title |
str (default ‘’) |
Optional short label. A normal message does not require a title. |
approval |
bool (default False) |
Attach a typed approval request to the initial shared chat message. False by default. |
choices |
list[str] | None (default None) |
Optional exact answer strings. A chosen answer must match an offered value. |
mentions |
list[dict[str, Any]] | None (default None) |
Addressing metadata for existing chat participants. It does not narrow audience or grant authority. |
attachment_ids |
list[str] | None (default None) |
IDs of staged private drafts to claim in the initial operation; at most five. |
key |
str | None (default None) |
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.
Working Python example. Input/output fields are in the types reference.
conversation
Section titled “conversation”Read a currently authorized conversation and its visible history.
conversation(self, conversation_id: str)| Parameter | Type and default | Usage |
|---|---|---|
conversation_id |
str (required) |
Canonical conversation ID. Use it to continue the same authorized history. |
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.
Working Python example. Input/output fields are in the types reference.
change_chat_membership
Section titled “change_chat_membership”Add or remove members, rename, leave, or transfer management of a shared chat.
change_chat_membership(self, conversation_id: str, *, operation: str, version: int, title: str='', members: list[str] | None=None, share_history: bool=False, next_manager: str='', key: str | None=None)| Parameter | Type and default | Usage |
|---|---|---|
conversation_id |
str (required) |
Canonical conversation ID. Use it to continue the same authorized history. |
operation |
str (required) |
Requested operation, with values defined by that endpoint. |
version |
int (required) |
Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts. |
title |
str (default ‘’) |
Optional short label. A normal message does not require a title. |
members |
list[str] | None (default None) |
Directory-group or chat member identity IDs. Membership never substitutes for contact authority. |
share_history |
bool (default False) |
Explicitly disclose earlier history to additions. False by default. |
next_manager |
str (default ‘’) |
Existing participant to manage the chat when the current manager leaves. |
key |
str | None (default None) |
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.
Working Python 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.
body = '👋 @Billing 2 check these orders.'chat = owner.start_chat(targets=targets, body=body, mentions=[{'principal_id': billing_id, 'start': 2, 'end': 12}], key=run_id + '/chat')chat_id = chat['conversation_id']assert 'explicitly addressed' in mention_context(chat['messages'][0], billing_id)history = owner.conversation(chat_id)changed = owner.change_chat_membership(chat_id, operation='rename', version=history['version'], title='Checkout reconciliation', key=run_id + '/rename')assert changed['version'] > history['version']