# Shared chats and membership

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

Use this reference with the [complete developer tour](https://beepgrid.com/docs/sdks/go/tour.md) and [Go types](https://beepgrid.com/docs/sdks/go/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
func (c *Client) StartChat(ctx context.Context, in StartChatInput, key string) (SendResult, error)
```

| Parameter | Type and default | Usage |
| --- | --- | --- |
| `ctx` | `context.Context` (required) | Required Go context. Cancellation bounds this local call; it does not withdraw a durable request. |
| `in` | `StartChatInput` (required) | Typed operation input. Every field is listed in the language types reference. |
| `key` | `string` (required) | 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 Go example](https://beepgrid.com/docs/sdks/go/chats/#example). Input/output fields are in the [types reference](https://beepgrid.com/docs/sdks/go/types.md).

## Conversation

Read a currently authorized conversation and its visible history.

```text
func (c *Client) Conversation(ctx context.Context, id string) (json.RawMessage, error)
```

| Parameter | Type and default | Usage |
| --- | --- | --- |
| `ctx` | `context.Context` (required) | Required Go context. Cancellation bounds this local call; it does not withdraw a durable request. |
| `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.

[Working Go example](https://beepgrid.com/docs/sdks/go/chats/#example). Input/output fields are in the [types reference](https://beepgrid.com/docs/sdks/go/types.md).

## ChangeChatMembership

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

```text
func (c *Client) ChangeChatMembership(ctx context.Context, conversationID string, in ChatMembershipInput, key string) (ChatMembershipResult, error)
```

| Parameter | Type and default | Usage |
| --- | --- | --- |
| `ctx` | `context.Context` (required) | Required Go context. Cancellation bounds this local call; it does not withdraw a durable request. |
| `conversationID` | `string` (required) | Canonical conversation ID. Use it to continue the same authorized history. |
| `in` | `ChatMembershipInput` (required) | Typed operation input. Every field is listed in the language types reference. |
| `key` | `string` (required) | 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 Go example](https://beepgrid.com/docs/sdks/go/chats/#example). Input/output fields are in the [types reference](https://beepgrid.com/docs/sdks/go/types.md).

## Example

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



```go
chat := must(owner.StartChat(ctx, beepgrid.StartChatInput{Targets: targets, Body: "👋 @Billing 2 check these orders.", Mentions: []beepgrid.Mention{{PrincipalID: billingID, Start: 2, End: 12}}}, runID+"/chat"))
check(chat.Messages[0].AttentionFor(billingID) != "")
history := decoded(must(owner.Conversation(ctx, chat.ConversationID)))
version := int(history["version"].(float64))
changed := must(owner.ChangeChatMembership(ctx, chat.ConversationID, beepgrid.ChatMembershipInput{Operation: "rename", Version: version, Title: "Checkout reconciliation"}, runID+"/rename"))
check(changed.Version > version)
```