Portail développeurs
Expérimental La plateforme de bots et d'apps est en développement actif. La prise en charge des serveurs auto-hébergés est arrivée le 13/08/2026, avec moins de fonctionnalités que le 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 et les événements gateway 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. La plupart des endpoints sont transparents. Ceux qui ne sont pas pris en charge sont listés ci-dessous.

Fonctionnement

Quand votre bot appelle GET /guilds/{id} ou POST /channels/{id}/messages, l’API bots dans le 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 dans le WebSocket de canal de contrôle que l’instance du client maintient ouvert vers nous. Le processus auto-hébergé exécute le gestionnaire équivalent sur ses propres bases SQLite et renvoie une enveloppe de réponse, que nous transmettons mot pour mot à votre bot.

Le renvoi a lieu au niveau de l’API bots. Votre bibliothèque ne le voit jamais. Pas d’autre jeton, pas d’autre URL de gateway, pas d’autre SDK. Votre bot se connecte au même gateway.gamevox.com et appelle le même bot-api.gamevox.com, que la guild soit dans le cloud ou auto-hébergée.

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é. Si une instance auto-hébergée cesse de répondre (hors ligne, mise à jour, coupure réseau), votre bot reçoit 504 Gateway Timeout dans la seconde qui suit l’échéance.

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.
  • 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, réordonner.
  • 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, poser, retirer.
  • Rôles : lister, lire, créer, modifier, 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 pertinentes pour les bots uniquement.
  • URL personnalisée : GET (toujours la forme vide).
  • État vocal : GET (en direct depuis le SFU), PATCH (rendre muet, déplacer, déconnecter).
  • Webhooks : CRUD complet et exécution. Les enregistrements vivent dans le stockage cloud ; le message produit est écrit dans le salon auto-hébergé via le même chemin de renvoi que les envois du bot, de sorte que les messages du salon sont correctement signalés.

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

  • PATCH .../voice-states/* avec deaf. Rendre sourd côté serveur n’est pas une primitive du SFU auto-hébergé aujourd’hui. Rendre muet, déplacer (via channel_id) et déconnecter (via channel_id: null) fonctionnent.
  • PUT .../channels/{id}/permissions/{oid}. L’auto-hébergé utilise des permissions au niveau du groupe plutôt que des exceptions par salon, il n’y a donc rien à quoi appliquer une exception Discord. DELETE renvoie 204 (supprimer une exception inexistante ne fait rien).
  • PATCH .../guilds/{id}/vanity-url. Les serveurs auto-hébergés n’ont pas d’URL personnalisée.

Ce qui renvoie 404 (non routé vers l’auto-hébergé)

Ces endpoints touchent des ressources qui n’existent que dans l’infrastructure cloud. Réessayez sur une guild cloud si votre bot en a besoin.

  • Tous les endpoints /interactions/*, de suivi et de réponse d’origine.
  • Tout le CRUD des commandes d’application (/applications/{id}/commands et les variantes par guild).
  • La création de salons de MP (POST /users/@me/channels).
  • La recherche de personnes entre serveurs (GET /users/{id}, GET /users/by-name/{name}).
  • GET /users/@me/guilds.

Événements gateway

Les instances auto-hébergées publient un sous-ensemble des événements émis par le cloud. Votre bot les reçoit via la même session gateway. Pas d’autre modèle d’abonnement.

Émis aujourd’hui depuis l’auto-hébergé :

  • MESSAGE_CREATE, MESSAGE_UPDATE, MESSAGE_DELETE, MESSAGE_DELETE_BULK
  • MESSAGE_REACTION_ADD, MESSAGE_REACTION_REMOVE
  • CHANNEL_CREATE, CHANNEL_UPDATE, CHANNEL_DELETE
  • CHANNEL_PINS_UPDATE
  • GUILD_UPDATE (changements de nom / description)
  • GUILD_MEMBER_ADD, GUILD_MEMBER_REMOVE, GUILD_MEMBER_UPDATE (changement de pseudonyme ou de rôle)
  • GUILD_BAN_ADD, GUILD_BAN_REMOVE
  • GUILD_ROLE_CREATE, GUILD_ROLE_UPDATE, GUILD_ROLE_DELETE (émis lorsque le modèle de permissions de l’instance change)
  • TYPING_START
  • VOICE_STATE_UPDATE (arrivée, départ, sourdine perso/serveur, casque coupé)

Pas encore émis depuis l’auto-hébergé :

  • PRESENCE_UPDATE. Nécessite un nouveau diffuseur de présence côté auto-hébergé.
  • Les événements de messages en MP. L’auto-hébergé n’a pas de MP entre serveurs.
  • INTERACTION_CREATE. Les invocations de vos commandes sur les instances auto-hébergées ne sont pas encore relayées.

Écarts de fidélité connus

  • Sourdine personnelle vs sourdine serveur : le SFU auto-hébergé ne suit qu’un seul bit de sourdine par participant, au lieu de séparer self_mute de mute comme Discord. VOICE_STATE_UPDATE recopie la même valeur dans les deux champs ; lever une sourdine serveur peut donc donner l’impression que la personne a aussi levé sa sourdine personnelle. Les bots qui ne lisent qu’un seul des deux champs ne sont pas affectés ; ceux à machine à états qui les mélangent devraient privilégier mute pour les bascules de modération.
  • Le déplacement é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.

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 fiable est un 501 ou un 404 venant d’un des endpoints ci-dessus, avec un corps d’erreur JSON du type :

{ "code": 0, "message": "voice-state modify not supported on self-hosted yet" }

Si suffisamment de bots ont besoin d’une détection moins coûteuse, nous ajouterons une entrée features (par exemple "SELF_HOSTED") dans la charge 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