Skip to main content
The Channels API provides comprehensive endpoints for creating, reading, updating, and deleting messages within channels.

​
Message Endpoints

​
List Messages

curl -X GET "https://your-domain.com/api/channels/ch_abc123/messages?skip=0&limit=50" \
  -H "Authorization: Bearer YOUR_TOKEN"
Retrieves messages from a channel with pagination. Query Parameters:
  • skip (integer): Number of messages to skip (default: 0)
  • limit (integer): Maximum number of messages to return (default: 50)
Response: Array of message objects with user information and reactions

​
Get Pinned Messages

curl -X GET "https://your-domain.com/api/channels/ch_abc123/messages/pinned?page=1" \
  -H "Authorization: Bearer YOUR_TOKEN"
Retrieves pinned messages from a channel. Query Parameters:
  • page (integer): Page number for pagination (default: 1, 20 items per page)
Response: Array of pinned message objects

​
Post Message

curl -X POST "https://your-domain.com/api/channels/ch_abc123/messages/post" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Hello, world!",
    "data": {
      "files": []
    }
  }'
Request Body:
  • content (string, required): Message text content
  • reply_to_id (string, optional): ID of message being replied to
  • parent_id (string, optional): ID of thread parent message
  • data (object, optional): Additional message data (files, etc.)
  • meta (object, optional): Message metadata
  • temp_id (string, optional): Temporary client-side ID for optimistic updates
Response: Created message object

​
Get Single Message

curl -X GET "https://your-domain.com/api/channels/ch_abc123/messages/msg_xyz" \
  -H "Authorization: Bearer YOUR_TOKEN"
Retrieves a specific message by ID. Response: Message object with user information

​
Get Message Data

curl -X GET "https://your-domain.com/api/channels/ch_abc123/messages/msg_xyz/data" \
  -H "Authorization: Bearer YOUR_TOKEN"
Retrieves only the data field of a message (files, attachments, etc.). Response: Message data object

​
Get Thread Replies

curl -X GET "https://your-domain.com/api/channels/ch_abc123/messages/msg_xyz/thread?skip=0&limit=50" \
  -H "Authorization: Bearer YOUR_TOKEN"
Retrieves all replies in a message thread. Query Parameters:
  • skip (integer): Number of replies to skip (default: 0)
  • limit (integer): Maximum number of replies to return (default: 50)
Response: Array of reply message objects

​
Update Message

curl -X POST "https://your-domain.com/api/channels/ch_abc123/messages/msg_xyz/update" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Updated message content"
  }'
Request Body:
  • content (string, required): Updated message text
  • data (object, optional): Updated message data
  • meta (object, optional): Updated metadata
Response: Updated message object Notes:
  • Users can update their own messages
  • Admins and users with write access can update any message in the channel
  • Updates trigger real-time socket events to all channel members

​
Pin/Unpin Message

curl -X POST "https://your-domain.com/api/channels/ch_abc123/messages/msg_xyz/pin" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "is_pinned": true
  }'
Request Body:
  • is_pinned (boolean, required): true to pin, false to unpin
Response: Updated message object with pin information

​
Add Reaction

curl -X POST "https://your-domain.com/api/channels/ch_abc123/messages/msg_xyz/reactions/add" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "👍"
  }'
Request Body:
  • name (string, required): Emoji or reaction name
Response: Boolean indicating success

​
Remove Reaction

curl -X POST "https://your-domain.com/api/channels/ch_abc123/messages/msg_xyz/reactions/remove" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "👍"
  }'
Request Body:
  • name (string, required): Emoji or reaction name to remove
Response: Boolean indicating success

​
Delete Message

curl -X DELETE "https://your-domain.com/api/channels/ch_abc123/messages/msg_xyz/delete" \
  -H "Authorization: Bearer YOUR_TOKEN"
Deletes a message and all its reactions. Response: Boolean indicating success Notes:
  • Users can delete their own messages
  • Admins and users with write access can delete any message
  • Deleting a message with replies will keep the replies but remove the parent content
  • Emits real-time socket events to notify all channel members

​
Message Object Schema

{
  "id": "msg_abc123",
  "user_id": "user_123",
  "channel_id": "ch_xyz",
  "content": "Hello, world!",
  "reply_to_id": null,
  "parent_id": null,
  "is_pinned": false,
  "pinned_by": null,
  "pinned_at": null,
  "data": {
    "files": []
  },
  "meta": {},
  "user": {
    "id": "user_123",
    "name": "Alice",
    "role": "user"
  },
  "reactions": [
    {
      "name": "👍",
      "count": 3,
      "users": [
        {"id": "user_123", "name": "Alice"},
        {"id": "user_456", "name": "Bob"},
        {"id": "user_789", "name": "Charlie"}
      ]
    }
  ],
  "reply_count": 5,
  "latest_reply_at": 1709567890123456789,
  "created_at": 1709567800000000000,
  "updated_at": 1709567800000000000
}

​
Real-time Updates

All message operations emit real-time events via WebSocket to channel members:
  • message - New message posted
  • message:update - Message edited
  • message:delete - Message deleted
  • message:reply - New reply in thread
  • message:reaction:add - Reaction added
  • message:reaction:remove - Reaction removed

​
Model Mentions

Messages can mention AI models using the @model_id syntax. When a model is mentioned:
  1. The model automatically responds to the message
  2. Thread history is included in the model’s context
  3. Images from thread messages are processed
  4. Response is posted as a new message with model metadata

​
Webhooks

Messages can be posted via webhooks without authentication. See the Webhooks section for details.