Entwicklerportal
Experimentell Die Bot- & App-Plattform wird aktiv weiterentwickelt. Auf selbst gehosteten Servern laufen Bots, Slash-Befehle und Nachrichtenkomponenten, mit einigen Unterschieden zur 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 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. Gateway-Ereignisse laufen in die umgekehrte Richtung. Die meisten Endpunkte sind transparent. Die Unterschiede sind unten aufgeführt.

So funktioniert es

Wenn dein Bot GET /guilds/{id} oder POST /channels/{id}/messages aufruft, prüft die Cloud-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 prüft die Berechtigungen deines Bots gegen seine eigenen Rollen, führt den passenden Handler gegen seine eigenen SQLite-Datenbanken aus und liefert einen Antwort-Envelope zurück, den wir an deinen Bot weiterreichen.

Die Weiterleitung geschieht in der Cloud. 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 app-api.gamevox.com auf, egal ob der Server in der Cloud oder selbst gehostet ist. Dein Bot muss Mitglied des selbst gehosteten Servers sein; andernfalls werden Aufrufe mit 403 beantwortet.

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 (90 s für eine Nachricht mit Dateien, weil die Instanz sie herunterlädt). Ist die Instanz nicht verbunden, erhält dein Bot sofort 503. Ist sie verbunden, antwortet aber nicht rechtzeitig, erhält dein Bot 504.

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. Embeds, Komponenten, Antworten (message_reference), Dateianhänge (Multipart files[n] plus payload_json) und Umfragen. tts wird akzeptiert und ignoriert.
  • 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 (auch App-Kanäle), neu ordnen.
  • Berechtigungs-Overwrites pro Kanal: PUT und DELETE .../channels/{id}/permissions/{oid} sowie permission_overwrites an jedem Kanalobjekt (und in CHANNEL_UPDATE). Das Lesen von permission_overwrites gibt es vorerst nur auf selbst gehosteten Servern: Kanalobjekte in der Cloud enthalten das Feld nicht, und die Cloud-API unterstützt nur die Schreibvorgänge PUT und DELETE. Auf einem selbst gehosteten Server gibt es nur Rollen-Overwrites: oid ist eine Rollen-ID und type muss 0 sein; ein Mitglieder-Overwrite (type: 1) wird abgelehnt. Overwrites decken Kanal ansehen, Nachrichten senden, Dateien anhängen, Reaktionen hinzufügen, Verbinden, Sprechen, Sprachaktivität verwenden und Streamen ab. Ein Allow gewährt nie mehr, als die Rolle selbst darf; ein Allow auf eine Berechtigung, die der Rolle fehlt, wird daher nicht zurückgemeldet. Ein Kanal ohne Overwrites meldet eine leere Liste.
  • Server (Guild): abrufen, ändern (Name und Beschreibung).
  • Mitglieder: auflisten, suchen, @me, abrufen, ändern, Spitznamen ändern, kicken, Rolle hinzufügen oder entfernen.
  • Sperren: auflisten, abrufen, verhängen, aufheben.
  • Rollen: auflisten, abrufen, erstellen, ändern (auch color), neu ordnen, löschen sowie Rollenberechtigungen.
  • Emojis: auflisten, abrufen (servereigen).
  • Soundboard: auflisten, abrufen (servereigen).
  • Audit-Log: GET /guilds/{id}/audit-logs, Einträge für Aktionen, die über die Bot-API ausgeführt wurden.
  • Vanity-URL: GET (immer die leere Struktur).
  • Sprachzustand: GET (live von der SFU), PATCH mit mute, deaf und channel_id (verschieben, oder null zum Trennen), in beliebiger Kombination. mute und deaf sind die Server-Flags; self_mute und self_deaf sind die des Mitglieds selbst.
  • Webhooks: vollständiges CRUD und Ausführen. Die Webhook-Datensätze liegen in der Cloud; beim Ausführen erzeugte Nachrichten werden in den selbst gehosteten Kanal geschrieben und erscheinen unter dem Namen des Webhooks.
  • Geplante Termine: auflisten, erstellen, abrufen, ändern, löschen, interessierte Personen auflisten sowie die Zusage (RSVP) eines Mitglieds setzen oder entfernen, mit denselben Strukturen wie in der Cloud. Wiederholungseinstellungen werden gespeichert, spätere Vorkommen eines wiederkehrenden Termins werden aber nicht erzeugt.
  • Forenbeiträge: einen Beitrag starten (POST /channels/{forum}/threads), ihn lesen und darin antworten. Die Eröffnungsnachricht eines Beitrags ist auf 10.000 Zeichen begrenzt (20.000 in der Cloud).
  • Slash-Befehle: Aufruf, wobei Berechtigungen gegen die Rollen der Instanz selbst geprüft werden. Die Registrierung ist dieselbe wie in der Cloud.
  • Nachrichtenkomponenten: Buttons, String-Auswahlmenüs, Dialoge und ephemere Antworten, einschließlich der Endpunkte für Interaktions-Callback, Follow-ups und Original-Response. Siehe Nachrichtenkomponenten.

