Portail développeurs
Expérimental La plateforme de bots & d’apps est en développement actif. Les serveurs auto-hébergés font tourner les bots, les commandes slash et les composants de message, avec quelques différences par rapport au cloud. Voir ce qui est pris en charge.
← Docs

Serveurs auto-hébergés

Vos clients peuvent faire tourner GameVox sur leur propre matériel, et votre bot y fonctionne. L’API cloud relaie les appels REST au format Discord par le canal de contrôle du client, l’instance auto-hébergée les exécute sur sa base locale, et la réponse remonte par le même tuyau. Les événements gateway font le chemin inverse. La plupart des endpoints sont transparents. Les différences sont listées ci-dessous.

Fonctionnement

Quand votre bot appelle GET /guilds/{id} ou POST /channels/{id}/messages, l’API cloud vérifie le palier du serveur cible. S’il est auto-hébergé, nous sérialisons la requête (méthode, chemin, query, corps, bot_user_id) et l’envoyons via le WebSocket persistant du canal de contrôle que l’instance du client maintient ouvert vers nous. Le processus auto-hébergé vérifie les permissions de votre bot par rapport à ses propres rôles, exécute le gestionnaire équivalent sur ses propres bases SQLite et renvoie une enveloppe de réponse, que nous retransmettons à votre bot.

Le transfert a lieu dans le cloud. Votre bibliothèque ne le voit jamais. Pas de token différent, pas d’URL de gateway différente, pas de SDK différent. Votre bot se connecte au même gateway.gamevox.com et appelle le même app-api.gamevox.com, que le serveur soit hébergé dans le cloud ou auto-hébergé. Votre bot doit être membre du serveur auto-hébergé ; sinon, les appels renvoient 403.

Latence

L’aller-retour est limité par la liaison WAN du client plus le temps de requête SQLite, en général 30–300 ms en plus d’un appel cloud. Un délai de bout en bout de 12 s est appliqué (90 s pour un message qui contient des fichiers, car l’instance les télécharge). Si l’instance n’est pas connectée, votre bot reçoit 503 immédiatement. Si elle est connectée mais ne répond pas à temps, votre bot reçoit 504.

Ce qui fonctionne

Tout ce qui suit s’exécute sur les données locales de l’instance auto-hébergée, avec la même forme de réponse que dans le cloud.

  • Messages : lister, lire, envoyer, modifier, supprimer, supprimer en masse. Embeds, composants, réponses (message_reference), pièces jointes (multipart files[n] plus payload_json) et sondages. tts est accepté et ignoré.
  • Réactions : ajouter, retirer la sienne, retirer celle d’une autre personne, tout retirer, tout retirer pour un emoji, lister les personnes.
  • Épinglés : épingler, désépingler, lister.
  • Indicateur de saisie : POST /channels/{id}/typing.
  • Salons : lire, modifier, supprimer, lister, créer (y compris les salons d’app), réordonner.
  • Exceptions de permissions par salon : PUT et DELETE .../channels/{id}/permissions/{oid}, et permission_overwrites sur chaque objet salon (et CHANNEL_UPDATE). La lecture de permission_overwrites est pour l’instant réservée à l’auto-hébergé : les objets salon du cloud n’incluent pas ce champ, et l’API cloud ne prend en charge que les écritures PUT et DELETE. Seules les exceptions de rôle existent sur un serveur auto-hébergé : oid est un identifiant de rôle et type doit valoir 0 ; une exception de membre (type: 1) est refusée. L’exception couvre voir le salon, envoyer des messages, joindre des fichiers, ajouter des réactions, se connecter, parler, utiliser la détection de la voix et diffuser. Une autorisation n’accorde jamais plus que ce que le rôle lui-même a le droit de faire, donc une autorisation sur une permission que le rôle n’a pas n’est pas renvoyée. Un salon sans exception renvoie une liste vide.
  • Serveur (guild) : lire, modifier (nom et description).
  • Membres : lister, rechercher, @me, lire, modifier, changer le pseudonyme, expulser, ajouter ou retirer un rôle.
  • Bannissements : lister, lire, créer, retirer.
  • Rôles : lister, lire, créer, modifier (y compris color), réordonner, supprimer, ainsi que les permissions de rôle.
  • Emojis : lister, lire (ceux du serveur).
  • Soundboard : lister, lire (ceux du serveur).
  • Journal d’audit : GET /guilds/{id}/audit-logs, entrées correspondant aux actions effectuées via l’API de bot.
  • URL personnalisée : GET (toujours la forme vide).
  • État vocal : GET (en direct depuis le SFU), PATCH avec mute, deaf et channel_id (déplacement, ou null pour déconnecter), dans n’importe quelle combinaison. mute et deaf sont les indicateurs côté serveur ; self_mute et self_deaf sont ceux du membre lui-même.
  • Webhooks : CRUD complet et exécution. Les enregistrements des webhooks vivent dans le cloud ; les messages produits par l’exécution sont écrits dans le salon auto-hébergé et apparaissent sous le nom du webhook.
  • Événements programmés : lister, créer, lire, modifier, supprimer, lister les personnes intéressées, et définir ou effacer la réponse (RSVP) d’un membre, avec les mêmes formes que dans le cloud. Les paramètres de répétition sont enregistrés, mais les occurrences suivantes d’un événement récurrent ne sont pas générées.
  • Publications de forum : créer une publication (POST /channels/{forum}/threads), la lire et y répondre. Le message d’ouverture d’une publication est limité à 10 000 caractères (20 000 dans le cloud).
  • Commandes slash : invocation, avec des permissions vérifiées par rapport aux rôles de l’instance elle-même. L’enregistrement est le même que dans le cloud.
  • Composants de message : boutons, sélecteurs de texte, modales et réponses éphémères, y compris les endpoints de callback d’interaction, de suivi et de réponse d’origine. Voir Composants de message.

