Zrzur Bot API

A bot is a Zrzur account that a program controls. It sits in servers like a member, reads and sends messages, answers slash commands, shows buttons and forms, moderates, posts files and can join voice channels. People install it; your code runs on your own computer or server.

These pages are all you need. Start with Start your bot, then build the complete bot.

How a bot works

1. You create an application in the Developer Portal. It comes with a bot user and a token, the password of the bot.
2. Someone with Manage Server installs the bot in a server and gives it permissions.
3. Your program calls the REST API over HTTPS with the token in the x-bot-token header. This is how a bot acts.
4. Your program keeps one gateway connection open, a WebSocket. This is how a bot hears: commands, button clicks, messages and member changes arrive there as events.

The path from nothing to a finished bot

1. Start your bot: an application, a token, a first command.
2. Applications and tokens: every setting of the Developer Portal, and how to install a bot.
3. Gateway: connect, stay connected, come back after a failure.
4. Slash commands, Answering interactions and Buttons, menus and forms.
5. Messages, Roles and permissions, Moderation.
6. Errors, Rate limits, Keeping tokens safe, Running in production.

Base URLs

Self-hosted servers use their own addresses. GET / on the API returns them, with the limits of that server. Read these fields (the answer has more; this one is shortened):

{
  "zrzur": "26.0.0",
  "ws": "wss://events.zrzur.com",
  "app": "https://app.zrzur.com",
  "features": {
    "autumn": { "enabled": true, "url": "https://cdn.zrzur.com" },
    "january": { "enabled": true, "url": "https://api.zrzur.com/january" },
    "livekit": {
      "enabled": true,
      "nodes": [{ "name": "fra", "lat": 50.11, "lon": 8.68, "public_url": "wss://voice.zrzur.com" }]
    },
    "webhooks": false,
    "forwarding": false,
    "polls": false,
    "server_events": false,
    "limits": {
      "default": { "message_length": 2000, "message_attachments": 5, "file_upload_size_limits": { "attachments": 20000000 } }
    }
  }
}

GET /

Query Node. Fetch the server configuration for this Zrzur instance.

Rate limit: any_dlta, 20 / 10 s

What is not supported

• Sharding. One bot keeps one connection, or several connections that each receive everything. Events cannot be split between processes.
• Slash commands in groups, and server commands in direct messages. In a direct message with the bot, a person can use the bot's global commands that need no server permission. Buttons, selects and forms work there too.
• Webhooks, polls, forwarding and scheduled events where the installation has them switched off. GET / says which are on; see Base URLs.
• Interactions over HTTP on a server where the setting signing_key is empty. There the routes answer FeatureDisabled, and bots use the gateway.
• Bots creating bots or servers, joining by invite, or having friends. People do those. The coverage page lists every endpoint bots are refused.
• The SDK as a package. It is not on npm yet. Every page here works with Node alone; see SDKs.

What each status means

Each endpoint in this reference shows one of these marks.