Portal do Desenvolvedor
Experimental A plataforma de bots e apps está em desenvolvimento ativo. O suporte a servidores auto-hospedados chegou em 13/08/2026 com menos recursos que a nuvem. Veja o que é suportado.
← Documentação

Servidores auto-hospedados

Clientes podem rodar o GameVox no próprio hardware, e o seu bot funciona lá. A API na nuvem encaminha chamadas REST e eventos de gateway no formato do Discord pelo canal de controle do cliente, a instância auto-hospedada os executa no banco local, e a resposta volta pelo mesmo caminho. A maioria dos endpoints é transparente. Os não suportados estão listados abaixo.

Como funciona

Quando o seu bot chama GET /guilds/{id} ou POST /channels/{id}/messages, a API de bots na nuvem confere o nível do servidor de destino. Se for auto-hospedado, serializamos a requisição (método, caminho, query, corpo, bot_user_id) e a enviamos pelo WebSocket de canal de controle que a instância do cliente mantém aberto conosco. O processo auto-hospedado executa o handler equivalente nos próprios bancos SQLite e devolve um envelope de resposta, que repassamos ao seu bot ao pé da letra.

O encaminhamento acontece na camada da API de bots. Sua biblioteca nunca vê isso. Sem outro token, sem outra URL de gateway, sem outro SDK. Seu bot se conecta ao mesmo gateway.gamevox.com e chama o mesmo bot-api.gamevox.com, esteja a guild na nuvem ou auto-hospedada.

Latência

O tempo de ida e volta é limitado pelo link WAN do cliente mais o tempo de consulta do SQLite, normalmente 30–300 ms além de uma chamada na nuvem. Há um prazo total de 12 s. Se uma instância auto-hospedada parar de responder (offline, atualizando, rede cortada), seu bot recebe 504 Gateway Timeout em até um segundo após o prazo.

O que funciona

Tudo abaixo roda sobre os dados locais da instância auto-hospedada, com o mesmo formato de resposta da nuvem.

  • Mensagens: listar, obter, enviar, editar, excluir, excluir em lote.
  • Reações: adicionar, remover a própria, remover a de outra pessoa, remover todas, remover todas de um emoji, listar pessoas.
  • Fixadas: fixar, desafixar, listar.
  • Digitação: POST /channels/{id}/typing.
  • Canais: obter, alterar, excluir, listar, criar, reordenar.
  • Servidor (guild): obter, alterar (nome e descrição).
  • Integrantes: listar, buscar, @me, obter, alterar, alterar apelido, expulsar, adicionar ou remover cargo.
  • Banimentos: listar, obter, aplicar, remover.
  • Cargos: listar, obter, criar, alterar, reordenar, excluir, além das permissões de cargo.
  • Emojis: listar, obter (do servidor).
  • Soundboard: listar, obter (do servidor).
  • Registro de auditoria: GET /guilds/{id}/audit-logs, só entradas relevantes para bots.
  • URL personalizada: GET (sempre o formato vazio).
  • Estado de voz: GET (ao vivo do SFU), PATCH (silenciar, mover, desconectar).
  • Webhooks: CRUD completo e execução. Os registros ficam no armazenamento na nuvem; a mensagem resultante é escrita no canal auto-hospedado pelo mesmo caminho de encaminhamento dos envios do bot, então as mensagens do canal são marcadas corretamente.

O que devolve 501 (aceito, não implementado)

  • PATCH .../voice-states/* com deaf. Ensurdecer pelo servidor não é uma primitiva do SFU auto-hospedado hoje. Silenciar, mover (via channel_id) e desconectar (via channel_id: null) funcionam.
  • PUT .../channels/{id}/permissions/{oid}. O auto-hospedado usa permissões em nível de grupo em vez de exceções por canal, então não há a que aplicar uma exceção do Discord. O DELETE devolve 204 (excluir uma exceção que não existe não faz nada).
  • PATCH .../guilds/{id}/vanity-url. Servidores auto-hospedados não têm URL personalizada.

O que devolve 404 (não roteado para o auto-hospedado)

Estes endpoints tocam recursos que só existem na infraestrutura em nuvem. Tente de novo em uma guild na nuvem se o seu bot precisar deles.

  • Todos os endpoints de /interactions/*, de follow-up e de resposta original.
  • Todo o CRUD de comandos de aplicação (/applications/{id}/commands e as variantes por guild).
  • A criação de canais de DM (POST /users/@me/channels).
  • A busca de pessoas entre servidores (GET /users/{id}, GET /users/by-name/{name}).
  • GET /users/@me/guilds.

Eventos do gateway

Instâncias auto-hospedadas publicam um subconjunto dos eventos que a nuvem emite. Seu bot os recebe pela mesma sessão de gateway. Sem outro modelo de assinatura.

Emitidos hoje pelo auto-hospedado:

  • 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 (mudanças de nome / descrição)
  • GUILD_MEMBER_ADD, GUILD_MEMBER_REMOVE, GUILD_MEMBER_UPDATE (mudança de apelido ou de cargo)
  • GUILD_BAN_ADD, GUILD_BAN_REMOVE
  • GUILD_ROLE_CREATE, GUILD_ROLE_UPDATE, GUILD_ROLE_DELETE (disparado quando o modelo de permissões da instância muda)
  • TYPING_START
  • VOICE_STATE_UPDATE (entrar, sair, silêncio próprio/do servidor, ensurdecer)

Ainda não emitidos pelo auto-hospedado:

  • PRESENCE_UPDATE. Exige um novo difusor de presença no auto-hospedado.
  • Eventos de mensagens em DM. O auto-hospedado não tem DMs entre servidores.
  • INTERACTION_CREATE. As invocações dos seus comandos em instâncias auto-hospedadas ainda não são encaminhadas.

Diferenças conhecidas de fidelidade

  • Silêncio próprio x silêncio do servidor: o SFU auto-hospedado mantém um único bit de silêncio por participante, em vez de separar self_mute de mute como o Discord. O VOICE_STATE_UPDATE espelha o mesmo valor nos dois campos; tirar um silêncio do servidor pode parecer que a pessoa também tirou o próprio. Bots que leem só um dos campos ficam bem; bots com máquina de estados que misturam os dois devem preferir mute para alternâncias de moderação.
  • Mover dispara dois eventos: o PATCH do Discord em voice-states/{uid} com um novo channel_id emite um único VOICE_STATE_UPDATE; no auto-hospedado a movimentação é implementada como sair + entrar de novo, então você verá o channel_id da pessoa piscar para null e depois para o novo canal. Trate atualizações consecutivas da mesma pessoa dentro de algumas centenas de milissegundos como uma única movimentação.

Detectando o auto-hospedado

O objeto guild não traz hoje uma marca de “auto-hospedado” (estamos mantendo paridade byte a byte com o Discord). Se o seu bot precisar ramificar, o sinal confiável é um 501 ou 404 vindo de um dos endpoints acima, com um corpo de erro JSON como:

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

Se bots suficientes precisarem de uma detecção mais barata, vamos acrescentar uma entrada em features (por exemplo "SELF_HOSTED") ao payload da guild. Envie um retorno pela aba de suporte da sua aplicação se isso ajudaria.

Erros

  • 502 Bad Gateway. A instância auto-hospedada devolveu uma resposta malformada. Raro; normalmente é diferença de versão durante uma atualização.
  • 503 Service Unavailable. O canal de controle não está conectado no momento. Tente de novo com backoff.
  • 504 Gateway Timeout. A instância não respondeu em 12 s.

← Voltar para a documentação