Starte deinen Bot

In etwa zehn Minuten hast du einen Bot, der in deinem Testserver auf einen Slash-Befehl antwortet. Du brauchst ein Zrzur-Konto, einen eigenen Server und Node.js 22 oder neuer. Installieren musst du nichts.

1. Erstelle eine Anwendung

Wähle im Entwicklerportal „Neue Anwendung“, gib einen Namen ein und wähle „Erstellen“. Die Anwendung bringt ein Bot-Konto mit. Meine Anwendungen öffnen

2. Kopiere das Token

Das Token erscheint einmal, direkt nach dem Erstellen der Anwendung. Kopiere es jetzt. Wer das Token hat, steuert den Bot.

3. Installiere den Bot in einem Testserver

Wähle im Tab „Übersicht“ deiner Anwendung „Zu einem Server hinzufügen“ und dann einen Server, auf dem du „Server verwalten“ hast. Mehr zum Installieren

Mach das vor dem ersten Start. Ein Bot, der nicht auf dem Server ist, bekommt beim Schreiben in dessen Kanäle 403 MissingPermission, und das sieht aus wie eine fehlende Berechtigung. Ist der Bot auf diesem Server?

4. Keine Bibliothek nötig

Node.js 22 bringt alles mit: Die API ist einfaches HTTP und WebSocket. Die offizielle Bibliothek @zrzur/sdk lässt sich noch nicht herunterladen. Über die SDKs

5. Schreib deinen ersten Bot

Speichere das als hello-raw.mjs in einem leeren Ordner. Es registriert /hello und antwortet darauf.

// Hello World without any library: Node 22+, fetch and WebSocket only.
//
//   ZRZUR_BOT_TOKEN=YOUR_BOT_TOKEN node hello-raw.mjs

const token = process.env.ZRZUR_BOT_TOKEN;
const api = process.env.ZRZUR_API_URL ?? "https://api.zrzur.com";
const ws = process.env.ZRZUR_WS_URL ?? "wss://events.zrzur.com";

if (!token) {
  console.error("Set ZRZUR_BOT_TOKEN first.");
  process.exit(2);
}

/** An interaction's token is in its path: it must never reach a log */
const masked = (path) =>
  path.replace(/(\/interactions\/[^/]+\/)[^/]+/, "$1***");

async function rest(method, path, body) {
  const response = await fetch(api + path, {
    method,
    headers: {
      "x-bot-token": token,
      ...(body ? { "content-type": "application/json" } : {}),
    },
    body: body ? JSON.stringify(body) : undefined,
  });
  if (!response.ok)
    throw new Error(
      `${method} ${masked(path)}: ${response.status} ${await response.text()}`,
    );
  return response.status === 204 ? null : response.json();
}

// 1. Who am I? A bot's application id is its user id.
const me = await rest("GET", "/users/@me");

// 2. Register the global /hello command (PUT replaces the whole list).
await rest("PUT", `/applications/${me._id}/commands`, [
  { name: "hello", description: "Say hello" },
]);

// 3. Connect to the gateway and answer interactions.
const socket = new WebSocket(`${ws}/?version=1&format=json`);
// intents 33 = SERVERS (1) + INTERACTIONS (32): commands, nothing else
socket.addEventListener("open", () =>
  socket.send(JSON.stringify({ type: "Authenticate", token, intents: 33 })),
);

async function handle(event) {
  if (event.type === "Ready") console.log(`ready as ${me.username}`);
  if (
    event.type === "InteractionCreate" &&
    event.interaction.command?.name === "hello"
  ) {
    const { _id, token: interactionToken } = event.interaction;
    // answer within 3 seconds
    await rest("POST", `/interactions/${_id}/${interactionToken}/callback`, {
      type: "Message",
      data: { content: "Hello from Zrzur!" },
    });
  }
}

socket.addEventListener("message", ({ data }) => {
  const event = JSON.parse(data);
  // several events can arrive together in one Bulk packet
  for (const item of event.type === "Bulk" ? event.v : [event])
    handle(item).catch(console.error);
});

// keep the connection alive
setInterval(
  () => socket.send(JSON.stringify({ type: "Ping", data: Date.now() })),
  20_000,
);

6. Starte ihn

Setze das Token und starte dann den Bot:

mkdir my-bot
cd my-bot
# save hello-raw.mjs here, then:
export ZRZUR_BOT_TOKEN=YOUR_BOT_TOKEN
node hello-raw.mjs

Sobald das Terminal ready zeigt, tippe /hello in einem Kanal deines Testservers. Der Bot antwortet Hello from Zrzur!

7. Empfange Ereignisse

Der Bot hält eine WebSocket-Verbindung zum Gateway. Befehle, Klicks auf Schaltflächen, neue Nachrichten und Änderungen an Mitgliedern kommen dort als Ereignisse an. Gateway

8. Baue einen echten Bot

Dieser Bot stoppt, wenn die Leitung abbricht, und kennt nur einen Befehl. Der vollständige Bot hat Befehle, Schaltflächen, ein Formular, Moderation, gespeicherte Daten, Fehlerbehandlung und Wiederverbindung, in einer Datei. Baue einen vollständigen Bot