Zuse

Bot developer docs

Bots are first-class on Zuse: a bot is its own account, listed in channels like anyone else, and signs in with a token. The simplest way to build one is the TypeScript SDK; the protocol underneath is plain JSON over a WebSocket, so any language works.

Get a bot and a token

  1. Sign in, then open Your bots from the menu at the top right.
  2. Create a bot (this picks its username) and make a token with the permissions it needs.
  3. Copy the token straight away. It starts with zb_, is shown once, and only a fingerprint of it is kept. Treat it like a password: never commit it, and revoke it from the same page if it leaks.

Quick start with the SDK

npm install @zusechat/sdk

import { Bot } from "@zusechat/sdk";

const bot = new Bot({ token: process.env.BOT_TOKEN! });

bot.on("message", async (msg) => {
  if (msg.body === "!ping") await msg.reply("pong");
});
bot.on("error", console.error);

await bot.connect();
await bot.join("bots");

The SDK reconnects with backoff, rejoins channels, and paces what it sends to the flood limit. Its README lists every event and option.

Permissions

A token carries scopes that apply in every channel the bot joins. Give a bot the least it needs.

A bot with the whisper scope can answer privately: msg.replyPrivately("...") or bot.whisper(channel, user, "...") sends a message that only that person sees, so a help bot does not fill the channel. Nothing is stored, the person can mute the bot, and it is limited per person. Private messages sent to the bot arrive as the whisper event.

Scopes are only half of it: moderation also needs a high enough role in the channel, the same rank rules as for people (an op cannot act on the owner or another op).

Without the SDK

Open a WebSocket to wss://api.zuse.chat/gateway and send your first frame within a few seconds, or the connection is closed. Every frame is JSON shaped { "op": "...", "d": { ... }, "id": "optional" }.

{ "op": "identify", "d": { "protocol": 1, "token": "zb_..." } }
{ "op": "join", "d": { "channel": "bots" } }
{ "op": "say",  "d": { "channel": "bots", "body": "hello" } }

The gateway answers ready, then channel_state for each join (topic, members, your role, recent history), then streams message, user_join, user_leave and other frames. Errors come aserror frames carrying a code such as muted or read_only, and sending too fast is answered with a rate_limited frame saying how long to wait. The schemas are in the @zusechat/protocol package.

Limits and rules