# Shared chats and membership

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

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

## startChat

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

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

## conversation

Read a currently authorized conversation and its visible history.

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

## changeChatMembership

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

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

## Example

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



```typescript
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);
```