Bots

A server bot is an account that belongs to one server and signs in with a token instead of a password. It reads and sends messages, reacts, runs polls, uploads files and joins voice channels, using the same API and SDK as everyone else.

Creating one

In Server Settings → Bots, a server owner, an administrator, or anyone with the Create bots permission can add a bot:

1. Choose its name and @handle.
2. Give it roles, and optionally a ceiling on its privileges. The preview shows exactly what it will be able to see and do in each channel.
3. Copy the token. It's shown once, so put it straight into your runtime's secret store.

Its roles, private-channel access and channel overrides apply like anyone's, and the ceiling caps them further. The people who manage a bot can also style its profile (tagline, bio, picture, colours) like their own.

What a bot can and can't do

• It can read the server and its channels, send, edit and react to messages, run polls, upload attachments to a channel, read the audit log if permitted, and join voice channels.
• It can't use direct messages, receive friend requests, change account settings, administer the server, or manage other bots.

A minimal bot

import { ApiService, SocketEventType, SocketManager } from "@refractchat/sdk";

const url = "https://chat.example.com";
const token = process.env.REFRACT_BOT_TOKEN!;

const api = new ApiService();
api.setBaseURL(`${url}/api/v1`);
api.setToken(token);

const { user: me } = await api.auth.getCurrentUser();

const socket = new SocketManager();
socket.on(SocketEventType.CHANNEL_MESSAGE_ADDED, async ({ message }) => {
  // answer mentions, but never itself
  if (message.createdBy === me.id || !message.mentionDirectUserIds?.includes(me.id)) return;

  await api.message.sendMessage({
    channelId: message.channelId,
    content: "Hey! Thanks for the mention.",
    mediaIds: [],
    replyToMessageId: message.id,
  });
});
socket.ensureConnected(url, token);

The repository has a fuller, runnable version in sdk/examples/server-bot.mjs.

Tokens

• A token lasts 90 days.
• Regenerating it invalidates the old one straight away. Disabling the bot revokes it; enable the bot and regenerate a token to bring it back.
• A bot's access also depends on the person who approved it. If they leave the server or lose the authority to grant that access, the bot is suspended until an administrator reviews it and regenerates its token.

People manage bots with their own sign-in, through api.bots (list, create, update, rotateToken, remove, preview). A bot token can't.

Voice

Bots join calls exactly as people do. api.live.getLivekitToken(voiceChannelId) returns a serverUrl and participantToken to pass to the LiveKit client for your runtime, plus an encryptionKey when the call is end-to-end encrypted. The SDK doesn't include a media client.

Joining needs View channel and Connect. A bot in a call hears and sees what everyone else does, and needs Speak, Video and Share screen to publish those. It can't moderate other people in the call. Regenerating, disabling or deleting the bot removes it from calls.

Limits

Bot tokens have rate limits of their own, per bot:

What	Per minute
API reads	120
API writes	60
Attachment uploads	10
Voice tokens	30
Socket connections	30
Socket messages	120

All the bots in one server share ten times each allowance. Over a limit, requests answer 429: back off and retry.

An instance allows 50 bots per server and 10 per creator by default, set by bots: in app.config.yaml.