> ## 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

> Create, read, and manage direct and group chat conversations through the Public API.

Use Conversations for new Public API messaging integrations. The legacy
member-scoped chat endpoints stay available for compatibility, but new
integrations should use `/public/v1/conversations`.

## Capabilities

| Capability                                  | Endpoint                                                                      |
| :------------------------------------------ | :---------------------------------------------------------------------------- |
| List direct and group conversations         | `GET /public/v1/conversations`                                                |
| List the combined conversation inbox        | `GET /public/v1/conversations/inbox`                                          |
| Create a direct or group conversation       | `POST /public/v1/conversations`                                               |
| Read one conversation                       | `GET /public/v1/conversations/{conversationId}`                               |
| List messages without marking them as seen  | `GET /public/v1/conversations/{conversationId}/messages`                      |
| Send, update, or delete coach text messages | `POST`, `PATCH`, `DELETE /public/v1/conversations/{conversationId}/messages*` |
| List active participants                    | `GET /public/v1/conversations/{conversationId}/participants`                  |
| Add or remove group participants            | `POST`, `DELETE /public/v1/conversations/{conversationId}/participants*`      |

## Actor Rules

Message writes require `conversation_messages:write` and
`consents.privateCommunication=true`. The request includes `senderCoachId`; that
coach must match the requesting coach for the Public API client, belong to the
company, be an active participant in the conversation, and must be the original
sender for update/delete operations. Company-level Public API clients cannot
send messages as a client or as another coach.

Participant writes require `conversation_participants:write`. The request
includes `actorCoachId`; that coach must match the requesting coach and be an
active coach participant in the group conversation. Direct conversations stay
one-to-one, so adding another coach or member is done by creating or using a
group conversation.

For group creation, `createdBy` is optional when the Public API client has a
requesting coach. If it is provided, it must match that requesting coach. This
keeps the current API from silently impersonating another coach while still
leaving room for explicit delegated replies later.

## Future Contexts

Every conversation response includes a `context` object:

```json theme={null}
{
  "type": "client",
  "id": "66f7b8b1e13c8d25f4d3d90c",
  "occurrenceStart": null,
  "label": ""
}
```

Supported context types are `none`, `client`, `company`, `lesson`,
`calendar_event`, and `booking`. The current API already stores and returns this
shape so company chats, lesson chats, and calendar-event conversations can be
added later without replacing the endpoint family.

## Webhook Events

Conversation write actions emit outbound Public API webhook events when a company
has an active webhook subscription for the matching event. Supported events are
`conversation.created`, `conversation.updated`,
`conversation.participant.added`, `conversation.participant.removed`,
`conversation.message.created`, `conversation.message.updated`, and
`conversation.message.deleted`.

Webhook payloads include conversation IDs, type, context IDs, participant roles,
sender/actor IDs, and timestamps. They do not include message text, media URLs,
conversation names, descriptions, or context labels. Use the read endpoints
above when an integration needs detail after receiving a webhook.

## Output Contract

Conversation responses return explicit DTOs only. They omit push-channel names,
unread-state internals, raw participant authorization fields, S3 media paths,
and delivery/read internals. Reads are side-effect-free: listing conversations
or messages does not mark anything as seen.

The inbox, conversation list, message list, and participant list endpoints all
support page pagination with `page` and `limit`. Paginated responses include
`page`, `limit`, `total`, `totalPages`, `hasNextPage`, and `hasPrevPage`.

See the **Conversations** group in the API Reference tab for exact request and
response schemas.