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

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 no formato do Discord pelo canal de controle do cliente, a instância auto-hospedada as executa no banco local, e a resposta volta pelo mesmo caminho. Os eventos de gateway fazem o caminho inverso. A maioria dos endpoints é transparente. As diferenças estão listadas abaixo.

Como funciona

Quando o seu bot chama GET /guilds/{id} ou POST /channels/{id}/messages, a API 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 verifica as permissões do seu bot com base nos próprios cargos, executa o handler equivalente nos próprios bancos SQLite e devolve um envelope de resposta, que repassamos ao seu bot.

O encaminhamento acontece na nuvem. 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 app-api.gamevox.com, esteja o servidor na nuvem ou auto-hospedado. Seu bot precisa ser integrante do servidor auto-hospedado; caso contrário, as chamadas respondem 403.

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 (90 s para uma mensagem com arquivos, porque a instância os baixa). Se a instância não estiver conectada, seu bot recebe 503 na hora. Se estiver conectada mas não responder a tempo, seu bot recebe 504.

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. Embeds, componentes, respostas (message_reference), anexos de arquivo (multipart files[n] mais payload_json) e enquetes. tts é aceito e ignorado.
  • Reações: adicionar, remover a própria, remover a de um usuário, remover todas, remover todas de um emoji, listar usuários.
  • Fixadas: fixar, desafixar, listar.
  • Digitação: POST /channels/{id}/typing.
  • Canais: obter, alterar, excluir, listar, criar (incluindo canais de app), reordenar.
  • Exceções de permissão por canal: PUT e DELETE .../channels/{id}/permissions/{oid}, e permission_overwrites em todo objeto de canal (e em CHANNEL_UPDATE). Por enquanto, a leitura de permission_overwrites só existe no auto-hospedado: os objetos de canal da nuvem não incluem o campo, e a API na nuvem só suporta as escritas PUT e DELETE. Num servidor auto-hospedado só existem exceções de cargo: oid é um id de cargo e type precisa ser 0; uma exceção de integrante (type: 1) é rejeitada. A exceção cobre ver o canal, enviar mensagens, anexar arquivos, adicionar reações, conectar, falar, usar detecção de voz e transmitir. Uma liberação nunca concede mais do que o próprio cargo tem permitido, então uma liberação numa permissão que o cargo não tem não aparece na resposta. Um canal sem exceções devolve uma lista vazia.
  • 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 (incluindo color), 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, entradas das ações feitas pela API de bots.
  • URL personalizada: GET (sempre o formato vazio).
  • Estado de voz: GET (ao vivo do SFU), PATCH com mute, deaf e channel_id (mover, ou null para desconectar), em qualquer combinação. mute e deaf são as marcações do servidor; self_mute e self_deaf são as do próprio integrante.
  • Webhooks: CRUD completo e execução. Os registros dos webhooks ficam na nuvem; as mensagens geradas pela execução são gravadas no canal auto-hospedado e aparecem com o nome do webhook.
  • Eventos agendados: listar, criar, obter, alterar, excluir, listar pessoas interessadas, e definir ou limpar o RSVP de um integrante, com os mesmos formatos da nuvem. As configurações de repetição são armazenadas, mas as ocorrências seguintes de um evento recorrente não são geradas.
  • Publicações de fórum: criar uma publicação (POST /channels/{forum}/threads), lê-la e responder nela. A mensagem de abertura de uma publicação é limitada a 10.000 caracteres (20.000 na nuvem).
  • Comandos de barra: invocação, com permissões verificadas contra os cargos da própria instância. O registro é o mesmo da nuvem.
  • Componentes de mensagem: botões, seletores de string, modais e respostas efêmeras, incluindo os endpoints de callback da interação, de follow-up e de resposta original. Veja Componentes de mensagem.

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

  • PATCH .../guilds/{id}/vanity-url. Servidores auto-hospedados não têm URL personalizada.

Respondidos pela nuvem, não pela instância

Estes endpoints tratam de contas GameVox, e não de um servidor específico, então a nuvem os responde para todos os bots. Os integrantes de servidores auto-hospedados são contas GameVox comuns.

  • GET /users/{id} e GET /users/by-name/{name}.
  • GET /users/@me/guilds, que inclui os servidores auto-hospedados em que o seu app está instalado.
  • POST /users/@me/channels devolve um canal de DM, mas enviar mensagens nele ainda não é suportado, nem na nuvem nem no auto-hospedado.

Eventos do gateway

Instâncias auto-hospedadas publicam eventos pela mesma sessão de gateway que a nuvem. Sem outro modelo de assinatura. Eventos de canal só são entregues a bots que podem ver o canal, e os intents valem como na nuvem.

Emitidos para ações de pessoas na instância e para as chamadas REST do seu bot:

  • MESSAGE_CREATE, MESSAGE_UPDATE, MESSAGE_DELETE
  • MESSAGE_DELETE_BULK (também quando uma expulsão ou um banimento remove as mensagens do integrante)
  • 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 (mudanças de nome / descrição)
  • GUILD_MEMBER_ADD
  • GUILD_MEMBER_REMOVE (saída, expulsão, banimento, remoção de convidados inativos)
  • GUILD_MEMBER_UPDATE (mudança de cargo, de nome de usuário ou de avatar)
  • GUILD_BAN_ADD
  • GUILD_ROLE_CREATE, GUILD_ROLE_UPDATE, GUILD_ROLE_DELETE (criação, renomeação, reordenação, mudanças de cor e de permissões)
  • GUILD_EMOJIS_UPDATE
  • TYPING_START
  • PRESENCE_UPDATE (exige o intent GUILD_PRESENCES; só mudanças, sem um retrato dos integrantes que já estão online quando você se conecta)
  • VOICE_STATE_UPDATE (entrada, saída, movimentação, silenciamento e ensurdecimento próprios e do servidor)
  • INTERACTION_CREATE (comandos de barra, cliques em componentes e envios de modais; repassados pela nuvem)

Emitidos só para mudanças que o seu bot faz por REST:

  • GUILD_BAN_REMOVE (a instância não oferece às pessoas uma ação de desbanir)
  • MESSAGE_REACTION_REMOVE_ALL, MESSAGE_REACTION_REMOVE_EMOJI (a instância não oferece essa ação às pessoas)

Não emitidos (nem na nuvem):

  • THREAD_*, INVITE_*, GUILD_SCHEDULED_EVENT_*.

Diferenças conhecidas de fidelidade

  • Mover na voz 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. Um mute ou deaf enviado junto com uma movimentação é aplicado quando o integrante entra de novo.
  • URLs de anexos: num servidor auto-hospedado, a url de um anexo aponta para a instância do cliente e exige uma sessão de integrante para ser baixada. Seu bot vê o nome, o tamanho e o tipo do arquivo, mas ainda não consegue baixá-lo. width, height e description não são guardados no auto-hospedado.

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 é um 501 vindo de um endpoint listado acima, com o motivo da instância no corpo de erro JSON, como:

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

Um 404 ("Unknown resource") significa que o recurso não existe, não que o servidor é auto-hospedado. 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 for ajudar.

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