Ihr erster discord.js-Bot: ein Slash-Befehl Schritt für Schritt

Wir schreiben einen Bot mit der Bibliothek discord.js und zwei Slash-Befehlen: /ping und /pozdrav („grüßen“) mit einem Parameter. Wir erklären jede Zeile und betreiben den Bot am Ende bei StormHost.

So funktioniert es#

Ein Bot mit Slash-Befehlen besteht aus drei Teilen:

1. Befehlsdefinitionen – Name, Beschreibung und Parameter des Befehls. Sie teilen sie Discord einmal mit, über ein separates Skript über die REST-API (Registrierung).
2. Der laufende Bot – verbindet sich mit Discord (dem Gateway) und wartet auf Ereignisse.
3. Interaktionsverarbeitung – wenn jemand einen Befehl verwendet, sendet Discord dem Bot eine Interaktion, und der Bot muss innerhalb von 3 Sekunden antworten. Andernfalls sieht der Nutzer, dass die Anwendung nicht reagiert hat.

Registrierung und Betrieb des Bots sind getrennt: Sie müssen die Befehle nur dann neu registrieren, wenn Sie ihre Definition ändern (Name, Beschreibung, Parameter). Änderungen am Antwortcode brauchen keine neue Registrierung.

Projekt anlegen#