Was 501 zurückgibt (akzeptiert, nicht implementiert)

  • PATCH .../guilds/{id}/vanity-url. Selbst gehostete Server haben keine Vanity-URLs.

Von der Cloud beantwortet, nicht von der Instanz

Diese Endpunkte betreffen GameVox-Konten statt eines einzelnen Servers, daher beantwortet die Cloud sie für jeden Bot. Mitglieder selbst gehosteter Server sind gewöhnliche GameVox-Konten.

  • GET /users/{id} und GET /users/by-name/{name}.
  • GET /users/@me/guilds, einschließlich der selbst gehosteten Server, auf denen deine App installiert ist.
  • POST /users/@me/channels liefert einen DM-Kanal, aber das Senden von Nachrichten dorthin wird noch nicht unterstützt, weder in der Cloud noch auf selbst gehosteten Servern.

Gateway-Ereignisse

Selbst gehostete Instanzen veröffentlichen Ereignisse über dieselbe Gateway-Sitzung wie die Cloud. Kein anderes Abonnementmodell. Kanalereignisse werden nur an Bots zugestellt, die den Kanal sehen können, und Intents gelten wie in der Cloud.

Ausgelöst für Aktionen von Personen auf der Instanz und für die eigenen REST-Aufrufe deines Bots:

  • MESSAGE_CREATE, MESSAGE_UPDATE, MESSAGE_DELETE
  • MESSAGE_DELETE_BULK (auch wenn ein Kick oder Bann die Nachrichten des Mitglieds entfernt)
  • 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 (Änderungen an Name / Beschreibung)
  • GUILD_MEMBER_ADD
  • GUILD_MEMBER_REMOVE (Verlassen, Kick, Bann, Bereinigung inaktiver Gäste)
  • GUILD_MEMBER_UPDATE (Rollenwechsel, Änderung von Benutzername oder Avatar)
  • GUILD_BAN_ADD
  • GUILD_ROLE_CREATE, GUILD_ROLE_UPDATE, GUILD_ROLE_DELETE (Erstellen, Umbenennen, Neuordnen, Änderungen an Farbe und Berechtigungen)
  • GUILD_EMOJIS_UPDATE
  • TYPING_START
  • PRESENCE_UPDATE (erfordert den Intent GUILD_PRESENCES; nur Änderungen, kein Snapshot der Mitglieder, die beim Verbinden bereits online sind)
  • VOICE_STATE_UPDATE (Beitreten, Verlassen, Verschieben, Stumm- und Taubschalten durch die Person selbst und durch den Server)
  • INTERACTION_CREATE (Slash-Befehle, Klicks auf Komponenten und abgeschickte Dialoge; von der Cloud weitergeleitet)

Nur für Änderungen ausgelöst, die dein Bot über REST vornimmt:

  • GUILD_BAN_REMOVE (auf der Instanz gibt es für Personen keine Aktion zum Aufheben eines Banns)
  • MESSAGE_REACTION_REMOVE_ALL, MESSAGE_REACTION_REMOVE_EMOJI (auf der Instanz gibt es für Personen keine solche Aktion)

Nicht ausgelöst (auch nicht in der Cloud):

  • THREAD_*, INVITE_*, GUILD_SCHEDULED_EVENT_*.

Bekannte Abweichungen

  • 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. Wird mute oder deaf zusammen mit einem Verschieben gesendet, wird es angewendet, wenn das Mitglied wieder beitritt.
  • Anhang-URLs: Die url eines Anhangs auf einem selbst gehosteten Server zeigt auf die Instanz der Kundschaft und erfordert zum Herunterladen eine Mitgliedssitzung. Dein Bot sieht Name, Größe und Typ der Datei, kann die Datei aber noch nicht abrufen. width, height und description werden auf selbst gehosteten Servern nicht gespeichert.

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 Signal ein 501 von einem der oben genannten Endpunkte, mit dem Grund der Instanz im JSON-Fehlerbody, etwa so:

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

Ein 404 ("Unknown resource") bedeutet, dass die Ressource fehlt, nicht dass der Server selbst gehostet ist. 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