Schaltflächen, Menüs und Formulare

Setze Schaltflächen und Auswahlmenüs auf eine Nachricht, ordne Inhalte in Blöcken und frage mit einem Formular nach Eingaben. Nur Bots können Komponenten senden.

Das brauchst du

Den Intent INTERACTIONS. Jeder Klick kommt als InteractionCreate vom Typ Component, jedes Formular als ModalSubmit. Beide haben dieselben 3 Sekunden wie ein Befehl: siehe die Zeitlimits.

Schaltflächen

Eine Nachricht hat components, eine Liste von Blöcken. Eine ActionRow hält bis zu fünf Schaltflächen oder ein Auswahlmenü.

{
  "content": "Heads or tails?",
  "components": [
    {
      "type": "ActionRow",
      "components": [
        { "type": "Button", "style": "Primary", "label": "Heads", "custom_id": "flip:heads" },
        { "type": "Button", "style": "Secondary", "label": "Tails", "custom_id": "flip:tails" },
        { "type": "Button", "style": "Link", "label": "Rules", "url": "https://example.com/rules" }
      ]
    }
  ]
}

Lege in custom_id, was du brauchst, etwa flip:heads oder note:3, und es kommt in interaction.component.custom_id zurück. Antworte mit UpdateMessage, um die Nachricht zu ändern, oder Message für eine neue.

Die erste Nachricht eines Threads kann noch keine Komponenten tragen. Starte den Thread und sende die Nachricht mit Schaltflächen dann hinein; siehe Kanäle und Webhooks.

Wer klicken darf

{ "restrict": { "users": ["USER_ID"], "roles": ["ROLE_ID"] } }

Bis zu 25 IDs je Liste. Der Server lehnt Klicks anderer ab, dein Bot sieht sie nie. Nicht für Link-Schaltflächen oder Formularfelder.

Auswahlmenüs

Alle nehmen custom_id, placeholder (bis 150), min_values und max_values (0 bis 25, Standard 1), disabled und restrict.

Ein Eintrag von options hat label und value (je bis 100, eine Zeile) und kann description, emoji und default haben. Werte sind eindeutig.

{
  "type": "ActionRow",
  "components": [
    {
      "type": "StringSelect",
      "custom_id": "colour",
      "placeholder": "Pick a colour",
      "options": [
        { "label": "Red", "value": "red" },
        { "label": "Blue", "value": "blue" }
      ]
    }
  ]
}

Die Wahl kommt in interaction.component.values. Benutzer, Rollen und Kanäle kommen auch als Objekte in interaction.component.resolved.

Layoutblöcke

Ein Bild hat entweder url oder attachment (die ID einer Datei derselben Nachricht) und kann description und spoiler haben. Container verschachteln sich nicht.

Limits einer Nachricht

Apps überspringen Blöcke, die sie nicht kennen. Webhooks ohne Bot können nur Blöcke posten, die niemand benutzen kann: Text, Bilder, Link-Schaltflächen.

Formulare

Ein Formular (Modal) öffnet sich als Antwort auf einen Befehl oder Klick auf dem Bildschirm der Person. Es kann keine Antwort auf ein anderes Formular oder eine Autovervollständigung sein.

{
  "type": "Modal",
  "modal": {
    "custom_id": "note-form",
    "title": "New note",
    "components": [
      {
        "type": "Field",
        "label": "Title",
        "description": "Short and clear.",
        "component": {
          "type": "TextInput",
          "custom_id": "title",
          "style": "Short",
          "max_length": 80
        }
      }
    ]
  }
}

title hat bis zu 45 Zeichen. Ein Formular hat bis zu 5 Felder und bis zu 10 Blöcke mit Text. Ein Field hat label, description (bis 100) und eine component:

required ist true, außer du sagst etwas anderes. file_types listet image, video, audio oder eine Endung wie .pdf.

Sendet die Person das Formular, bekommst du eine Interaktion vom Typ ModalSubmit:

{
  "custom_id": "note-form",
  "fields": [{ "custom_id": "title", "value": "Hello" }]
}

Antworte innerhalb von 3 Sekunden. UpdateMessage geht nur, wenn das Formular von einer Schaltfläche geöffnet wurde.

Eine Person kann ein Formular schließen, ohne dass dein Bot davon erfährt, warte also nicht darauf.

Häufige Fehler

Weiter

• Baue einen vollständigen Bot
• Spiele mit Schaltflächen