Chat WebSocket API

Velora's chat runs on Socket.IO. You can connect as either a guest (read-only — receive messages but can't send) or as an authenticated user (full chat permissions, scoped by your account's role and channel-specific roles like moderator/VIP).

If you're building a bot, you'll want the authenticated path. Bots authenticate using either:

• A user JWT (the same kind a logged-in browser uses) — fastest path to ship
• An OAuth 2.0 access token from a registered developer app — proper for distributed/published bots

Socket.IO transport. Both websocket and polling work; websocket is recommended for bots.

Pass your JWT or OAuth access token using anyof three methods (the gateway checks all three on connection — first one that's present wins):

1. Socket.IO auth payload (recommended)

import { io } from 'socket.io-client';

const socket = io('wss://api.velora.tv/chat', {
  auth: { token: 'YOUR_JWT_OR_OAUTH_TOKEN' },
  transports: ['websocket'],
});

2. Authorization header

const socket = io('wss://api.velora.tv/chat', {
  extraHeaders: { Authorization: 'Bearer YOUR_TOKEN' },
  transports: ['websocket'],
});

3. Query string

const socket = io('wss://api.velora.tv/chat?token=YOUR_TOKEN', {
  transports: ['websocket'],
});

If no token is sent, you'll connect as a guest (read-only). Authenticated connections receive your role, account-wide permissions, and channel-specific roles automatically — no separate login event needed.

Authenticating connects you to the gateway. To start receiving messages and events for a specific channel, emit joinChannel:

socket.emit('joinChannel', { channelId: 'streamer_user_id_or_username' });

channelIdcan be either the broadcaster's user ID (UUID) or their username — the server resolves both. You can join multiple channels concurrently with the same socket. To leave: socket.emit('leaveChannel', { channelId }).

socket.emit('sendMessage', {
  channelId: 'streamer_user_id_or_username',
  message: 'Hello from my bot!',
  // Optional fields:
  platform: 'velora',         // 'velora' (default), 'twitch', 'kick', 'youtube'
  effect: 'rainbow',           // optional message effect
  effectColor: '#ff00ff',      // optional color override
  replyTo: {                   // optional reply context
    messageId: 'parent_msg_id',
    username: 'parent_author',
    snippet: 'Parent message preview',
  },
});

Server enforces: 500-char max, slow-mode/follower-only/sub-only/emote-only checks per channel, blacklist filtering, and email-verification gating. You'll receive a commandResult event back if your message is rejected.

The gateway emits a wide variety of events. The most useful ones for bots and chat clients:

For published / multi-user bots, register a developer app first — see Getting Started and Authentication. Your bot then uses an OAuth access token per-streamer to connect on their behalf.

For self-hosted single-streamer bots, you can use a long-lived JWT. We recommend the OAuth path even for single-streamer bots so token rotation and scopes work cleanly.

User IDs starting with bot:, streamerbot:, or devapp: are flagged with isBot: true in their newMessage payloads, so chat clients can render bot messages differently if they want.

Need to receive non-chat events too (subscriptions, raids, channel-points redemptions, donations)? Use the Events API in addition to the chat WebSocket — they complement each other.

Velora ships a first-class Streamer.bot bridge. If you're writing a Streamer.bot action that needs to send a Velora chat message, use the bridge instead of speaking Socket.IO directly:

POST https://api.velora.tv/streamerbot/messages
Authorization: Bearer <streamerbot-config-token>
Content-Type: application/json

{
  "channelId": "your_user_id",
  "message": "Hello from Streamer.bot!"
}

Configure the bridge token in your dashboard under Settings → Integrations → Streamer.bot. The bridge handles the WebSocket connection, retries, and rate-limit backoff for you.

Slash commands in Streamer.bot: The bridge automatically recognizes slash commands (messages starting with /) and executes them with the channel owner's permissions. For example, sending "/announceblue Stream starting soon!" via the bridge will execute the announcement command as if the streamer typed it.

Velora supports slash commands for channel moderation and announcements. When sent via the Streamer.bot bridge or from a channel-owned bot, these commands execute with the channel owner's permissions.

Announcement commands

Post styled announcements in chat that are instantly recognizable and attention-grabbing. Perfect for stream start/end notices, important updates, or calls to action.

Example: Streamer.bot announcement

POST https://api.velora.tv/streamerbot/messages
Authorization: Bearer <your-token>
Content-Type: application/json

{
  "channelId": "your_user_id",
  "message": "/announceblue **Stream starting in 5 minutes!** Get ready!"
}

More slash commands are documented in the dashboard under Chat Settings → Commands. Common ones include /timeout, /ban, /mod, /vip, and /raid.

Socket.IO clients reconnect automatically. We accept a heartbeatemit at any cadence to keep your session warm; the gateway responds with the current channel members. If you don't emit anything for a long stretch we may drop you — emit a heartbeat or a ping every 60-120s if your client is otherwise quiet.

After a reconnect, your joinChannelsubscriptions need to be re-emitted — they're scoped to the socket lifetime, not the user. A reconnect handler that re-joins your channel(s) is one of the first things to write.

File an issue on Nexus, or join the Velora Discord and ping a CM in #cm-workspace. If you're hitting a specific event/payload shape mismatch with what's documented here, screenshot the full client-side log and include the connection URL — that'll get an answer fast.