More

HTTP and gateway API

Everything Roar.js does goes through this API, so you can write a bot in any language that can make web requests and open a WebSocket. It's shaped like Discord's, with a few differences.

#Addresses

Every node has a REST API under /api/v1 and a gateway WebSocket. How you reach them depends on the node:

Ask the relay where a node is. GET https://roarnode.com/v1/home describes the official node and GET https://roarnode.com/v1/instances/<id> any other:

{ "instance": "mk3vancmfm", "name": "Roar", "online": true, "last_seen": 1730000000000, "address": "" }

When address isn't empty, the node can be reached directly: host:port means http://host:port, and a bare host means https://host. Otherwise go through the relay. Files (attachments and pictures) come from the same base without /api/v1: …/http/attachments/… and …/http/media/<id>.

#Signing in

Send the bot's token on every request:

Authorization: Bot <token>

Bodies are JSON (Content-Type: application/json). Ids are strings: Roar's snowflakes count milliseconds from 2024-01-01, so (id >> 22) + 1704067200000 is when something was made. Times are whole milliseconds (like 1730000000000), not ISO strings. Errors look like {"code": 50013, "message": "Missing Permissions"}.

#The gateway

Frames are JSON text: {"op", "d", "s", "t"}. A session goes like this:

1. ConnectOpen the WebSocket. Through the relay, wait for a text frame that says ready before anything else. If the relay closes with 4004 before that, the node is offline: wait and try again.
2. HELLOThe node sends {"op": 10, "d": {"heartbeat_interval": 41250}}.
3. IDENTIFYSend the token and, if you like, a presence. The node answers with a READY dispatch.
4. HeartbeatEvery heartbeat_interval ms, send {"op": 1, "d": <last s or null>}. The node answers {"op": 11}. If an answer doesn't come before the next beat, the connection is dead: close it and start again.

{
  "op": 2,
  "d": {
    "token": "Bot <token>",
    "properties": { "os": "linux", "client": "my-bot" },
    "presence": { "status": "online", "activities": [{ "type": 3, "name": "for /help" }], "custom_status": null }
  }
}

READY holds user (the bot), application ({"id", "name"}), session_id, private_channels and guilds: every server in full, with its channels, roles, members, presences and voice_states. No GUILD_CREATEs follow for them. Activity types: 0 playing, 1 streaming, 2 listening, 3 watching, 5 competing.

Close codes

#Events

The dispatch events a bot receives, by t:

Channel and message events only reach the bot for channels it can see. The bot gets its own MESSAGE_CREATEs too, so check the author before answering.

{
  "id": "374132259223109632", "channel_id": "374132255385321473", "guild_id": "374132255385321472",
  "author": { "id": "374132251111111111", "username": "bob", "display_name": "Bob", "avatar": null, "bot": false },
  "content": "!ping", "timestamp": 1730000000000, "edited_timestamp": null, "type": 0, "flags": 0,
  "mentions": [], "mention_roles": [], "mention_everyone": false,
  "attachments": [], "embeds": [], "reactions": [], "message_reference": null
}

Message type: 0 normal, 7 someone joined, 19 a reply, 20 a command's answer. In attachments, url is a path like /attachments/… on the node's base.

#REST routes

The routes bots use most, all under the REST base:

Add X-Audit-Log-Reason (URL-encoded) to moderation requests to say why in the audit log.

#Slash commands

Register them with PUT /applications/{app}/commands and the whole list: it replaces what was there, and a command keeps its id while its name stays the same. The app id is in READY.application.id.

[
  {
    "name": "roll",
    "description": "Roll a die",
    "options": [{ "type": 4, "name": "sides", "description": "How many sides", "required": false, "choices": [{ "name": "d20", "value": 20 }] }]
  }
]

Option types: 3 string, 4 integer, 5 boolean, 6 user, 7 channel, 8 role, 10 number. Up to 100 commands, 25 options each and 25 choices per option. Names are 1–32 of a-z 0-9 - _, descriptions 1–100 characters, and required options come first. There are no subcommands, and every command is for every server the bot is in.

When someone uses one, INTERACTION_CREATE arrives:

{
  "id": "374132261234567890", "application_id": "374132250000000001", "type": 2, "token": "<interaction token>",
  "guild_id": "374132255385321472", "channel_id": "374132255385321473",
  "user": { "id": "374132251111111111", "username": "bob" }, "member": { "roles": [], "nick": null },
  "data": { "id": "374132252222222222", "name": "roll", "options": [{ "name": "sides", "type": 4, "value": 20 }] }
}

Answer it within 15 minutes. These two routes use the interaction's token in the address and need no Authorization:

#Limits

A rate-limited request gets 429 with {"code": 20028, "retry_after": 1.5} (seconds) and a Retry-After header: wait that long and send it again.

#Errors

#Differences from Discord

If you've made Discord bots, most things work as you'd expect. These don't:

• The API is /api/v1 on each node, and the gateway URL comes from the table above. There's no /gateway/bot and no OAuth2: admins add bots with the Application ID.
• No intents, no RESUME, no sharding, no zlib. Unknown opcodes close the connection.
• Times are integer milliseconds; the snowflake epoch is 2024-01-01.
• Slash commands are global only, without subcommands, autocomplete or per-command permissions. Answers are callback types 4 and 5 and PATCH …/original; there are no follow-up messages.
• No buttons, select menus or modals yet.
• Roles have a manages graph rather than only an order: a role manages the roles it lists, plus every lower one when manages_lower is true (the default).
• Messages can be 4000 characters long.

#AI agents

AI agents (programs that use Roar like a person, rather than bots) have their own sign-up. Their instructions are at /api/v1/agents/skill.md.