Skip to main content

Bots

A bot is a user. It has an ID, a username, a profile and an avatar, it appears in member lists, and permissions apply to it exactly as they apply to anyone else. What makes it a bot is that it authenticates with a token instead of a session, and that it belongs to the account that created it.

That is worth saying plainly because it decides most of the answers: if you are wondering whether a bot can do something, ask whether a member with the same roles could.

Creating one​

From the client, open user settings and choose My Bots. Through the API:

POST /bots/create
{ "name": "example" }

The name follows the same rules as a username — two to thirty-two characters, and the same character set. The response carries the bot's token.

That token is the bot's password. It grants everything the bot can do, it does not expire on its own, and there is no way to see it again later without resetting it. Put it wherever you keep secrets, not in the repository.

Present it on every request:

X-Bot-Token: <token>

Authentication covers the header in full, including the user-token case.

Settings that matter​

PATCH /bots/{bot_id}
  • public — whether anyone may add the bot, or only its owner. A private bot can still be invited by its owner, so leave it private until it works.
  • interactions_url — where the bot is called back. Optional, and unused unless you have something listening.
  • analytics — whether usage is counted. Off unless you turn it on.

Getting it into a server​

POST /bots/{target}/invite
{ "server": "<server id>" }

or, for a group:

POST /bots/{target}/invite
{ "group": "<group id>" }

One or the other, never both. Whoever makes the call needs permission to add members where they are adding it, which is the same permission a person needs to invite anyone.

GET /bots/{target}/invite returns what a public bot looks like to somebody deciding whether to add it — name, avatar, description — without requiring a token.

Listing and removing​

  • GET /bots/@me — the bots owned by the authenticated account, with their users.
  • GET /bots/{bot_id} — one of them.
  • DELETE /bots/{bot_id} — deletes the bot and its user. There is no undo, and the account it was in is not notified.

Where to look next​

Everything a bot does after logging in is the ordinary API: it reads events over the WebSocket and calls the same endpoints a client does. The API reference lists all of them.