Skip to main content
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

​
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:
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.