Chat can only be sent and received over the WebSocket. The REST API has no chat endpoint.
---
## Ranks
| Name | Value |
|-----------|-------|
| Moderator | 2 |
| Admin | 3 |
| Owner | 4 |
| Creator | 5 |
A bot's rank is capped at the rank of the user who issued its token. Every REST endpoint that modifies state has a minimum rank requirement listed in its description.
---
## Issuing a token
Tokens are issued in the channel settings modal on the **Bots** tab. You need at least moderator rank (2) to see this tab.
Fill in a name (1–20 alphanumeric, `-`, `_` characters), choose a rank, and click **Issue Token**. The token is shown **once** — copy it immediately. It looks like:
```
cbt_a3f8e2...64 hex characters...
```
To revoke a token, click **Revoke** next to it in the table. Any live WebSocket connections using that token are disconnected immediately.
---
## WebSocket connection
The bot authenticates by passing the token in the socket.io `auth` object:
```js
const io = require('socket.io-client');
const socket = io('http://your-server:1337', {
auth: { token: process.env.BOT_TOKEN }
});
```
> **Port note:** socket.io runs on the port defined by `io.port` in your server config (default 1337), which is separate from the HTTP port used for the web UI and REST API.
### Join sequence
After connecting you must wait for the `login` event before emitting `joinChannel`, otherwise the server will ignore it:
| 403 | Token not authorized for this channel, or rank too low |
| 404 | Resource not found |
| 503 | Channel is not currently active (no users in it) |
---
### Playlist
Playlist endpoints require the channel to be active (at least one user present).
#### `GET /channels/:channel/playlist`
Returns the current playlist and which item is playing.
No minimum rank.
**Response:**
```json
{
"items": [
{
"uid": 1,
"id": "dQw4w9WgXcQ",
"type": "yt",
"title": "Rick Astley - Never Gonna Give You Up",
"seconds": 212,
"duration": "3:32",
"thumb": { "url": "..." },
"meta": {}
}
],
"currentIndex": 0,
"locked": false
}
```
`uid` is the server-assigned unique ID for the playlist slot. Use it for delete/jump operations.
#### `POST /channels/:channel/playlist`
Queue a new item. Minimum rank: **2 (Mod)**.
Returns `202 Accepted` immediately because media lookup is asynchronous. If the bot's permissions don't allow the add (e.g. playlist is locked and rank is too low), a `400` is returned synchronously.
Remove a playlist item by uid. Minimum rank: **3 (Admin)**.
#### `PUT /channels/:channel/playlist/playing`
Skip to a specific item. Minimum rank: **2 (Mod)**.
**Body:**
```json
{ "uid": 3 }
```
#### `POST /channels/:channel/playlist/shuffle`
Shuffle the playlist. Minimum rank: **3 (Admin)**.
#### `POST /channels/:channel/playlist/clear`
Clear the entire playlist. Minimum rank: **3 (Admin)**.
---
### Emotes
Emote endpoints read and write directly to the database and work even when the channel is offline. If the channel happens to be active, changes are broadcast live to connected users.
Kick a user. Minimum rank: **2 (Mod)**. Cannot kick users with equal or higher rank.
**Body:**
```json
{ "reason": "Spamming" }
```
`reason` is optional, defaults to `"Kicked by bot"`.
#### `POST /channels/:channel/users/:name/ban`
Ban a user by name. Minimum rank: **3 (Admin)**. Cannot ban users with equal or higher rank.
**Body:**
```json
{ "reason": "Ban evasion" }
```
`reason` is optional, defaults to `"Banned by bot"`.
#### `DELETE /channels/:channel/users/:name/ban`
Remove a ban. Minimum rank: **3 (Admin)**.
#### `PUT /channels/:channel/users/:name/rank`
Change a user's channel rank. Minimum rank: **4 (Owner)**. Cannot assign a rank equal to or higher than your own, and cannot target users with equal or higher rank.
**Body:**
```json
{ "rank": 2 }
```
---
### Settings
Settings endpoints require the channel to be active. Minimum rank: **4 (Owner)** for both read and write.
-`status`: one of `draft | scheduled | paused | running | completed | failed | canceled` (`running` is accepted but normalized to `scheduled` on write)
Revoke a bot token. Any live socket connections for that bot are disconnected immediately. Requires channel rank ≥ 2 and your rank must be ≥ the bot's rank.
---
## Demo bot
A working example with a TUI is in `examples/demo-bot/`.
```
cd examples/demo-bot
npm install
cp .env.example .env
# Edit .env: fill in BOT_TOKEN, CHANNEL, SERVER_URL, API_BASE