Ce qui renvoie 501 (accepté, non implémenté)

  • PATCH .../guilds/{id}/vanity-url. Les serveurs auto-hébergés n’ont pas d’URL personnalisée.

Traité par le cloud, pas par l’instance

Ces endpoints concernent les comptes GameVox plutôt qu’un serveur en particulier, le cloud y répond donc pour tous les bots. Les membres des serveurs auto-hébergés sont des comptes GameVox ordinaires.

  • GET /users/{id} et GET /users/by-name/{name}.
  • GET /users/@me/guilds, qui inclut les serveurs auto-hébergés sur lesquels votre app est installée.
  • POST /users/@me/channels renvoie un salon de MP, mais l’envoi de messages dans ce salon n’est pas encore pris en charge, ni dans le cloud ni en auto-hébergé.

Événements gateway

Les instances auto-hébergées publient leurs événements via la même session gateway que le cloud. Pas d’autre modèle d’abonnement. Les événements de salon ne sont envoyés qu’aux bots qui peuvent voir le salon, et les intents s’appliquent comme dans le cloud.

Émis pour les actions des personnes sur l’instance et pour les appels REST de votre bot :

  • MESSAGE_CREATE, MESSAGE_UPDATE, MESSAGE_DELETE
  • MESSAGE_DELETE_BULK (aussi lorsqu’une expulsion ou un bannissement supprime les messages du membre)
  • MESSAGE_REACTION_ADD, MESSAGE_REACTION_REMOVE
  • MESSAGE_POLL_VOTE_ADD, MESSAGE_POLL_VOTE_REMOVE
  • CHANNEL_CREATE, CHANNEL_UPDATE, CHANNEL_DELETE
  • CHANNEL_PINS_UPDATE
  • GUILD_UPDATE (changements de nom / description)
  • GUILD_MEMBER_ADD
  • GUILD_MEMBER_REMOVE (départ, expulsion, bannissement, purge des invités inactifs)
  • GUILD_MEMBER_UPDATE (changement de rôle, de nom d’utilisateur ou d’avatar)
  • GUILD_BAN_ADD
  • GUILD_ROLE_CREATE, GUILD_ROLE_UPDATE, GUILD_ROLE_DELETE (création, renommage, réordonnancement, changements de couleur et de permissions)
  • GUILD_EMOJIS_UPDATE
  • TYPING_START
  • PRESENCE_UPDATE (nécessite l’intent GUILD_PRESENCES ; changements uniquement, pas d’instantané des membres déjà en ligne au moment où vous vous connectez)
  • VOICE_STATE_UPDATE (arrivée, départ, déplacement, micro et son coupés par le membre ou par le serveur)
  • INTERACTION_CREATE (commandes slash, clics sur des composants et soumissions de modales ; relayés par le cloud)

Émis uniquement pour les changements que votre bot fait via REST :

  • GUILD_BAN_REMOVE (l’instance ne propose pas d’action de débannissement aux personnes)
  • MESSAGE_REACTION_REMOVE_ALL, MESSAGE_REACTION_REMOVE_EMOJI (l’instance ne propose pas cette action aux personnes)

Non émis (dans le cloud non plus) :

  • THREAD_*, INVITE_*, GUILD_SCHEDULED_EVENT_*.

Écarts de fidélité connus

  • Le déplacement vocal émet deux événements : le PATCH Discord sur voice-states/{uid} avec un nouveau channel_id émet un seul VOICE_STATE_UPDATE ; en auto-hébergé, le déplacement est implémenté comme un départ suivi d’une arrivée, vous verrez donc le channel_id de la personne passer à null puis au nouveau salon. Traitez des mises à jour consécutives de la même personne à quelques centaines de millisecondes d’intervalle comme un seul déplacement. Un mute ou un deaf envoyé avec un déplacement est appliqué lorsque le membre revient dans le salon.
  • URL des pièces jointes : sur un serveur auto-hébergé, l’url d’une pièce jointe pointe vers l’instance du client et nécessite une session de membre pour être téléchargée. Votre bot voit le nom, la taille et le type du fichier, mais ne peut pas encore récupérer le fichier. width, height et description ne sont pas conservés en auto-hébergé.

Détecter l’auto-hébergement

L’objet guild ne porte pas aujourd’hui d’indicateur “auto-hébergé” (nous restons identiques octet pour octet à Discord). Si votre bot doit se comporter différemment, le signal est un 501 venant d’un endpoint listé ci-dessus, avec la raison donnée par l’instance dans le corps d’erreur JSON, par exemple :

{ "code": 0, "message": "vanity URL not supported on self-hosted" }

Un 404 ("Unknown resource") signifie que la ressource n’existe pas, pas que le serveur est auto-hébergé. Si suffisamment de bots ont besoin d’une détection moins coûteuse, nous ajouterons une entrée features (par exemple "SELF_HOSTED") dans le payload de la guild. Faites-le savoir depuis l’onglet Support de votre application si cela vous serait utile.

Erreurs

  • 502 Bad Gateway. L’instance auto-hébergée a renvoyé une réponse mal formée. Rare ; généralement un décalage de version pendant une mise à jour.
  • 503 Service Unavailable. Le canal de contrôle n’est pas connecté pour l’instant. Réessayez avec un backoff.
  • 504 Gateway Timeout. L’instance n’a pas répondu en 12 s.

← Retour à la documentation