Communications Service API

Overview

The Communications Service (Comms Service) provides real-time messaging and collaboration features for Macro. It manages channels, direct messages, message threads, and real-time notifications via WebSocket connections. Base URL: /comms Authentication: JWT authentication required via the Authorization header.

Core Concepts

Channels

Channels are conversation spaces that can be:

Direct Messages (DM): 1-on-1 conversations between two users
Private: Invitation-only group conversations
Organization: Company-wide or team channels

Each channel maintains:

Participant list
Message history
Typing indicators
Read receipts
Activity tracking

Messages

Messages support:

Rich text content
User mentions (@user)
Document/entity attachments
Reactions (emoji)
Threading (replies to messages)
Real-time delivery via WebSocket

Participants

Users who are members of a channel. Participants can:

Send and receive messages
Add/remove other participants (based on permissions)
Leave channels
See typing indicators

Channels

Create Channel

POST /comms/channels

Creates a new channel of any type.

name

string

Channel name (optional for DMs, required for other types)

channel_type

string

required

Channel type: dm, private, or organization

participants

array

required

Array of participant user IDs (must start with “macro|”)

string

Created channel ID (UUID)

Participants are automatically filtered to only include valid Macro user IDs. At least one participant is required.

{
  "name": "Product Team",
  "channel_type": "private",
  "participants": [
    "macro|[email protected]",
    "macro|[email protected]",
    "macro|[email protected]"
  ]
}

Get or Create DM

POST /comms/channels/get_or_create_dm

Finds an existing DM channel with a user, or creates one if it doesn’t exist.

participant_id

string

required

User ID to start/find DM with

string

Channel ID

created

boolean

Whether a new channel was created

Get or Create Private Channel

POST /comms/channels/get_or_create_private

Finds an existing private channel with the exact participant set, or creates one.

participants

array

required

Array of participant user IDs

name

string

Channel name (if creating)

Get Channel

GET /comms/channels/{channel_id}

Retrieves channel details and recent messages.

channel_id

string

required

Channel ID

limit

integer

Number of messages to return (default: 50)

before

string

Message ID to fetch messages before (for pagination)

string

Channel ID

name

string

Channel name

channel_type

string

Channel type

participants

array

Array of participant objects

messages

array

Recent messages in the channel

created_at

datetime

Channel creation time

updated_at

datetime

Last message time

Update Channel

PATCH /comms/channels/{channel_id}

Updates channel metadata (name, description, etc.).

channel_id

string

required

Channel ID

name

string

New channel name

description

string

Channel description

Delete Channel

DELETE /comms/channels/{channel_id}

Deletes a channel and all its messages.

channel_id

string

required

Channel ID

Deleting a channel is permanent and cannot be undone. All messages and metadata will be removed.

Join Channel

POST /comms/channels/{channel_id}/join

Joins an organization channel.

channel_id

string

required

Channel ID

Leave Channel

POST /comms/channels/{channel_id}/leave

Leaves a channel (removes current user as participant).

Add Participants

POST /comms/channels/{channel_id}/participants

Adds users to a channel.

channel_id

string

required

Channel ID

user_ids

array

required

Array of user IDs to add

Remove Participants

DELETE /comms/channels/{channel_id}/participants

Removes users from a channel.

channel_id

string

required

Channel ID

user_ids

array

required

Array of user IDs to remove

Get Channel Metadata

GET /comms/channels/{channel_id}/metadata

Retrieves channel metadata without messages (lightweight).

Get Channel Transcript

GET /comms/channels/{channel_id}/transcript

Exports full channel message history.

channel_id

string

required

Channel ID

format

string

Export format: json, txt, html (default: json)

Messages

Post Message

POST /comms/channels/{channel_id}/message

Sends a message to a channel.

channel_id

string

required

Channel ID

content

string

required

Message content (supports markdown)

mentions

array

Array of mention objects

attachments

array

Array of attachment objects (documents, links, etc.)

thread_id

string

Parent message ID if replying in a thread

nonce

string

Client-generated nonce for deduplication

string

Created message ID

nonce

string

Echo back the nonce for client correlation

Messages are delivered in real-time to all channel participants via WebSocket. The service also handles:

Updating channel share permissions for attached documents
Sending notifications to mentioned users
Indexing the message for search
Updating channel activity tracking

{
  "content": "Hey team, check out this design document @jane",
  "mentions": [
    {
      "entity_type": "user",
      "entity_id": "macro|[email protected]",
      "display_text": "@jane"
    }
  ],
  "attachments": [
    {
      "entity_type": "document",
      "entity_id": "doc_123",
      "name": "Design Mockups.pdf"
    }
  ],
  "nonce": "client_msg_12345"
}

Update Message

