Slash-Befehle

Registriere Befehle, die Menschen als /name tippen, mit Optionen, Unterbefehlen und Namen in ihrer Sprache.

Das brauchst du

Dein Bot-Token (YOUR_BOT_TOKEN) und seine ID (YOUR_BOT_ID). Die ID steht im Entwicklerportal und in GET /users/@me als _id.

Global oder pro Server

Eine Änderung erreicht Menschen in beiden Bereichen sofort. Nutze beim Bauen einen Testserver, damit niemand sonst halbfertige Befehle sieht. Der Bot muss auf diesem Server installiert sein.

Gibt es denselben Namen in beiden Bereichen, sehen Menschen beide.

Registrieren

PUT ersetzt die ganze Liste. Das ist der einfachste Weg, Befehle mit deinem Code gleich zu halten: Sende deine Liste bei jedem Start. Unveränderte Befehle behalten ihre IDs. Befehle, die fehlen, werden gelöscht.

curl -X PUT "https://api.zrzur.com/applications/YOUR_BOT_ID/commands" \
  -H "x-bot-token: YOUR_BOT_TOKEN" \
  -H "content-type: application/json" \
  -d '[{ "name": "ping", "description": "Check that the bot is awake" }]'

POST /applications/{application_id}/commands fügt einen Befehl hinzu, PATCH /applications/{application_id}/commands/{command_id} ändert einen, DELETE entfernt einen. Ohne Code öffnest du deine Anwendung im Entwicklerportal, Tab Befehle: Ein Formular fügt Befehle hinzu, ändert und löscht sie, mit Optionen, Auswahlwerten, Namen in anderen Sprachen und wer sie nutzen darf, und zeigt eine Vorschau. JSON importieren und JSON exportieren dort nehmen und liefern dieselbe Liste wie PUT. Speichern im Portal ersetzt die globale Liste wie PUT; ein Bot, der seine Liste beim Start sendet, überschreibt also, was du gespeichert hast.

Ein Befehl

Der Server füllt _id, application_id und version. version ändert sich mit jeder Änderung. Wer noch eine ältere Version offen hat, wird gebeten, neu zu laden.

Limits

Optionen

{
  "name": "roll",
  "description": "Roll a die",
  "options": [
    {
      "type": "Integer",
      "name": "sides",
      "description": "How many sides",
      "required": true,
      "min_value": 2,
      "max_value": 100
    }
  ]
}

Regeln, die der Server beim Registrieren prüft:

• required-Optionen stehen vor optionalen.
• choices und autocomplete schließen sich aus.
• Zahlen bleiben innerhalb von 9007199254740991, damit JavaScript sie halten kann.

Der Server prüft Pflichtoptionen, Limits und Auswahlwerte, bevor dein Bot die Interaktion sieht. Für User, Role, Channel, Mentionable und Attachment ist der Wert eine ID, und das ganze Objekt kommt in command.resolved, unter users (auf einem Server mit members), roles, channels oder attachments, mit dieser ID als Schlüssel.

Dateien aus einer Option

Der Wert einer Attachment-Option ist eine Datei-ID. Die Datei kommt in command.resolved.attachments:

{
  "type": "Command",
  "command": {
    "name": "report",
    "options": [{ "name": "file", "type": "Attachment", "value": "FILE_ID" }],
    "resolved": {
      "attachments": {
        "FILE_ID": {
          "_id": "FILE_ID",
          "tag": "attachments",
          "filename": "screenshot.png",
          "content_type": "image/png",
          "size": 48213,
          "metadata": { "type": "Image", "width": 1280, "height": 720 }
        }
      }
    }
  }
}

Lade sie von https://cdn.zrzur.com/attachments/FILE_ID/screenshot.png (der tag, die ID und der filename). Der Befehl hat die ID verwendet, sie geht also nicht in eine eigene Nachricht deines Bots: Das antwortet 404 NotFound. Um die Datei zu posten, sende ihre Adresse, oder lade sie herunter und lade eine Kopie hoch.

Unterbefehle

Fasse Aktionen unter einem Namen zusammen: /note add, /note list.

{
  "name": "note",
  "description": "Notes for this server",
  "options": [
    { "type": "SubCommand", "name": "add", "description": "Write a new note" },
    {
      "type": "SubCommandGroup",
      "name": "admin",
      "description": "For moderators",
      "options": [
        { "type": "SubCommand", "name": "clear", "description": "Delete all notes" }
      ]
    }
  ]
}

Regeln:

• SubCommand kann normale Optionen halten. Eine SubCommandGroup hält nur Unterbefehle.
• Eine Gruppe steht auf der obersten Ebene. Nichts verschachtelt tiefer als eine Gruppe.
• Unterbefehle und einfache Optionen mischen sich nicht auf einer Ebene.
• Ein Unterbefehl nimmt name, description und options, sonst nichts.

Der gewählte Pfad kommt in den Optionen an, die Werte darin:

{
  "name": "note",
  "options": [
    {
      "name": "add",
      "type": "SubCommand",
      "options": [{ "name": "title", "type": "String", "value": "Hello" }]
    }
  ]
}

Namen in anderen Sprachen

Gib jeden Text pro Sprache an. Die Schlüssel sind Sprachtags: ar, de, pt-BR.

{
  "name": "ping",
  "name_localizations": { "ar": "فحص", "de": "pruefen" },
  "description": "Check that the bot is awake",
  "description_localizations": {
    "ar": "تحقق من أن البوت يعمل",
    "de": "Prüfen, ob der Bot läuft"
  }
}

Optionen und Auswahlwerte nehmen dieselben Felder. Übersetzte Namen folgen denselben Regeln wie name, arabische Buchstaben sind also erlaubt. Die Interaktion trägt immer den Basisnamen name, dein Code hat also einen Fall pro Befehl. Sie trägt auch die Sprache der Person in locale, damit du darin antworten kannst.

Wer einen Befehl nutzen kann

default_member_permissions ist eine Zahl: Addiere die Werte der Berechtigungen, die ein Mitglied braucht, aus der Berechtigungstabelle. Ein Mitglied, dem eine davon fehlt, sieht den Befehl nicht, und eine Anfrage bekommt MissingPermission. 256 ist „Mitglieder in Timeout versetzen“; Nachrichten verwalten (8388608) plus Mitglieder kicken (64) ist 8388672. Im Entwicklerportal wählst du die Berechtigungen stattdessen aus einer Liste. Dein Bot sollte trotzdem user_permissions prüfen: Admins können Rollen ändern, und ein Befehl ist keine Sicherheitsmauer für das, was dein Bot selbst tut.

Menübefehle

"type": "User" und "type": "Message" zeigen einen Befehl im Menü eines Benutzers oder einer Nachricht. Sie haben weder Beschreibung noch Optionen, und ihr Name darf Großbuchstaben und Leerzeichen enthalten. Das Ziel kommt in command.target_id.

Häufige Fehler

Referenz

Die Routen stehen unter Auf Interaktionen antworten.

Weiter

• Auf Interaktionen antworten
• Befehle mit Optionen