Writing a bot

@gryt/bot is an SDK for writing Gryt bots in TypeScript. A bot joins a server the way any other client does — a key it holds, a self-signed certificate, and a challenge-response over P-256 — so from the server's side it's a member like any other.

import { GrytBot } from "@gryt/bot";

const bot = new GrytBot({
  host: "chat.example.com",
  nickname: "Helper",
  wants: ["read_messages", "send_messages"],
  description: "Answers questions in #support",
});

bot.command("ping", async (ctx) => ctx.reply("pong"), {
  description: "Check I am alive",
  requires: ["send_messages"],
});

void bot.start();

There's no bot account type, no bot token and no bot bypass. What a bot may do is what an admin agreed to let it do, enforced by the same checks that apply to a person.

This page teaches the shape. The API reference is everything @gryt/bot exports, generated from the source, and there are two bots to copy in the SDK's examples/.

How a bot gets in

It knocks.

The bot starts, knowing only the server's address. It says what it is called and what it wants to be allowed to do.
It's turned away, and a request is left behind.
An admin opens Server settings → Bots, sees the ask, unticks anything they would rather it didn't have, and lets it in.
The approval reaches the bot without a restart. Leave it running.

Nothing to configure on the server, no invite, and no restart.

What a bot asks for is fixed

The first declaration is the only one. A later run asking for more gets the answer to the question the first one asked, and the server won't record the new list at all — a bot can't even change its own name after approval.

That isn't about you. It's about the run that isn't yours, after a published image has been taken over. If a bot genuinely needs more, an admin makes a new registration.

Setting one up in advance

For a compose file or CI, where nobody is watching the first launch: an admin creates the registration first, decides everything up front, and hands over a single-use token.

const bot = new GrytBot({ host, botToken: process.env.GRYT_BOT_TOKEN });

The token is shown once, when it's created. The first bot to present it becomes that registration; after that it stops working.

A bot isn't a person, and can't pretend to be

Bots have their own identity namespace with a BOT_ prefix, so a bot can never hold an id a person could hold. Every surface that shows a member shows a BOT tag beside the name — in the member list and on every message — derived from the identity rather than from anything the bot sends.

People can't take bot-shaped names either: BOT_helper and Bot Helper are refused. Robot and Botany are fine.

Running one

A bot is a container. The support bot example is a folder to copy, with a Dockerfile and a compose file.

services:
  support-bot:
    image: ghcr.io/you/support-bot:latest
    restart: unless-stopped
    environment:
      GRYT_HOST: chat.example.com
    volumes:
      - support-bot-identity:/data

volumes:
  support-bot-identity:

The volume isn't optional

gryt-bot-identity.json is the bot — the id the server knows it by is derived from the key inside it. Keep it and the bot keeps its permissions across restarts and upgrades. Lose it and the server sees a stranger knocking, holding nothing.

Mounting the volume isn't enough on its own. By default the bot writes the file to ./gryt-bot-identity.json, next to the code, and only the bot can move it. identityPath is an option on GrytBot, and the SDK reads no environment variables of its own. The support bot passes process.env.GRYT_IDENTITY_PATH, and its Dockerfile sets that to /data/gryt-bot-identity.json. Without that, a bot works, survives restarts, and loses its identity the next time you rebuild the image.

Asking for the least that works

The permissions a bot declares are the list an admin has to decide about. A long one is a list they can't check, and the ones they untick are the ones you find out about at runtime — so check before you act:

if (bot.can("add_reactions")) {
  await bot.react(conversationId, messageId, "👋");
}

bot.can() answers from what the server said, and stays current: an admin who widens or narrows a bot mid-run is obeyed without a restart.

Commands declare what they need and are skipped rather than attempted when the bot doesn't hold it, so nobody types a command and watches nothing happen:

bot.command("purge", handler, { requires: ["manage_messages"] });

For server admins

Whether bots may knock at all is a switch at the top of the Bots tab. Turn it off and the only way in is a token you hand out yourself.

Approving a bot needs the manage bots permission, which by default only the owner has — approving one is granting permissions to something nobody in the room can vouch for. See Roles and permissions.