Nachrichtenkomponenten

Bots hängen Discord-förmige components genau wie bei Discord an ihre Nachrichten, und ein Klick kommt als INTERACTION_CREATE mit dem üblichen Token- und Callback-Ablauf an, Bibliotheken brauchen also keine Änderungen. Diese Seite beschreibt, was GameVox darstellt, wie Interaktionen deine App erreichen und wo die Grenzen von Discord abweichen.

Was funktioniert

Action Rows (Typ 1) mit Buttons (Typ 2, Stile 1 bis 5) und String-Auswahlmenüs (Typ 3). Ein Link-Button (Stil 5) öffnet seine url und sendet nie eine Interaktion.
Cloud und selbst gehostete Server. Komponenten werden mit der Nachricht gespeichert und bei REST-Abfragen sowie in MESSAGE_CREATE / MESSAGE_UPDATE zurückgegeben. Eine Bearbeitung mit components: [] entfernt sie.
Alle Clients. Der Desktop- und Web-Client, iOS und Android stellen Buttons und String-Auswahlmenüs dar (höchstens 5 Zeilen mit je 5 Elementen pro Nachricht) und zeigen Dialoge und ephemere Antworten an.
Dialoge (Callback-Typ 9) und ephemere Antworten (flags: 64), siehe unten.

Eine Nachricht mit einer Button-Zeile und einem Auswahlmenü:

POST /api/v10/channels/{channel_id}/messages

{
  "content": "Next map?",
  "components": [
    {
      "type": 1,
      "components": [
        { "type": 2, "style": 1, "label": "Vote", "custom_id": "vote" },
        { "type": 2, "style": 5, "label": "Rules", "url": "https://example.com/rules" }
      ]
    },
    {
      "type": 1,
      "components": [
        {
          "type": 3,
          "custom_id": "map",
          "placeholder": "Pick a map",
          "options": [
            { "label": "Dust", "value": "dust" },
            { "label": "Nuke", "value": "nuke" }
          ]
        }
      ]
    }
  ]
}

Nicht unterstützt

Auswahlmenüs für Nutzer, Rollen, Erwähnbare und Kanäle (Typen 5 bis 8). Sie werden angenommen und gespeichert, aber Clients zeigen sie deaktiviert an, daher lösen sie nie eine Interaktion aus.
Komponenten v2 (Layout-Komponenten). Sie werden nicht angezeigt.
Premium-Buttons (Stil 6). Sie werden deaktiviert angezeigt.
DMs. Interaktionen mit Komponenten, Dialoge und ephemere Antworten funktionieren nur in Serverkanälen.

Einen Klick empfangen

Ein Klick kommt als INTERACTION_CREATE mit type: 3 (MESSAGE_COMPONENT) an, mit data.custom_id, data.component_type und bei einem Auswahlmenü data.values. message ist die vollständige angeklickte Nachricht einschließlich Komponenten, unabhängig von den Intents deines Bots. Ein abgeschickter Dialog kommt als type: 5 (MODAL_SUBMIT) an, mit den eingegebenen Werten in data.components.

GameVox prüft jeden Klick gegen die gespeicherte Nachricht, bevor deine App ihn sieht: Das Element muss noch auf der Nachricht stehen und aktiviert sein, Auswahlwerte müssen zu den Optionen gehören und innerhalb von min_values / max_values liegen, und das Mitglied muss den Kanal sehen können. Ein Klick wird nur an die App zugestellt, deren Bot die Nachricht gepostet hat.

Interaktionen werden über die Gateway-Verbindung deines Bots zugestellt oder per POST an deine Endpunkt-URL für Interaktionen gesendet, falls du eine gesetzt hast (siehe OAuth2). Im HTTP-Modus weichen zwei Dinge von Discord ab:

Halte trotzdem eine Gateway-Sitzung verbunden. GameVox reicht jede Interaktion über sie an deine App weiter, bevor es sie per POST an deinen Endpunkt sendet. Ohne verbundene Sitzung wird nichts zugestellt, und ein Mitglied, das klickt, erfährt, dass die App nicht online ist.
Der Antwort-Body wird ignoriert. Antworte mit einem Aufruf von POST /interactions/{id}/{token}/callback; ein Callback im Body der POST-Antwort erreicht niemanden.

