Composants de message

Les bots attachent des components au format Discord à leurs messages exactement comme sur Discord, et un clic arrive sous forme d’INTERACTION_CREATE avec le flux habituel de token et de callback ; les bibliothèques n’ont besoin d’aucune modification. Cette page décrit ce que GameVox affiche, comment les interactions atteignent votre app et où les limites diffèrent de Discord.

Ce qui fonctionne

Rangées d’action (type 1) contenant des boutons (type 2, styles 1 à 5) et des sélecteurs de texte (type 3). Un bouton lien (style 5) ouvre son url et n’envoie jamais d’interaction.
Serveurs cloud et auto-hébergés. Les composants sont enregistrés avec le message et renvoyés par les lectures REST et dans MESSAGE_CREATE / MESSAGE_UPDATE. Modifier un message avec components: [] les supprime.
Tous les clients. Le client desktop et web, iOS et Android affichent les boutons et les sélecteurs de texte (au plus 5 rangées de 5 contrôles par message), ainsi que les modales et les réponses éphémères.
Modales (callback de type 9) et réponses éphémères (flags: 64), décrites plus bas.

Un message avec une rangée de boutons et un sélecteur :

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" }
          ]
        }
      ]
    }
  ]
}

Non pris en charge

Sélecteurs d’utilisateur, de rôle, de mentionnable et de salon (types 5 à 8). Ils sont acceptés et enregistrés, mais les clients les affichent désactivés, ils ne produisent donc jamais d’interaction.
Composants v2 (composants de mise en page). Ils ne sont pas affichés.
Boutons premium (style 6). Ils sont affichés désactivés.
MP. Les interactions de composants, les modales et les réponses éphémères ne fonctionnent que dans les salons de serveur.

Recevoir un clic

Un clic arrive sous forme d’INTERACTION_CREATE avec type: 3 (MESSAGE_COMPONENT), avec data.custom_id, data.component_type et, pour un sélecteur, data.values. message est le message complet sur lequel on a cliqué, composants compris, quels que soient les intents de votre bot. Une modale soumise arrive sous forme de type: 5 (MODAL_SUBMIT) avec les valeurs saisies dans data.components.

GameVox vérifie chaque clic par rapport au message enregistré avant que votre app ne le voie : le contrôle doit toujours figurer sur le message et être activé, les valeurs d’un sélecteur doivent faire partie de ses options et respecter min_values / max_values, et le membre doit pouvoir voir le salon. Un clic n’est délivré qu’à l’app dont le bot a publié le message.

Les interactions sont délivrées par la connexion gateway de votre bot, ou envoyées en POST à votre URL d’endpoint d’interactions si vous en avez défini une (voir OAuth2). En mode HTTP, deux choses diffèrent de Discord :

Gardez quand même une session gateway connectée. GameVox transmet chaque interaction à votre app par cette session avant de l’envoyer en POST à votre endpoint. Sans session connectée, rien n’est délivré, et un membre qui clique est informé que l’app n’est pas en ligne.
Le corps de la réponse est ignoré. Répondez en appelant POST /interactions/{id}/{token}/callback ; un callback renvoyé dans le corps de la réponse au POST n’atteint personne.

Répondre

Via l’endpoint de callback habituel. Le token d’interaction est valable 15 minutes.

Type	Effet
`4` `CHANNEL_MESSAGE_WITH_SOURCE`	Publie une réponse dans le salon. Avec `flags: 64`, la réponse est éphémère.
`5` `DEFERRED_CHANNEL_MESSAGE_WITH_SOURCE`	Accuse réception tout de suite ; le premier `PATCH .../messages/@original` publie la réponse. Avec `flags: 64`, cette réponse est éphémère.
`6` `DEFERRED_UPDATE_MESSAGE`	Accuse réception sans changement visible. `@original` désigne ensuite le message cliqué, donc un `PATCH .../messages/@original` ultérieur le modifie.
`7` `UPDATE_MESSAGE`	Modifie sur place le message cliqué, composants compris.
`9` `MODAL`	Ouvre une modale pour le membre qui a cliqué.

Les messages de suivi (jusqu’à 5 par interaction, flags: 64 pour l’éphémère) et GET / PATCH / DELETE sur @original et sur les messages de suivi fonctionnent comme sur Discord. Les types 4, 5 et 9 et les réponses éphémères fonctionnent aussi pour les commandes slash ; les types 6 et 7 nécessitent un message cliqué.

Réponses éphémères

Une réponse éphémère ne parvient qu’au membre qui a déclenché l’interaction, sur les sessions qu’il a ouvertes, et elle est marquée comme visible par lui seul. Elle n’est jamais écrite dans le salon : elle n’apparaît ni dans l’historique des messages ni dans MESSAGE_CREATE, elle disparaît quand le membre recharge, et votre app peut la modifier ou la supprimer pendant 15 minutes. Les composants d’une réponse éphémère fonctionnent comme les autres. C’est identique sur les serveurs cloud et auto-hébergés.

Modales

Jusqu’à 5 rangées d’action de champs de texte (type 4). Tout le reste dans une modale est ignoré. Le style 1 est une seule ligne, le style 2 un paragraphe.
Le titre et les libellés sont tronqués à 45 caractères et les textes indicatifs à 100. Un champ contient jusqu’à 4000 caractères. required vaut true par défaut.
GameVox vérifie la soumission par rapport à la modale ouverte (champs obligatoires, min_length, max_length) avant que votre app ne la voie.
Une modale expire au bout de 15 minutes et ne peut être soumise qu’une fois.

Limites

components d’un message : 64 Kio de JSON sur les serveurs cloud ; 128 Kio et 40 composants de premier niveau sur les serveurs auto-hébergés. Une requête plus grande échoue avec 400.
custom_id : jusqu’à 100 caractères ; un contrôle dont l’identifiant est plus long est inutilisable. Sélecteurs : jusqu’à 25 valeurs de 100 caractères au plus chacune.
Clics : une interaction de composant par membre et par serveur toutes les 0,7 seconde. Un serveur auto-hébergé autorise en plus au plus 5 clics par membre en 5 secondes. Les clics plus rapides sont refusés et n’atteignent jamais votre app.
Réponses éphémères et modales : 120 par app pour chaque membre sur une fenêtre de 15 minutes, comptées ensemble. Modifier une réponse existante ne compte pas. Au-delà, la requête échoue avec 429.
Contenu d’une réponse éphémère : jusqu’à 4000 caractères.

← Retour à la documentation