PATCH /comms/channels/{channel_id}/message/{message_id}

Edits a message (must be the sender).

channel_id

string

required

Channel ID

message_id

string

required

Message ID

content

string

required

Updated message content

Delete Message

DELETE /comms/channels/{channel_id}/message/{message_id}

Deletes a message (must be the sender or channel owner).

Post Reaction

POST /comms/channels/{channel_id}/reaction

Adds an emoji reaction to a message.

channel_id

string

required

Channel ID

message_id

string

required

Message ID to react to

emoji

string

required

Emoji character or code

Post Typing Indicator

POST /comms/channels/{channel_id}/typing

Sends a typing indicator (broadcast to other participants via WebSocket).

channel_id

string

required

Channel ID

is_typing

boolean

required

Whether user is currently typing

Get Message with Context

GET /comms/channels/messages/context

Retrieves a message with surrounding context (useful for deep links).

message_id

string

required

Message ID

context_size

integer

Number of messages before/after to include (default: 10)

Mentions

Get Mentions

GET /comms/channels/{channel_id}/mentions

Retrieves all messages in a channel that mention the current user.

channel_id

string

required

Channel ID

Attachments

Get Attachment References

GET /comms/attachments/references

Finds all channels where a specific document/entity has been shared.

entity_id

string

required

Entity ID (e.g., document ID)

entity_type

string

required

Entity type (e.g., “document”)

channels

array

Array of channel IDs where the entity is referenced

Activity

Post Activity

POST /comms/activity

Records user activity for analytics and presence tracking.

activity_type

string

required

Type of activity: view, interact, typing

channel_id

string

Channel ID (for channel-specific activity)

Error Codes

Common Errors

200 - Success
201 - Created
400 - Bad Request (invalid participants, empty content)
401 - Unauthorized (not a channel member)
404 - Channel or message not found
500 - Internal Server Error

Service-Specific Errors

INVALID_PARTICIPANTS - Participants list is empty or contains invalid user IDs
NOT_CHANNEL_MEMBER - User is not a member of the channel
CHANNEL_ARCHIVED - Cannot perform action on archived channel
MESSAGE_TOO_LONG - Message exceeds maximum length
PERMISSION_DENIED - User lacks permission for this action

{
  "error": "INVALID_PARTICIPANTS",
  "message": "participants must be a non-empty list of 'macro|<email>'"
}

Data Models

Channel

interface Channel {
  id: string;                       // UUID
  name?: string;
  channel_type: "dm" | "private" | "organization";
  owner_id: string;
  org_id?: number;
  created_at: string;
  updated_at: string;
  participants: Participant[];
}

Message

interface Message {
  id: string;                       // UUID
  channel_id: string;
  sender_id: string;
  content: string;
  thread_id?: string;               // Parent message for threaded replies
  created_at: string;
  updated_at?: string;
  deleted_at?: string;
}

Participant

interface Participant {
  user_id: string;
  channel_id: string;
  joined_at: string;
  last_read_at?: string;
}

Mention

interface SimpleMention {
  entity_type: string;              // "user", "document", etc.
  entity_id: string;
  display_text: string;             // Text shown in UI (e.g., "@username")
}

Attachment

interface NewAttachment {
  entity_type: string;              // "document", "link", etc.
  entity_id: string;
  name: string;                     // Display name
  url?: string;                     // For link attachments
}

Overview

Core Services

Processing Services

​Overview

​Core Concepts

​Channels

​Messages

​Participants

​Channels

​Create Channel

​Get or Create DM

​Get or Create Private Channel

​Get Channel

​Update Channel

​Delete Channel

​Join Channel

​Leave Channel

​Add Participants

​Remove Participants

​Get Channel Metadata

​Get Channel Transcript

​Messages

​Post Message

​Update Message

​Delete Message

​Post Reaction

​Post Typing Indicator

​Get Message with Context

​Mentions

​Get Mentions

​Attachments

​Get Attachment References

​Activity

​Post Activity

​Error Codes

​Common Errors

​Service-Specific Errors

​Data Models

​Channel

​Message

​Participant

​Mention

​Attachment

Build docs developers (and LLMs) love

Overview

Core Concepts

Channels

Messages

Participants

Channels

Create Channel

Get or Create DM

Get or Create Private Channel

Get Channel

Update Channel

Delete Channel

Join Channel

Leave Channel

Add Participants

Remove Participants

Get Channel Metadata

Get Channel Transcript

Messages

Post Message

Update Message

Delete Message

Post Reaction

Post Typing Indicator

Get Message with Context

Mentions

Get Mentions

Attachments

Get Attachment References

Activity

Post Activity

Error Codes

Common Errors

Service-Specific Errors

Data Models

Channel

Message

Participant

Mention

Attachment