> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fitsociety.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Conversations

> Reference for reading and managing direct and group chat conversations through MCP.

The `conversations` module is the MCP surface for new messaging automation. It
uses the same conversation DTOs as the Public API and supports direct and group
chat conversations without exposing unread-state internals or private channel
names.

| Key                  | Value                         |
| :------------------- | :---------------------------- |
| **Module Key**       | `conversations`               |
| **Sensitivity**      | `private_communication`       |
| **Consent Required** | `privateCommunicationConsent` |

***

## Available Tools

### `list_conversations`

List direct and group conversations, newest updated first.

* **Type:** Read-only
* **Important Input Fields:**
  * `conversationType` (string, optional): `direct` or `group`.
  * `clientId` (string, optional): Filter by client.
  * `participantId` / `participantRole` (string, optional): Filter by participant.
  * `contextType` / `contextId` (string, optional): Filter by semantic context.
  * `page` / `limit` (integer, optional): Page pagination.

### `list_conversation_inbox`

List the combined inbox of direct and group conversations, newest updated
first. This is an alias of `list_conversations` with the same filters and page
pagination.

* **Type:** Read-only
* **Important Input Fields:**
  * `conversationType` (string, optional): `direct` or `group`.
  * `clientId` (string, optional): Filter by client.
  * `participantId` / `participantRole` (string, optional): Filter by participant.
  * `contextType` / `contextId` (string, optional): Filter by semantic context.
  * `page` / `limit` (integer, optional): Page pagination.

### `get_conversation`

Retrieve one conversation without marking messages as read.

* **Type:** Read-only
* **Important Input Fields:**
  * `conversationId` (string, required): Conversation ID.
  * `conversationType` (string, optional): `direct` or `group`.

### `get_conversation_messages`

Retrieve conversation messages, newest first.

* **Type:** Read-only
* **Important Input Fields:**
  * `conversationId` (string, required): Conversation ID.
  * `conversationType` (string, optional): `direct` or `group`.
  * `page` / `limit` (integer, optional): Page pagination.

### `list_conversation_participants`

List active participants for a conversation.

* **Type:** Read-only
* **Important Input Fields:**
  * `conversationId` (string, required): Conversation ID.
  * `conversationType` (string, optional): `direct` or `group`.
  * `page` / `limit` (integer, optional): Page pagination.

### `create_conversation`

Create or find a direct conversation, or create a group conversation.

* **Type:** Write
* **Write Tool Grant:** `create_conversation`
* **Important Input Fields:**
  * `conversationType` (string, required): `direct` or `group`.
  * `participants` (array, required): Coach/client participants.
  * `createdBy` (object, optional): Requesting coach actor. Defaults to the grant owner when available.
  * `name` (string, group only): Required for group conversations.
  * `context` (object, optional): `none`, `client`, `company`, `lesson`, `calendar_event`, or `booking`.

### `send_conversation_message`

Send a text message as the requesting coach when that coach is an active
participant.

* **Type:** Write
* **Write Tool Grant:** `send_conversation_message`
* **Important Input Fields:**
  * `conversationId` (string, required): Conversation ID.
  * `senderCoachId` (string, required): Requesting coach sender ID.
  * `message` (string, required): Text body.

### `update_conversation_message`

Update a text message sent by the requesting coach within the edit window.

* **Type:** Write
* **Write Tool Grant:** `update_conversation_message`
* **Important Input Fields:**
  * `conversationId` (string, required): Conversation ID.
  * `messageId` (string, required): Message ID.
  * `senderCoachId` (string, required): Original requesting coach sender ID.
  * `message` (string, required): Replacement text.

### `delete_conversation_message`

Soft-delete a text message sent by the requesting coach within the edit window.

* **Type:** Write
* **Write Tool Grant:** `delete_conversation_message`
* **Important Input Fields:**
  * `conversationId` (string, required): Conversation ID.
  * `messageId` (string, required): Message ID.
  * `senderCoachId` (string, required): Original requesting coach sender ID.

### `add_conversation_participants`

Add or restore participants in a group conversation.

* **Type:** Write
* **Write Tool Grant:** `add_conversation_participants`
* **Important Input Fields:**
  * `conversationId` (string, required): Group conversation ID.
  * `actorCoachId` (string, required): Requesting coach performing the change.
  * `participants` (array, required): Participants to add.

### `remove_conversation_participant`

Remove one participant from a group conversation.

* **Type:** Write
* **Write Tool Grant:** `remove_conversation_participant`
* **Important Input Fields:**
  * `conversationId` (string, required): Group conversation ID.
  * `actorCoachId` (string, required): Requesting coach performing the change.
  * `participantId` (string, required): User ID to remove.

***

## Actor and Context Rules

MCP writes use the grant owner as the requesting coach. The request still passes
`senderCoachId`, `actorCoachId`, or `createdBy` for audit clarity, but that coach
must match the requesting coach, belong to the company, and already be an active
conversation participant where applicable. Other-coach delegation is intentionally
not enabled yet; it can be added later as an explicit permission without
renaming these tools.

Conversation contexts are intentionally future-facing. The current contract
accepts and returns `client`, `company`, `lesson`, `calendar_event`, and
`booking` context values, so later company chats or lesson-specific chats can be
added without replacing the tool names.

Conversation write tools use the same mutation service as the Public API.
Successful writes therefore emit the same outbound Public API webhook events
when the company has an active matching webhook subscription. Webhook payloads
stay metadata-only: they include IDs, roles, context IDs, and timestamps, but no
message text, media URLs, conversation names, descriptions, or context labels.