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

Bot-Logs

Der Tab „Bot“ deiner Anwendung kann den laufenden Bot nach seinen letzten Logzeilen fragen, sodass du sehen kannst, was passiert ist, ohne dich auf der Maschine anzumelden, auf der er läuft. Diese Seite beschreibt das Protokoll, das ein Bot implementiert, um zu antworten.

So funktioniert es

  1. Eine Person mit Entwicklerzugang (Eigentümer oder Teamrolle Entwickler und höher) drückt im Tab „Bot“ auf Logs anfordern und wählt ein Zeitfenster und eine Zeilenzahl.
  2. GameVox sendet deinem Bot einen Gateway-Dispatch namens GAMEVOX_LOG_REQUEST. Er geht nur an die aktiven Gateway-Sitzungen genau dieser Anwendung.
  3. Dein Bot sammelt die Zeilen dieses Zeitfensters und lädt sie mit einem REST-Aufruf hoch. Das Portal zeigt sie an, sobald sie ankommen.
  4. Kommt innerhalb von zwei Minuten nichts an, meldet das Portal, dass der Bot nicht geantwortet hat. Ein Bot, der das Ereignis nicht kennt, ignoriert es, sodass bei Bibliotheken, die nie davon gehört haben, nichts kaputtgeht.

Das Gateway-Ereignis

Ein gewöhnlicher Dispatch (Opcode 0) mit t gleich GAMEVOX_LOG_REQUEST. Er trägt wie jeder andere Dispatch eine Sequenznummer und wird beim Resume erneut zugestellt.

{
  "op": 0,
  "s": 4821,
  "t": "GAMEVOX_LOG_REQUEST",
  "d": {
    "request_id": "6f0c2d1e-8a54-4b7e-9c3d-2a1f5e7b9d40",
    "since": "2026-10-30T11:45:00Z",
    "max_lines": 2000,
    "nonce": "3f9a0c...e1b7",
    "expires_at": "2026-10-30T12:02:00Z"
  }
}
  • request_id: identifiziert die Anfrage; Teil der Upload-URL.
  • since: Zeitpunkt nach RFC 3339. Sende Zeilen ab diesem Zeitpunkt.
  • max_lines: die gewünschte Höchstzahl an Zeilen (50 bis 20.000). Sende die neuesten, wenn du mehr hast.
  • nonce: ein einmaliges Geheimnis für diese Anfrage. Sende es mit dem Upload zurück; es beweist, dass der Upload von dem Bot kommt, der die Anfrage erhalten hat.
  • expires_at: Zeitpunkt nach RFC 3339, nach dem der Upload abgelehnt wird (zwei Minuten nach der Anfrage).

Die Zeilen hochladen

Antworte mit einer Anfrage, authentifiziert wie jeder andere Bot-Aufruf (Authorization: Bot <token>). JSON ist die normale Form:

POST /api/v10/applications/@me/log-requests/6f0c2d1e-8a54-4b7e-9c3d-2a1f5e7b9d40
Authorization: Bot <token>
Content-Type: application/json

{
  "nonce": "3f9a0c...e1b7",
  "lines": [
    { "ts": "2026-10-30T11:58:02.114Z", "level": "info",  "msg": "synced 12 guilds" },
    { "ts": "2026-10-30T11:58:09.870Z", "level": "error", "msg": "poll failed: timeout" }
  ]
}

HTTP/1.1 204 No Content

Jede Zeile ist {ts, level, msg}: ts ein Zeitpunkt nach RFC 3339, level eines von debug, info, warn, error, und msg der Text. Statt eines Objekts wird auch ein einfacher String akzeptiert.

Reiner Text geht auch: Sende Content-Type: text/plain mit einer Zeile pro Eintrag und der Nonce in einem Header X-GameVox-Log-Nonce. So gesendete Zeilen haben keinen Zeitstempel und keine Stufe (GameVox schätzt die Stufe anhand der Wörter in der Zeile). Der Header funktioniert auch mit JSON; das Body-Feld ist nur eine Erleichterung.

