Chat

Real-time messaging with channels, messages, and reactions

The Chat API handles real-time messaging through channels (DMs, groups, rooms), message operations, reactions, and typing indicators.

Channel Types

Type	Description
`dm`	Direct message between two users
`group`	Private group with invited members
`room`	Public room anyone can join

Member Roles

Role	Description
`owner`	Channel creator, full control
`admin`	Can manage members and settings
`member`	Regular participant

List Channels

Get all channels you're a member of.

GET /v1/channels?include_hidden=false
Authorization: Bearer {token}

Query Parameters:

Param	Default	Description
`include_hidden`	false	Include hidden/archived channels

Response:

[
  {
    "id": "123456789",
    "type": "dm",
    "name": "",
    "owner_id": null,
    "created_at": 1703520000,
    "unread_count": 5,
    "other_user_id": "987654321",
    "other_user_name": "FriendName"
  },
  {
    "id": "234567890",
    "type": "group",
    "name": "Project Team",
    "owner_id": "123456",
    "created_at": 1703510000,
    "unread_count": 0
  }
]

Create Channel

Create a new channel.

POST /v1/channels
Authorization: Bearer {token}

Create a DM:

{
  "type": "dm",
  "user_id": "67890"
}

Create a Group:

{
  "type": "group",
  "name": "My Group"
}

Create a Room:

{
  "type": "room",
  "name": "Public Room"
}

Response (201 Created):

{
  "id": "123456789",
  "type": "group",
  "name": "My Group",
  "owner_id": "12345",
  "created_at": 1703520000
}

Error Codes:

Code	Description
`CHAT_CANNOT_DM_SELF`	Cannot create DM with yourself
`CHAT_DM_BLOCKED_USER`	User is blocked

Get Channel

Get channel details.

GET /v1/channels/{channelID}
Authorization: Bearer {token}

Response:

{
  "id": "123456789",
  "type": "group",
  "name": "My Group",
  "owner_id": "12345",
  "created_at": 1703520000
}

Update Channel

Update channel settings (admins only, not for DMs).

PUT /v1/channels/{channelID}
Authorization: Bearer {token}

{
  "name": "New Group Name"
}

Error Codes:

Code	Description
`CHAT_NOT_ADMIN`	Only admins can update
`CHAT_CANNOT_MODIFY_DM`	Cannot modify DM channels

List Members

Get all members of a channel.

GET /v1/channels/{channelID}/members
Authorization: Bearer {token}

Response:

[
  {
    "user_id": "12345",
    "display_name": "UserName",
    "role": "owner",
    "joined_at": 1703520000
  }
]

Add Member

Add a member to a group/room (admins only).

POST /v1/channels/{channelID}/members
Authorization: Bearer {token}

{
  "user_id": "67890",
  "role": "member"
}

Response (201 Created):

{
  "user_id": "67890",
  "display_name": "NewMember",
  "role": "member",
  "joined_at": 1703520000
}

Remove Member

Remove a member or leave channel.

DELETE /v1/channels/{channelID}/members/{userID}
Authorization: Bearer {token}

Response: 204 No Content

Notes:

Users can remove themselves (leave)
Admins can remove other members (except owner)
Owner cannot be removed

List Messages

Get messages with pagination.

GET /v1/channels/{channelID}/messages?limit=50&before={messageID}
Authorization: Bearer {token}

Query Parameters:

Param	Default	Description
`limit`	50	Max messages (1-100)
`before`	-	Cursor for pagination

Response:

{
  "messages": [
    {
      "id": "111222333",
      "channel_id": "123456789",
      "sender_id": "12345",
      "sender_name": "UserName",
      "body": "Hello everyone!",
      "attachments": [],
      "inline_emotes": [],
      "created_at": 1703520000,
      "edited_at": null,
      "deleted": false,
      "reactions": [
        {
          "emote_asset_id": "999888777",
          "count": 3,
          "user_ids": ["12345", "67890", "11111"]
        }
      ]
    }
  ],
  "has_more": true
}

Send Message

Send a message to a channel.

POST /v1/channels/{channelID}/messages
Authorization: Bearer {token}

{
  "body": "Hello everyone!",
  "attachments": [
    {
      "asset_id": 555666777,
      "filename": "image.png",
      "content_type": "image/png",
      "size_bytes": 102400
    }
  ],
  "inline_emotes": [
    {
      "shortcode": "smile",
      "asset_id": 888999000,
      "start_index": 6,
      "end_index": 12
    }
  ]
}

Response (201 Created):

{
  "id": "111222333",
  "channel_id": "123456789",
  "sender_id": "12345",
  "sender_name": "UserName",
  "body": "Hello everyone!",
  "attachments": [...],
  "inline_emotes": [...],
  "created_at": 1703520000,
  "deleted": false
}

Error Codes:

Code	Description
`CHAT_EMPTY_MESSAGE`	Message body or attachments required
`CHAT_NOT_MEMBER`	Not a channel member

Edit Message

Edit your own message.

PUT /v1/channels/{channelID}/messages/{messageID}
Authorization: Bearer {token}

{
  "body": "Updated message text"
}

Response:

{
  "id": "111222333",
  "channel_id": "123456789",
  "sender_id": "12345",
  "body": "Updated message text",
  "created_at": 1703520000,
  "edited_at": 1703520100,
  "deleted": false
}

Error Codes:

Code	Description
`CHAT_NOT_MESSAGE_AUTHOR`	Can only edit own messages
`CHAT_MESSAGE_NOT_FOUND`	Message not found

Delete Message

Delete a message (author or admin).

DELETE /v1/channels/{channelID}/messages/{messageID}
Authorization: Bearer {token}

Response: 204 No Content

Add Reaction

React to a message with an emote.

POST /v1/channels/{channelID}/messages/{messageID}/reactions
Authorization: Bearer {token}

{
  "emote_asset_id": "999888777"
}

Response (201 Created):

{
  "message": "Reaction added"
}

Error Codes:

Code	Description
`CHAT_REACTION_EXISTS`	Already reacted with this emote

Remove Reaction

Remove your reaction from a message.

DELETE /v1/channels/{channelID}/messages/{messageID}/reactions/{emoteID}
Authorization: Bearer {token}

Response: 204 No Content

Get Attachment URL

Get a presigned download URL for a message attachment.

GET /v1/channels/{channelID}/messages/{messageID}/attachments/{attachmentID}/url?size=512
Authorization: Bearer {token}

Query Parameters:

Param	Default	Description
`size`	full	Thumbnail size: full, 1600, 512, 256, 128

Response:

{
  "url": "https://cdn.ocvr.net/...",
  "expires_at": 1703523600
}

Update Read Cursor

Mark messages as read up to a specific message.

POST /v1/channels/{channelID}/read
Authorization: Bearer {token}

{
  "last_read_message_id": "111222333"
}

Response:

{
  "channel_id": "123456789",
  "last_read_message_id": "111222333",
  "updated_at": 1703520000
}

Typing Indicators

Send Typing

Notify others you're typing.

POST /v1/channels/{channelID}/typing
Authorization: Bearer {token}

Response: 204 No Content

Get Typing Users

See who's currently typing.

GET /v1/channels/{channelID}/typing
Authorization: Bearer {token}

Response:

{
  "typing_users": ["12345", "67890"]
}

Real-time Events

Chat events are pushed via WebSocket. See WebSocket Protocol for:

message - New message
message_update - Message edited
message_delete - Message deleted
reaction_add - Reaction added
reaction_remove - Reaction removed
typing - User is typing