Portal do Desenvolvedor
Experimental A plataforma de bots & apps está em desenvolvimento ativo. Servidores auto-hospedados rodam bots, comandos de barra e componentes de mensagem, com algumas diferenças em relação à nuvem. Veja o que é suportado.
← Documentação

Logs do bot

A aba Bot da sua aplicação pode pedir ao bot em execução as linhas de log recentes dele, para você ver o que aconteceu sem entrar na máquina onde ele roda. Esta página descreve o protocolo que um bot implementa para responder.

Como funciona

  1. Um desenvolvedor (dono, ou desenvolvedor da equipe e acima) aperta Solicitar logs na aba Bot e escolhe um intervalo de tempo e uma quantidade de linhas.
  2. O GameVox envia ao seu bot um despacho do gateway chamado GAMEVOX_LOG_REQUEST. Ele vai só para as sessões de gateway ativas dessa mesma aplicação.
  3. O seu bot junta as linhas desse intervalo e as envia com uma única chamada REST. O portal as mostra assim que chegam.
  4. Se nada chegar em dois minutos, o portal avisa que o bot não respondeu. Um bot que não conhece o evento o ignora, então nada quebra para bibliotecas que nunca ouviram falar dele.

O evento do gateway

Um despacho comum (opcode 0) com t definido como GAMEVOX_LOG_REQUEST. Ele traz um número de sequência como qualquer outro despacho e é reenviado ao retomar a sessão.

{
  "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: identifica a requisição; faz parte da URL de envio.
  • since: horário RFC 3339. Envie as linhas a partir dele.
  • max_lines: o máximo de linhas desejadas (de 50 a 20.000). Envie as mais recentes se tiver mais.
  • nonce: um segredo de uso único para esta requisição. Devolva-o com o envio; ele prova que o envio vem do bot que recebeu a requisição.
  • expires_at: horário RFC 3339 depois do qual o envio é recusado (dois minutos após a requisição).

Enviando as linhas

Responda com uma única requisição, autenticada como qualquer outra chamada de bot (Authorization: Bot <token>). JSON é o formato normal:

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

Cada linha é {ts, level, msg}: ts um horário RFC 3339, level um entre debug, info, warn, error, e msg o texto. Uma string simples é aceita no lugar de um objeto.

Texto simples também funciona: envie Content-Type: text/plain com uma linha por registro e o nonce em um cabeçalho X-GameVox-Log-Nonce. Linhas enviadas assim não têm horário nem nível (o GameVox deduz um nível pelas palavras da linha). O cabeçalho também funciona com JSON; o campo no corpo é só uma conveniência.

Limites e regras

  • O corpo pode ter no máximo 2 MiB e uma requisição guarda no máximo 20.000 linhas. Acima do limite de linhas, as mais recentes são mantidas; um corpo maior é recusado com 413.
  • Uma requisição pode ser respondida uma vez. Um segundo envio recebe 409.
  • Só a aplicação para a qual a requisição foi feita pode respondê-la. O id de requisição de outra aplicação parece um id desconhecido (404).
  • O envio precisa chegar antes de expires_at (410 depois disso).
  • O nonce precisa corresponder (403 caso contrário).
  • As requisições são limitadas a uma a cada 30 segundos e 30 por dia por aplicação. Os pacotes ficam guardados por 7 dias e depois são excluídos.
  • O texto dos logs é mostrado só como texto simples. Caracteres de controle são removidos e cada linha é cortada em 4.000 caracteres.

Erros

  • 400: o corpo não é um JSON válido, ou o nonce está faltando.
  • 403: o nonce não corresponde.
  • 404: não existe essa requisição para a sua aplicação.
  • 409: a requisição já foi respondida.
  • 410: a requisição expirou.
  • 413: o corpo passa de 2 MiB.
  • 429: o seu bot está sujeito a limite de taxa como em qualquer outra rota.

Remova segredos antes de enviar

Os logs saem da sua máquina, então remova o que não deveria sair dela: o token do seu bot e qualquer outra credencial, cabeçalhos Authorization, senhas em URLs, endereços de e-mail e os endereços IP dos seus usuários. Os bots do próprio GameVox fazem tudo isso antes de enviar.

O GameVox também oculta dados na chegada (tokens, valores de Authorization, pares key=value cuja chave indica um segredo, senhas em URLs, strings hexadecimais longas e endereços de e-mail) e informa a quem está vendo quantos valores ocultou. Isso é uma rede de segurança, não um motivo para pular a sua própria ocultação: ele não tem como saber o que é privado nas suas mensagens.

Exemplo

A maioria das bibliotecas entrega os eventos que não modela por um hook bruto: on_socket_raw_receive no discord.py, o evento raw no discord.js. Mantenha alguns milhares das últimas linhas em um buffer circular e, quando o evento chegar, envie a parte pedida.

# 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})

Compatibilidade

O evento é novo e opcional. Bots escritos com bibliotecas do Discord continuam funcionando sem mudanças, porque um despacho que a biblioteca não conhece é ignorado. Os bots do próprio GameVox (League of Legends, VALORANT, Deadlock, Valheim, WARDOGS, guilda de WoW, Tickets e Tibia) dão suporte a ele pela biblioteca de bots compartilhada.

← Todos os docs