Grenzwerte und Regeln

  • Der Body darf höchstens 2 MiB groß sein, und eine Anfrage behält höchstens 20.000 Zeilen. Über dem Zeilenlimit werden die neuesten Zeilen behalten; ein größerer Body wird mit 413 abgelehnt.
  • Eine Anfrage kann einmal beantwortet werden. Ein zweiter Upload bekommt 409.
  • Nur die Anwendung, für die die Anfrage gestellt wurde, kann sie beantworten. Die Anfrage-ID einer anderen Anwendung sieht wie eine unbekannte ID aus (404).
  • Der Upload muss vor expires_at ankommen (danach 410).
  • Die Nonce muss übereinstimmen (sonst 403).
  • Anfragen sind auf eine alle 30 Sekunden und 30 pro Tag und Anwendung begrenzt. Pakete werden 7 Tage aufbewahrt und dann gelöscht.
  • Logtext wird nur als reiner Text angezeigt. Steuerzeichen werden entfernt, und jede Zeile wird bei 4.000 Zeichen abgeschnitten.

Fehler

  • 400: Der Body ist kein gültiges JSON, oder die Nonce fehlt.
  • 403: Die Nonce stimmt nicht überein.
  • 404: keine solche Anfrage für deine Anwendung.
  • 409: Die Anfrage wurde bereits beantwortet.
  • 410: Die Anfrage ist abgelaufen.
  • 413: Der Body ist größer als 2 MiB.
  • 429: Dein Bot unterliegt einem Rate-Limit wie bei jeder anderen Route.

Entferne Geheimnisse vor dem Senden

Logs verlassen deine Maschine, also entferne, was sie nicht verlassen soll: dein Bot-Token und alle anderen Zugangsdaten, Authorization-Header, Passwörter in URLs, E-Mail-Adressen und die IP-Adressen deiner Nutzenden. Die Bots von GameVox selbst tun all das vor dem Hochladen.

GameVox schwärzt auch beim Eingang (Tokens, Authorization-Werte, key=value-Paare, deren Schlüssel ein Geheimnis benennt, Passwörter in URLs, lange Hex-Strings und E-Mail-Adressen) und teilt der betrachtenden Person mit, wie viele Werte verborgen wurden. Das ist ein Sicherheitsnetz, kein Grund, die eigene Schwärzung auszulassen: GameVox kann nicht wissen, was in deinen Meldungen privat ist.

Beispiel

Die meisten Bibliotheken reichen Ereignisse, die sie nicht modellieren, über einen rohen Hook weiter: on_socket_raw_receive in discord.py, das Ereignis raw in discord.js. Halte die letzten paar tausend Zeilen in einem Ringpuffer, und wenn das Ereignis ankommt, sende den angefragten Teil.

# discord.py: keep recent lines, answer GAMEVOX_LOG_REQUEST
import collections, json, logging
from datetime import datetime, timezone

RING = collections.deque(maxlen=5000)

class Ring(logging.Handler):
    def emit(self, record):
        RING.append({"ts": datetime.fromtimestamp(record.created, timezone.utc).isoformat(),
                     "level": record.levelname.lower(),
                     "msg": redact(self.format(record))})

logging.getLogger().addHandler(Ring())

@client.event
async def on_socket_raw_receive(msg):
    packet = json.loads(msg)
    if packet.get("t") != "GAMEVOX_LOG_REQUEST":
        return
    d = packet["d"]
    lines = [l for l in RING if l["ts"] >= d["since"]][-d["max_lines"]:]
    await session.post(
        f"https://app-api.gamevox.com/api/v10/applications/@me/log-requests/{d['request_id']}",
        headers={"Authorization": f"Bot {TOKEN}"},
        json={"nonce": d["nonce"], "lines": lines})

Kompatibilität

Das Ereignis ist neu und optional. Bots, die mit Discord-Bibliotheken geschrieben sind, funktionieren unverändert weiter, weil eine Bibliothek einen Dispatch ignoriert, den sie nicht kennt. Die Bots von GameVox selbst (League of Legends, VALORANT, Deadlock, Valheim, WARDOGS, WoW-Gilde, Tickets und Tibia) unterstützen es über die gemeinsame Bot-Bibliothek.

← Zurück zur Doku