Antworten

Über den üblichen Callback-Endpunkt. Das Interaktions-Token ist 15 Minuten gültig.

Typ	Wirkung
`4` `CHANNEL_MESSAGE_WITH_SOURCE`	Postet eine Antwort im Kanal. Mit `flags: 64` ist die Antwort ephemer.
`5` `DEFERRED_CHANNEL_MESSAGE_WITH_SOURCE`	Bestätigt sofort; das erste `PATCH .../messages/@original` postet die Antwort. Mit `flags: 64` ist diese Antwort ephemer.
`6` `DEFERRED_UPDATE_MESSAGE`	Bestätigt ohne sichtbare Änderung. `@original` verweist danach auf die angeklickte Nachricht, ein späteres `PATCH .../messages/@original` bearbeitet sie also.
`7` `UPDATE_MESSAGE`	Bearbeitet die angeklickte Nachricht direkt, einschließlich Komponenten.
`9` `MODAL`	Öffnet einen Dialog für das Mitglied, das geklickt hat.

Follow-ups (bis zu 5 pro Interaktion, flags: 64 für ephemer) sowie GET / PATCH / DELETE auf @original und auf Follow-up-Nachrichten funktionieren wie bei Discord. Die Typen 4, 5 und 9 und ephemere Antworten funktionieren auch bei Slash-Befehlen; die Typen 6 und 7 brauchen eine angeklickte Nachricht.

Ephemere Antworten

Eine ephemere Antwort geht nur an das Mitglied, das die Interaktion ausgelöst hat, an dessen offene Sitzungen, und ist als nur für diese Person sichtbar gekennzeichnet. Sie wird nie in den Kanal geschrieben: Sie steht weder im Nachrichtenverlauf noch in MESSAGE_CREATE, sie verschwindet, wenn das Mitglied neu lädt, und deine App kann sie 15 Minuten lang bearbeiten oder löschen. Komponenten auf einer ephemeren Antwort funktionieren wie alle anderen. Das gilt gleichermaßen für Cloud- und selbst gehostete Server.

Dialoge

Bis zu 5 Action Rows mit Texteingaben (Typ 4). Alles andere in einem Dialog wird verworfen. Stil 1 ist eine einzelne Zeile, Stil 2 ein Absatz.
Titel und Beschriftungen werden auf 45 Zeichen gekürzt, Platzhalter auf 100. Eine Eingabe fasst bis zu 4000 Zeichen. required ist standardmäßig true.
GameVox prüft die Eingaben gegen den geöffneten Dialog (Pflichtfelder, min_length, max_length), bevor deine App sie sieht.
Ein Dialog läuft nach 15 Minuten ab und kann einmal abgeschickt werden.

Grenzen

components einer Nachricht: 64 KiB JSON auf Cloud-Servern; 128 KiB und 40 Komponenten auf oberster Ebene auf selbst gehosteten Servern. Eine größere Anfrage schlägt mit 400 fehl.
custom_id: bis zu 100 Zeichen; ein Element mit einer längeren ist nicht benutzbar. Auswahlmenüs: bis zu 25 Werte mit je bis zu 100 Zeichen.
Klicks: eine Interaktion mit Komponenten pro Mitglied und Server alle 0,7 Sekunden. Ein selbst gehosteter Server erlaubt zusätzlich höchstens 5 Klicks pro Mitglied in 5 Sekunden. Schnellere Klicks werden abgewiesen und erreichen deine App nie.
Ephemere Antworten und Dialoge: 120 pro App und Mitglied in einem 15-Minuten-Fenster, zusammen gezählt. Das Bearbeiten einer bestehenden zählt nicht. Über der Grenze schlägt die Anfrage mit 429 fehl.
Inhalt einer ephemeren Antwort: bis zu 4000 Zeichen.

← Zurück zur Doku