Start here

How bots work

A bot is a program with its own Roar account. Roar tells it what's happening, and it decides what to do. Here's everything that happens in between.

#A bot is an account

Every bot has its own Roar account, with a name, a picture and a BOT tag next to its name. You make it in User Settings → Developer → New Bot, and Roar gives you two things:

• An Application ID. Server admins paste it into Server Settings → Bots to add your bot to their server. It's not a secret.
• A token. It's the bot's password: your program sends it to sign in. Keep it secret. Anyone with the token can act as your bot, so never put it in a message or a public file. If it leaks, press Reset Token and the old one stops working at once.

A bot belongs to the node where you made it (most bots live on the official node). One account can own up to 25 bots.

#Events in, actions out

Your bot talks to Roar in two ways at the same time:

1. The gateway is a connection the bot keeps open the whole time. Roar pushes events down it the moment things happen: a message is sent, someone joins, a reaction is added, a slash command is used. The bot also sends a small "still here" heartbeat every 41 seconds so Roar knows it hasn't vanished.
2. The REST API is how the bot acts. Each action, like sending a message, adding a reaction or giving a role, is one web request.

A bot hears about everything in the channels it's allowed to see. There's nothing to subscribe to. Roar.js keeps the connection, the heartbeats and reconnecting going for you, so your code is just "when this happens, do that".

#One message, start to finish

Bob types !ping in #general. Here's what happens:

1. Bob sends itBob's app sends the message to the node, which saves it and passes it on to everyone who can see #general.
2. The bot hears itYour bot can see #general, so it gets a MESSAGE_CREATE event on the gateway with the message, the author and the channel. In Roar.js that's your bot.on("message") handler running.
3. The bot decidesYour code checks msg.content === "!ping". It is, so it calls msg.reply("Pong!").
4. The bot actsRoar.js sends POST /channels/<general>/messages with the reply. The node checks the bot is allowed to talk there and posts it.
5. Everyone sees it"Pong!" appears for everyone in #general, as a reply to Bob, a fraction of a second later.

#Slash commands

Slash commands are the friendliest way to use a bot: people type / and pick from a list, with each option explained.

1. The bot tells Roar its commandsWhen it connects, the bot sends its list (name, description, options). Roar.js does this from your bot.command(...) calls. Every server the bot is in gets the new list straight away.
2. Someone uses oneThey type /roll sides: 20 in the Roar desktop app. The node checks they're allowed to use commands in that channel, and that the bot is online.
3. The bot gets an interactionAn INTERACTION_CREATE event arrives with the command, the options and who used it.
4. The bot answersIt replies to the interaction, and the answer shows up under the command. It can answer for everyone or only for that person (ephemeral), or say "thinking..." first and answer within 15 minutes.

#Permissions and roles

A bot is a member like anyone else, so it follows the same rules. When it's added to a server it gets only what @everyone can do: read and send messages in normal channels, add reactions, use commands.

To do more, a server admin gives the bot a role. To hand out roles, kick people or time them out, the bot needs a role with that permission (Manage Roles, Kick Members...) that sits above the roles or people it acts on. If it isn't allowed, the node refuses with a clear error (code 50013, missing permissions), and the bot carries on.

#Nodes and the relay

Roar isn't one big server. It's made of nodes: the official node, plus nodes people host on their own PCs. Each node has a short id like mk3vancmfm. Many of them sit at home behind a router, so they connect out to the relay at roarnode.com, which passes traffic through to them.

Your bot uses the same route. Roar.js asks the relay where the node is, then connects through it (or straight to the node if it has a public address). You don't have to do anything: it connects to the official node unless you tell it another one.

#Where bots run

• Coded bots run wherever you start their program: your PC while you build and test, then something that stays switched on (a spare PC, a Raspberry Pi, or a small server). When the program stops, the bot shows as offline. Roar.js reconnects by itself after network hiccups and node restarts.
• Bot Builder bots run inside your Roar desktop app, so they're online while Roar is open on your PC.
• Webhooks don't run at all. They're a link that posts a message whenever something sends a request to it.

Ready? Make your first bot, or click one together in Bot Builder.