Entwicklerportal
Experimentell Die Bot- & App-Plattform wird aktiv weiterentwickelt. Die Unterstützung für selbst gehostete Server ist am 13.08.2026 erschienen und bietet weniger Funktionen als die Cloud. Sieh dir an, was unterstützt wird.
← Doku

Selbst gehostete Server

Kundinnen und Kunden können GameVox auf eigener Hardware betreiben, und dein Bot funktioniert dort. Die Cloud-API leitet REST-Aufrufe und Gateway-Ereignisse in Discord-Form über den Steuerkanal der Kundschaft weiter, die selbst gehostete Instanz führt sie gegen ihre lokale Datenbank aus, und die Antwort kommt über dieselbe Leitung zurück. Die meisten Endpunkte sind transparent. Die nicht unterstützten sind unten aufgeführt.

So funktioniert es

Wenn dein Bot GET /guilds/{id} oder POST /channels/{id}/messages aufruft, prüft die Cloud-Bot-API die Stufe des Zielservers. Ist er selbst gehostet, serialisieren wir die Anfrage (Methode, Pfad, Query, Body, bot_user_id) und senden sie über den dauerhaften Steuerkanal-WebSocket, den die Instanz der Kundschaft zu uns offenhält. Der selbst gehostete Prozess führt den passenden Handler gegen seine eigenen SQLite-Datenbanken aus und liefert einen Antwort-Umschlag zurück, den wir wortgetreu an deinen Bot weiterreichen.

Die Weiterleitung geschieht auf der Ebene der Bot-API. Deine Bibliothek bekommt davon nichts mit. Kein anderer Token, keine andere Gateway-URL, kein anderes SDK. Dein Bot verbindet sich mit demselben gateway.gamevox.com und ruft dasselbe bot-api.gamevox.com auf, egal ob die Guild in der Cloud oder selbst gehostet liegt.

Latenz

Die Umlaufzeit hängt von der WAN-Anbindung der Kundschaft plus SQLite-Abfragedauer ab, meist 30–300 ms zusätzlich zu einem Cloud-Aufruf. Es gilt eine Ende-zu-Ende-Frist von 12 s. Antwortet eine selbst gehostete Instanz nicht mehr (offline, Upgrade, Netzabbruch), erhält dein Bot innerhalb einer Sekunde nach Ablauf der Frist 504 Gateway Timeout.

Was funktioniert

Alles Folgende läuft gegen die lokalen Daten der selbst gehosteten Instanz, mit derselben Antwortform wie in der Cloud.

  • Nachrichten: auflisten, abrufen, senden, bearbeiten, löschen, Massenlöschung.
  • Reaktionen: hinzufügen, eigene entfernen, fremde entfernen, alle entfernen, alle zu einem Emoji entfernen, Personen auflisten.
  • Pins: anpinnen, lösen, auflisten.
  • Tippen: POST /channels/{id}/typing.
  • Kanäle: abrufen, ändern, löschen, auflisten, erstellen, neu ordnen.
  • Server (Guild): abrufen, ändern (Name und Beschreibung).
  • Mitglieder: auflisten, suchen, @me, abrufen, ändern, Spitznamen ändern, kicken, Rolle hinzufügen oder entfernen.
  • Banns: auflisten, abrufen, setzen, aufheben.
  • Rollen: auflisten, abrufen, erstellen, ändern, neu ordnen, löschen sowie Rollenberechtigungen.
  • Emojis: auflisten, abrufen (servereigen).
  • Soundboard: auflisten, abrufen (servereigen).
  • Audit-Log: GET /guilds/{id}/audit-logs, nur für Bots relevante Einträge.
  • Vanity-URL: GET (immer die leere Form).
  • Sprachzustand: GET (live von der SFU), PATCH (stummschalten, verschieben, trennen).
  • Webhooks: vollständiges CRUD und Execute. Die Datensätze liegen im Cloud-Speicher; die entstehende Nachricht wird über denselben Weiterleitungspfad wie Bot-Sendungen in den selbst gehosteten Kanal geschrieben, sodass Kanalnachrichten korrekt markiert werden.