1. Erstellen Sie einen Ordner muj-bot und öffnen Sie darin ein Terminal (in VS Code Strg+`).

2. Legen Sie das Projekt an und installieren Sie die Bibliotheken:

   npm init -y
   npm install discord.js dotenv

   • npm init -y – erstellt package.json mit Standardwerten (-y = beantwortet jede Frage mit „ja“).
   • npm install discord.js dotenv – installiert discord.js und dotenv (lädt die Datei .env) und trägt sie in dependencies ein.

3. Setzen Sie in package.json die Felder "main": "index.js" und "type": "commonjs". Die Beispiele verwenden require(). Die Felder erklärt die Anleitung Hochladen und Starten des Bots.

4. Erstellen Sie eine Datei .env:

   DISCORD_TOKEN=<BOT_TOKEN>
   CLIENT_ID=<APPLICATION_ID>
   GUILD_ID=<SERVER_ID>

   Ersetzen Sie <BOT_TOKEN> durch Ihren Bot-Token, <APPLICATION_ID> durch die Application ID von der Seite General Information im Developer Portal und <SERVER_ID> durch die ID Ihres Test-Discord-Servers. Wo Sie diese finden, beschreibt die Anleitung Token und Intents.

5. Erstellen Sie eine Datei .gitignore mit zwei Zeilen: node_modules und .env.

Die resultierende Struktur:

muj-bot/
├── .env
├── .gitignore
├── package.json
├── package-lock.json
├── index.js
├── deploy-commands.js
└── commands/
    └── utility/
        ├── ping.js
        └── pozdrav.js

Befehle#

Jeder Befehl hat eine eigene Datei mit zwei Teilen: data (die Definition für Discord) und execute (was passiert, wenn jemand ihn verwendet).

const { SlashCommandBuilder, MessageFlags } = require('discord.js');

module.exports = {
  data: new SlashCommandBuilder()
    .setName('ping')
    .setDescription('Antwortet mit Pong! und zeigt die Latenz des Bots.'),

  async execute(interaction) {
    await interaction.reply({
      content: `Pong! Latenz: ${interaction.client.ws.ping} ms`,
      flags: MessageFlags.Ephemeral,
    });
  },
};

Ein Befehl mit Parameter:

const { SlashCommandBuilder } = require('discord.js');

module.exports = {
  data: new SlashCommandBuilder()
    .setName('pozdrav')
    .setDescription('Grüßt die angegebene Person.')
    .addStringOption((option) =>
      option.setName('jmeno').setDescription('Wen grüßen').setRequired(true),
    ),

  async execute(interaction) {
    const jmeno = interaction.options.getString('jmeno');
    await interaction.reply(`Hallo, ${jmeno}! ${interaction.user.username} lässt grüßen.`);
  },
};

• .addStringOption(…) – fügt einen Textparameter hinzu (jmeno = Name). Discord bietet ihn dem Nutzer als Feld jmeno: an.
• .setRequired(true) – der Parameter ist erforderlich; ohne ihn lässt sich der Befehl nicht absenden.
• interaction.options.getString('jmeno') – liest den Wert des Parameters.
• interaction.user.username – der Benutzername der Person, die den Befehl verwendet hat.
• interaction.reply('…') – eine öffentliche Antwort im Kanal.

Weitere Parametertypen: addIntegerOption (ganze Zahl), addBooleanOption (ja/nein), addUserOption (Servermitglied), addChannelOption (Kanal), addRoleOption (Rolle).

Befehle registrieren#

Das Skript deploy-commands.js lädt die Definitionen aller Befehle und sendet sie an Discord. Sie führen es von Hand aus, nur wenn Sie einen Befehl hinzufügen oder seine Definition ändern.

const fs = require('node:fs');
const path = require('node:path');
require('dotenv').config({ path: path.join(__dirname, '.env'), quiet: true });
const { REST, Routes } = require('discord.js');

const commands = [];
const foldersPath = path.join(__dirname, 'commands');
for (const folder of fs.readdirSync(foldersPath)) {
  const commandsPath = path.join(foldersPath, folder);
  for (const file of fs.readdirSync(commandsPath).filter((f) => f.endsWith('.js'))) {
    const command = require(path.join(commandsPath, file));
    if ('data' in command && 'execute' in command) {
      commands.push(command.data.toJSON());
    } else {
      console.log(`[WARNUNG] Der Datei ${file} fehlt "data" oder "execute".`);
    }
  }
}

const rest = new REST().setToken(process.env.DISCORD_TOKEN);

(async () => {
  try {
    console.log(`Befehle werden registriert: ${commands.length}`);
    const data = await rest.put(
      Routes.applicationGuildCommands(process.env.CLIENT_ID, process.env.GUILD_ID),
      { body: commands },
    );
    console.log(`Fertig, registrierte Befehle: ${data.length}`);
  } catch (error) {
    console.error(error);
  }
})();

Führen Sie es auf Ihrem Computer im Projektordner aus:

node deploy-commands.js

Befehle werden registriert: 2
Fertig, registrierte Befehle: 2

Server- oder globale Befehle?#

Wenn Sie denselben Befehl sowohl für den Server als auch global registriert haben, sehen Sie ihn auf Ihrem Testserver doppelt. Löschen Sie vor dem Wechsel zur globalen Registrierung die Serverbefehle: Führen Sie die Serverregistrierung mit einer leeren Liste aus (body: []).

Discord begrenzt das Anlegen von Befehlen auf 200 pro Tag und Server. Führen Sie das Registrierungsskript deshalb nicht bei jedem Start des Bots aus.

Die Hauptdatei des Bots#

const fs = require('node:fs');
const path = require('node:path');
require('dotenv').config({ path: path.join(__dirname, '.env'), quiet: true });
const { Client, Collection, Events, GatewayIntentBits, MessageFlags } = require('discord.js');

const client = new Client({ intents: [GatewayIntentBits.Guilds] });

// Befehle aus dem Ordner commands laden
client.commands = new Collection();
const foldersPath = path.join(__dirname, 'commands');
for (const folder of fs.readdirSync(foldersPath)) {
  const commandsPath = path.join(foldersPath, folder);
  for (const file of fs.readdirSync(commandsPath).filter((f) => f.endsWith('.js'))) {
    const command = require(path.join(commandsPath, file));
    if ('data' in command && 'execute' in command) {
      client.commands.set(command.data.name, command);
    }
  }
}

client.once(Events.ClientReady, (readyClient) => {
  console.log(`Ready! Logged in as ${readyClient.user.tag}`);
});

client.on(Events.InteractionCreate, async (interaction) => {
  if (!interaction.isChatInputCommand()) return;

  const command = interaction.client.commands.get(interaction.commandName);
  if (!command) {
    console.error(`Der Befehl ${interaction.commandName} existiert nicht.`);
    return;
  }

  try {
    await command.execute(interaction);
  } catch (error) {
    console.error(error);
    const odpoved = { content: 'Beim Ausführen dieses Befehls ist ein Fehler aufgetreten.', flags: MessageFlags.Ephemeral };
    if (interaction.replied || interaction.deferred) {
      await interaction.followUp(odpoved);
    } else {
      await interaction.reply(odpoved);
    }
  }
});

client.login(process.env.DISCORD_TOKEN);

Probieren Sie den Bot auf Ihrem Computer aus:

node index.js

Ready! Logged in as MujBot#1234

Tippen Sie auf Discord /ping und wählen Sie den Befehl Ihres Bots.

Antwort auf einen langsamen Befehl#

Wenn ein Befehl mehr als 3 Sekunden braucht (eine Datenbankabfrage, ein Aufruf einer anderen API), schieben Sie die Antwort zuerst auf und senden Sie das Ergebnis später:

async execute(interaction) {
  await interaction.deferReply();
  const vysledek = await nejakaDlouhaPrace();
  await interaction.editReply(`Fertig: ${vysledek}`);
}

• interaction.deferReply() – bestätigt die Interaktion sofort. Der Nutzer sieht, dass der Bot nachdenkt. Für eine Antwort, die nur er sieht, verwenden Sie deferReply({ flags: MessageFlags.Ephemeral }).
• interaction.editReply(…) – ersetzt „denkt nach“ durch die eigentliche Antwort. Eine aufgeschobene Antwort müssen Sie innerhalb von 15 Minuten senden.
• nejakaDlouhaPrace() – Ihre eigene Funktion; der Name ist nur ein Beispiel.

Antwort mit einem Embed#

Ein Embed ist eine Nachricht mit farbigem Streifen, Titel und Feldern. Er eignet sich, um Informationen übersichtlich darzustellen. Der Befehl /server zeigt Details zum Server:

const { SlashCommandBuilder, EmbedBuilder, InteractionContextType } = require('discord.js');

module.exports = {
  data: new SlashCommandBuilder()
    .setName('server')
    .setDescription('Informationen über diesen Discord-Server.')
    .setContexts(InteractionContextType.Guild),

  async execute(interaction) {
    const guild = interaction.guild;
    const embed = new EmbedBuilder()
      .setColor(0xe11d48)
      .setTitle(guild.name)
      .addFields(
        { name: 'Mitglieder', value: String(guild.memberCount), inline: true },
        { name: 'Erstellt', value: guild.createdAt.toLocaleDateString('de-DE'), inline: true },
      )
      .setTimestamp();
    await interaction.reply({ embeds: [embed] });
  },
};

Führen Sie nach dem Hinzufügen der Datei erneut node deploy-commands.js aus; der neue Befehl muss registriert werden.

Wer einen Befehl verwenden darf#

Die Standardberechtigungen legen Sie direkt in der Befehlsdefinition fest:

const { SlashCommandBuilder, PermissionFlagsBits, InteractionContextType, MessageFlags } = require('discord.js');

module.exports = {
  data: new SlashCommandBuilder()
    .setName('smazat')
    .setDescription('Löscht die neuesten Nachrichten im Kanal.')
    .addIntegerOption((o) =>
      o.setName('pocet').setDescription('Wie viele Nachrichten (1–100)').setMinValue(1).setMaxValue(100).setRequired(true),
    )
    .setDefaultMemberPermissions(PermissionFlagsBits.ManageMessages)
    .setContexts(InteractionContextType.Guild),

  async execute(interaction) {
    const pocet = interaction.options.getInteger('pocet');
    const smazane = await interaction.channel.bulkDelete(pocet, true);
    await interaction.reply({ content: `Gelöschte Nachrichten: ${smazane.size}`, flags: MessageFlags.Ephemeral });
  },
};

• .setDefaultMemberPermissions(PermissionFlagsBits.ManageMessages) – standardmäßig sehen nur Mitglieder mit der Berechtigung Nachrichten verwalten den Befehl. Ein Serveradministrator kann das in den Servereinstellungen ändern (Integrationen).
• .setMinValue(1) und .setMaxValue(100) – Discord akzeptiert keine Zahl außerhalb des Bereichs.
• interaction.channel.bulkDelete(pocet, true) – löscht Nachrichten massenhaft. true überspringt Nachrichten, die älter als 14 Tage sind und nicht massenhaft gelöscht werden können.
• Der Bot selbst braucht im Kanal die Berechtigung Nachrichten verwalten, sonst schlägt er mit DiscordAPIError[50013]: Missing Permissions fehl.

Keine Befehlseinstellung hält Mitglieder mit der Berechtigung Administrator auf. Registrieren Sie Befehle, die nur für Sie gedacht sind (zum Beispiel eval), deshalb nur auf einem privaten Testserver.

Ereignis: ein neues Mitglied begrüßen#

Neben Befehlen reagiert ein Bot auf Ereignisse. Das Begrüßen eines neuen Mitglieds braucht den privilegierten Server Members Intent: Schalten Sie ihn im Developer Portal auf der Seite Bot ein und fügen Sie ihn in Ihren Code ein.

const { Events } = require('discord.js');

module.exports = {
  name: Events.GuildMemberAdd,
  once: false,
  async execute(member) {
    const kanal = member.guild.systemChannel;
    if (!kanal) return;
    await kanal.send(`Willkommen auf dem Server, ${member}!`);
  },
};

Aktualisieren Sie in index.js die Intents und fügen Sie das Laden der Ereignisse hinzu (nach dem Laden der Befehle):

const client = new Client({
  intents: [GatewayIntentBits.Guilds, GatewayIntentBits.GuildMembers],
});

// … Laden der Befehle …

const eventsPath = path.join(__dirname, 'events');
for (const file of fs.readdirSync(eventsPath).filter((f) => f.endsWith('.js'))) {
  const event = require(path.join(eventsPath, file));
  if (event.once) {
    client.once(event.name, (...args) => event.execute(...args));
  } else {
    client.on(event.name, (...args) => event.execute(...args));
  }
}

• GatewayIntentBits.GuildMembers – Discord sendet dann Ereignisse, wenn Mitglieder beitreten und den Server verlassen. Wenn der Intent im Developer Portal nicht aktiviert ist, meldet der Bot Used disallowed intents.
• member.guild.systemChannel – der Systemkanal des Servers (in dem Discord Willkommensnachrichten postet). Wenn der Server keinen hat, sendet der Bot nichts.
• ${member} – fügt eine Erwähnung des neuen Mitglieds ein (@name).
• client.once / client.on – ein Ereignis mit once: true wird nur einmal verarbeitet (Start des Bots), die anderen jedes Mal.

Struktur eines größeren Bots#

• Befehle nach Kategorien in Ordnern wie commands/moderace, commands/zabava … Der Ladecode oben geht sie alle durch.
• Ereignisse im Ordner events, jedes in einer eigenen Datei mit name, once und execute (siehe oben). Auch die Handler ClientReady und InteractionCreate können Sie nach events verschieben.
• Konfiguration (Kanal- und Rollen-IDs) in config.json, Geheimnisse in .env.
• Daten (Punkte, Verwarnungen) in einer Datenbank, nicht in Variablen im Speicher, die bei einem Neustart verloren gehen.

Betrieb bei StormHost#

1. Führen Sie die Befehlsregistrierung (node deploy-commands.js) auf Ihrem Computer aus. Auf dem Server müssen Sie sie nicht ausführen.
2. Stoppen Sie den Bot auf Ihrem Computer (Strg+C). Zwei laufende Kopien mit demselben Token stehlen sich gegenseitig die Interaktionen.
3. Laden Sie index.js, package.json, package-lock.json und den Ordner commands mit allen Unterordnern in der Registerkarte Dateien hoch. Wenn Sie die Begrüßung neuer Mitglieder hinzugefügt haben, laden Sie auch den Ordner events hoch. Ohne ihn stürzt der Bot beim Start mit ENOENT: no such file or directory ab. Legen Sie .env direkt auf dem Server an. Schritte: Hochladen und Starten des Bots.
4. Prüfen Sie in der Registerkarte Einstellungen, dass die Hauptdatei index.js ist.
5. Klicken Sie in der Registerkarte Konsole auf Start.

Überprüfung#

• Die Konsole zeigt Ready! Logged in as …, und der Bot ist auf Discord online.
• Wenn Sie auf Ihrem Testserver / tippen, zeigt das Menü ping und pozdrav mit dem Symbol Ihres Bots.
• /ping antwortet mit einer Nachricht, die nur Sie sehen, /pozdrav jmeno:Jan mit einer öffentlichen Nachricht.

Fehlerbehebung#

Befehle erscheinen nicht im Menü#

• Die Registrierung ist nicht gelaufen: Führen Sie node deploy-commands.js aus und achten Sie auf die Ausgabe Fertig, registrierte Befehle: ….
• GUILD_ID ist die ID eines anderen Servers als dem, auf dem Sie testen.
• Der Bot wurde ohne den Scope applications.commands eingeladen. Laden Sie ihn erneut mit einem Link ein, der sowohl bot als auch applications.commands enthält.
• Discord cacht das Menü. Laden Sie die Discord-App neu (Strg+R).

Die Registrierung schlägt mit DiscordAPIError[50001]: Missing Access fehl#

Der Bot ist nicht auf dem Server GUILD_ID oder hat dort nicht den Scope applications.commands. Prüfen Sie die Server-ID und laden Sie den Bot erneut ein.

Discord meldet „Die Anwendung hat nicht reagiert“#

Der Bot hat nicht innerhalb von 3 Sekunden geantwortet. Entweder läuft er nicht (prüfen Sie die Konsole), der Befehl dauert lange und deferReply() fehlt, oder im Befehl ist vor der Antwort ein Fehler aufgetreten (Sie finden ihn in der Konsole).

DiscordAPIError[10062]: Unknown interaction#

Die Antwort kam zu spät (nach 3 Sekunden), oder zwei Kopien des Bots laufen mit demselben Token und die andere hat die Interaktion bereits verarbeitet. Verwenden Sie deferReply() und lassen Sie nur eine Kopie laufen.

DiscordAPIError[40060]: Interaction has already been acknowledged#

Sie haben reply() bei einer Interaktion zweimal aufgerufen. Senden Sie die zweite Nachricht mit followUp() oder verwenden Sie editReply() nach deferReply().

[WARNUNG] Der Datei … fehlt "data" oder "execute".#

Eine Datei im Ordner commands exportiert nicht beide Teile. Prüfen Sie module.exports = { data, execute } und suchen Sie nach Tippfehlern.

require is not defined in ES module scope oder Cannot use import statement outside a module#

Sie mischen CommonJS und ES-Module. Die Beispiele gelten für CommonJS: package.json muss "type": "commonjs" enthalten (oder gar kein Feld type). Details in der Anleitung Logs und Fehler.

Weiterführende Links#

• discord.js Guide: Creating Slash Commands (öffnet sich in einem neuen Fenster)
• discord.js Guide: Registering Commands (öffnet sich in einem neuen Fenster)
• discord.js Guide: Command Handling (öffnet sich in einem neuen Fenster)
• discord.js: API-Dokumentation (öffnet sich in einem neuen Fenster)