Channel Messages

Endpoints for managing messages within channels

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

Message Endpoints

List Messages

GET /api/channels/{id}/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

GET /api/channels/{id}/messages/pinned

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

POST /api/channels/{id}/messages/post

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

GET /api/channels/{id}/messages/{message_id}

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

GET /api/channels/{id}/messages/{message_id}/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

GET /api/channels/{id}/messages/{message_id}/thread

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

POST /api/channels/{id}/messages/{message_id}/update

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

POST /api/channels/{id}/messages/{message_id}/pin

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

POST /api/channels/{id}/messages/{message_id}/reactions/add

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

POST /api/channels/{id}/messages/{message_id}/reactions/remove

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

DELETE /api/channels/{id}/messages/{message_id}/delete

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.