Was 501 zurückgibt (akzeptiert, nicht implementiert)

  • PATCH .../voice-states/* mit deaf. Server-seitiges Taubschalten ist auf der selbst gehosteten SFU derzeit kein Primitiv. Stummschalten, Verschieben (über channel_id) und Trennen (über channel_id: null) funktionieren alle.
  • PUT .../channels/{id}/permissions/{oid}. Selbst gehostet nutzt Berechtigungen auf Gruppenebene statt Overwrites pro Kanal, es gibt also nichts, worauf ein Discord-Overwrite angewendet werden könnte. DELETE gibt 204 zurück (das Löschen eines nicht vorhandenen Overwrites ist ein No-Op).
  • PATCH .../guilds/{id}/vanity-url. Selbst gehostete Server haben keine Vanity-URLs.

Was 404 zurückgibt (nicht auf selbst gehostete Server geleitet)

Diese Endpunkte betreffen Ressourcen, die es nur in der Cloud-Infrastruktur gibt. Versuche es gegen eine Cloud-Guild, wenn dein Bot sie braucht.

  • Alle /interactions/*-, Follow-up- und Original-Response-Endpunkte.
  • Das gesamte CRUD für Anwendungsbefehle (/applications/{id}/commands und die Guild-Varianten).
  • Das Erstellen von DM-Kanälen (POST /users/@me/channels).
  • Serverübergreifende Personensuche (GET /users/{id}, GET /users/by-name/{name}).
  • GET /users/@me/guilds.

Gateway-Ereignisse

Selbst gehostete Instanzen veröffentlichen eine Teilmenge der Ereignisse, die die Cloud auslöst. Dein Bot empfängt sie über dieselbe Gateway-Sitzung. Kein anderes Abonnementmodell.

Heute von selbst gehosteten Instanzen ausgelöst:

  • 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 (Änderungen an Name / Beschreibung)
  • GUILD_MEMBER_ADD, GUILD_MEMBER_REMOVE, GUILD_MEMBER_UPDATE (Spitzname oder Rollenwechsel)
  • GUILD_BAN_ADD, GUILD_BAN_REMOVE
  • GUILD_ROLE_CREATE, GUILD_ROLE_UPDATE, GUILD_ROLE_DELETE (wird ausgelöst, wenn sich das Berechtigungsmodell der Instanz ändert)
  • TYPING_START
  • VOICE_STATE_UPDATE (beitreten, verlassen, selbst/server-stumm, taub)

Noch nicht von selbst gehosteten Instanzen ausgelöst:

  • PRESENCE_UPDATE. Erfordert einen neuen Präsenz-Broadcaster auf der selbst gehosteten Seite.
  • DM-Nachrichtenereignisse. Selbst gehostete Instanzen haben keine serverübergreifenden DMs.
  • INTERACTION_CREATE. Aufrufe deiner Befehle auf selbst gehosteten Instanzen werden noch nicht weitergeleitet.

Bekannte Abweichungen

  • Selbst-Stumm vs. Server-Stumm: Die selbst gehostete SFU führt pro teilnehmender Person nur ein einzelnes Stumm-Bit, statt self_mute und mute wie Discord zu trennen. VOICE_STATE_UPDATE spiegelt denselben Wert in beide Felder; das Aufheben einer Server-Stummschaltung kann so aussehen, als hätte die Person auch die Selbst-Stummschaltung aufgehoben. Bots, die nur eines der beiden Felder lesen, sind unbetroffen; zustandsbasierte Bots, die beide mischen, sollten für Moderationsschalter mute bevorzugen.
  • Verschieben löst zwei Ereignisse aus: Discords PATCH auf voice-states/{uid} mit neuer channel_id löst ein einziges VOICE_STATE_UPDATE aus; auf selbst gehosteten Instanzen ist das Verschieben als Verlassen + erneutes Beitreten umgesetzt, sodass du siehst, wie die channel_id der Zielperson kurz auf null springt und dann auf den neuen Kanal. Behandle aufeinanderfolgende Updates derselben Person innerhalb weniger hundert Millisekunden als ein einziges Verschieben.

Selbst gehostete Server erkennen

Das guild-Objekt trägt heute kein „selbst gehostet“-Flag (wir bleiben byte-identisch zu Discord). Muss dein Bot verzweigen, ist das verlässliche Signal ein 501 oder 404 von einem der oben genannten Endpunkte, mit einem JSON-Fehlerbody wie:

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

Wenn genügend Bots eine günstigere Erkennung brauchen, ergänzen wir einen features-Eintrag (z. B. "SELF_HOSTED") im Guild-Payload. Gib im Support-Tab deiner Anwendung Rückmeldung, falls das helfen würde.

Fehler

  • 502 Bad Gateway. Die selbst gehostete Instanz hat eine fehlerhafte Antwort geliefert. Selten; meist ein Versionsversatz während eines Upgrades.
  • 503 Service Unavailable. Der Steuerkanal ist derzeit nicht verbunden. Wiederhole es mit Backoff.
  • 504 Gateway Timeout. Die Instanz hat nicht innerhalb von 12 s geantwortet.

← Zurück zur Doku