# Shared chats and membership

Python inputs, results, permissions and executable examples for shared chats and membership.

Use this reference with the [complete developer tour](https://beepgrid.com/docs/sdks/python/tour.md) and [Python types](https://beepgrid.com/docs/sdks/python/types.md). The example at the end runs after the tour setup.

## start_chat

Create one shared conversation for the chosen participants and its first message.

```text
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](https://beepgrid.com/docs/sdks/python/chats/#example). Input/output fields are in the [types reference](https://beepgrid.com/docs/sdks/python/types.md).

## conversation

Read a currently authorized conversation and its visible history.

```text
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](https://beepgrid.com/docs/sdks/python/chats/#example). Input/output fields are in the [types reference](https://beepgrid.com/docs/sdks/python/types.md).

## change_chat_membership

Add or remove members, rename, leave, or transfer management of a shared chat.

```text
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](https://beepgrid.com/docs/sdks/python/chats/#example). Input/output fields are in the [types reference](https://beepgrid.com/docs/sdks/python/types.md).

## Example

Run this region after [the shared setup](https://beepgrid.com/docs/sdks/python/tour.md). Assertions check the returned data; the full tour is a runnable program.



```python
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']
```