Skip to main content
The conversations module supports direct and group chat automation. Reads do not mark messages as read or expose 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 not supported. Conversation contexts accept and return client, company, lesson, calendar_event, and booking values. Successful conversation writes emit 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.