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

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