divcord · bot accounts

Enable bot mode

Bot accounts, like any other account, are unique to each server. Turning on a bot for your-server.divcord.gg does not turn it on for any other server.

Register or sign in on the server you want the bot to use.
Open Settings and choose Enable Bot Mode or Bot token under Account.
Confirm with your password. Copy the token. It will only be shown once.

You can still use the account normally in the browser. Rotate or disable the token from the same Settings panel if it leaks.

Server admins can turn member bot accounts off in Dashboard Settings. When that is off, only the server admin role can enable or use a bot token. Admins can also disable bot mode on a specific user from the Users tab, which revokes that account's current & future bot tokens.

Download the library

You'll need Node.js to use the native bot library. Grab the files from Divcord:

curl -O https://divcord.gg/bot/index.js
curl -O https://divcord.gg/bot/example.js
npm install socket.io-client

Treat this token like a password! Do not paste it into a public repo, chat, or share it with anyone.

Connect

const { DivcordBot } = require('./index');

const bot = new DivcordBot({
  server: 'your-server',
  username: 'mybot',
  token: process.env.DIVCORD_BOT_TOKEN,
  prefix: '!'
});

bot.login()
  .then(function () { return bot.join('general'); })
  .then(function () { return bot.say('online'); });

Commands

bot.command('ping', function (ctx) {
  return ctx.reply('pong');
});

bot.command('echo', function (ctx) {
  if (!ctx.rest) return ctx.reply('usage: !echo <text>');
  return ctx.reply(ctx.rest);
});

The handler receives bot, message, roomId, args, rest, and reply(). The bot ignores its own messages unless you turn that off.

What a bot can do

Everything below runs as the account. Kick, ban, mute, lock, and delete-other-people's-messages only work if that account can already do those things in the room.

Method	What it does
`login()`	Connect and sign in
`join(roomId)`	Join a room (creates it only if you are allowed to)
`leave(roomId?)`	Leave a room
`say(text, roomId?)`	Send a message
`sendPayload(data, { roomId }?)`	Broadcast JSON to every client in the room
`reply(message, text)`	Reply to a message
`edit(id, text, roomId?)`	Edit one of the bot's messages
`delete(id, roomId?)`	Delete a message
`react(id, emoji, roomId?)`	Toggle a reaction
`pin(id, roomId?)` / `unpin(id, roomId?)`	Pin or unpin a message (mods, or either person in a DM)
`poke(username, roomId?)`	Poke someone in the room
`invite(roomId, usernames)`	Invite people to an invite-only room
`openDm(username)`	Open a private thread
`listRooms()` / `listUsers()`	See public rooms and registered accounts
`uploadFile(path)`	Upload a file, then attach `file.id` to a message
`kick / ban / mute / unmute / lock / unlock`	Moderation, when the account has it
`updateProfile(data)`	Avatar, bio, flair, link
`disconnect()`	Sign out and close the connection

Events

bot.on(event, fn) listens for what the room is already doing: new messages, edits, joins, pokes, and so on. message is the handy name for a new chat line. After a disconnect, the library signs back in and rejoins the rooms it still holds.

For other languages

The library is a thin Socket.IO client. If you are not using Node, send these events yourself after connecting to the server origin (named servers use the /s/<name> namespace).

Event	Payload
`authenticate`	`{ type: 'bot', username, token }` or `{ type: 'login', username, password }`
`enable_bot`	`{ password }` returns the token once
`rotate_bot_token`	`{ password }` issues a new token and retires the old one
`disable_bot`	`{ password }` turns bot mode off
`embed_payload`	`{ roomId, data }` broadcasts JSON to the room. Inbound event is also `embed_payload` with `{ roomId, data, from, timestamp }`.

Only a hash of the token is stored. The plaintext value is never kept after you close the Settings panel. Bots follow the same send and react rate limits as everyone else.

If you want a moderation bot without writing one, Automod is a complete script on top of this library.