Portal de Desarrolladores
Experimental La plataforma de bots y apps está en desarrollo activo. La compatibilidad con servidores autoalojados llegó el 13-08-2026 con menos funciones que la nube. Consulta qué se admite.
← Documentación

Servidores autoalojados

La clientela puede ejecutar GameVox en su propio hardware, y tu bot funciona allí. La API en la nube reenvía las llamadas REST y los eventos de gateway con forma de Discord por el canal de control de la clientela, la instancia autoalojada los ejecuta contra su base de datos local y la respuesta vuelve por la misma vía. La mayoría de endpoints son transparentes. Los no admitidos están listados abajo.

Cómo funciona

Cuando tu bot llama a GET /guilds/{id} o POST /channels/{id}/messages, la API de bots en la nube comprueba el nivel del servidor de destino. Si es autoalojado, serializamos la petición (método, ruta, query, cuerpo, bot_user_id) y la enviamos por el WebSocket de canal de control que la instancia mantiene abierto hacia nosotros. El proceso autoalojado ejecuta el manejador equivalente contra sus propias bases de datos SQLite y devuelve un sobre de respuesta, que reenviamos a tu bot literalmente.

El reenvío ocurre en la capa de la API de bots. Tu biblioteca nunca lo ve. Ni otro token, ni otra URL de gateway, ni otro SDK. Tu bot se conecta al mismo gateway.gamevox.com y llama al mismo bot-api.gamevox.com tanto si la guild está en la nube como si es autoalojada.

Latencia

El tiempo de ida y vuelta está limitado por el enlace WAN de la clientela más el tiempo de consulta SQLite, normalmente 30–300 ms por encima de una llamada en la nube. Se aplica un plazo total de 12 s. Si una instancia autoalojada deja de responder (apagada, actualizándose, red caída), tu bot recibe 504 Gateway Timeout en el segundo siguiente al plazo.

Qué funciona

Todo lo de abajo se ejecuta contra los datos locales de la instancia autoalojada, con la misma forma de respuesta que en la nube.

  • Mensajes: listar, obtener, enviar, editar, eliminar y eliminar en bloque.
  • Reacciones: añadir, quitar la propia, quitar la de otra persona, quitar todas, quitar todas las de un emoji, listar personas.
  • Fijados: fijar, desfijar, listar.
  • Escribiendo: POST /channels/{id}/typing.
  • Canales: obtener, modificar, eliminar, listar, crear, reordenar.
  • Servidor (guild): obtener, modificar (nombre y descripción).
  • Miembros: listar, buscar, @me, obtener, modificar, cambiar apodo, expulsar, añadir o quitar rol.
  • Baneos: listar, obtener, poner, quitar.
  • Roles: listar, obtener, crear, modificar, reordenar, eliminar, además de permisos de rol.
  • Emojis: listar, obtener (del servidor).
  • Soundboard: listar, obtener (del servidor).
  • Registro de auditoría: GET /guilds/{id}/audit-logs, solo entradas relevantes para bots.
  • URL personalizada: GET (siempre la forma vacía).
  • Estado de voz: GET (en vivo desde la SFU), PATCH (silenciar, mover, desconectar).
  • Webhooks: CRUD completo y ejecución. Los registros viven en el almacenamiento en la nube; el mensaje resultante se escribe en el canal autoalojado por la misma vía de reenvío que usan los envíos del bot, así que los mensajes del canal se marcan correctamente.

Qué devuelve 501 (aceptado, no implementado)

  • PATCH .../voice-states/* con deaf. Ensordecer desde el servidor no es hoy una primitiva de la SFU autoalojada. Silenciar, mover (con channel_id) y desconectar (con channel_id: null) sí funcionan.
  • PUT .../channels/{id}/permissions/{oid}. El autoalojado usa permisos a nivel de grupo en lugar de excepciones por canal, así que no hay nada a lo que aplicar una excepción de Discord. DELETE devuelve 204 (borrar una excepción que no existe no hace nada).
  • PATCH .../guilds/{id}/vanity-url. Los servidores autoalojados no tienen URL personalizada.

Qué devuelve 404 (no se enruta al autoalojado)

Estos endpoints tocan recursos que solo existen en la infraestructura en la nube. Reinténtalo contra una guild en la nube si tu bot los necesita.

  • Todos los endpoints de /interactions/*, de seguimiento y de respuesta original.
  • Todo el CRUD de comandos de aplicación (/applications/{id}/commands y las variantes por guild).
  • La creación de canales de MD (POST /users/@me/channels).
  • La búsqueda de personas entre servidores (GET /users/{id}, GET /users/by-name/{name}).
  • GET /users/@me/guilds.

Eventos del gateway

Las instancias autoalojadas publican un subconjunto de los eventos que emite la nube. Tu bot los recibe por la misma sesión de gateway. Sin un modelo de suscripción distinto.

Emitidos hoy desde el autoalojado:

  • 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 (cambios de nombre / descripción)
  • GUILD_MEMBER_ADD, GUILD_MEMBER_REMOVE, GUILD_MEMBER_UPDATE (cambio de apodo o de rol)
  • GUILD_BAN_ADD, GUILD_BAN_REMOVE
  • GUILD_ROLE_CREATE, GUILD_ROLE_UPDATE, GUILD_ROLE_DELETE (se dispara cuando cambia el modelo de permisos de la instancia)
  • TYPING_START
  • VOICE_STATE_UPDATE (entrar, salir, silencio propio/del servidor, ensordecer)

Todavía no emitidos desde el autoalojado:

  • PRESENCE_UPDATE. Requiere un nuevo difusor de presencia en el autoalojado.
  • Eventos de mensajes de MD. El autoalojado no tiene MD entre servidores.
  • INTERACTION_CREATE. Las invocaciones de tus comandos en instancias autoalojadas todavía no se reenvían.

Diferencias conocidas de fidelidad

  • Silencio propio frente a silencio del servidor: la SFU autoalojada mantiene un único bit de silencio por participante en lugar de separar self_mute de mute como Discord. VOICE_STATE_UPDATE refleja el mismo valor en ambos campos; quitar un silencio del servidor puede parecer que la persona también se ha quitado el silencio propio. Los bots que leen solo uno de los dos campos están bien; los bots con máquina de estados que los mezclan deberían preferir mute para los conmutadores de moderación.
  • Mover dispara dos eventos: el PATCH de Discord a voice-states/{uid} con un nuevo channel_id emite un único VOICE_STATE_UPDATE; en el autoalojado el movimiento se implementa como salir + volver a entrar, así que verás el channel_id de la persona pasar a null y después al canal nuevo. Trata las actualizaciones consecutivas de la misma persona en unos pocos cientos de milisegundos como un único movimiento.

Detectar el autoalojado

El objeto guild no lleva hoy un indicador de «autoalojado» (nos mantenemos idénticos byte a byte con Discord). Si tu bot necesita ramificar, la señal fiable es un 501 o 404 de alguno de los endpoints de arriba, con un cuerpo de error JSON como:

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

Si suficientes bots necesitan una detección más barata, añadiremos una entrada en features (por ejemplo "SELF_HOSTED") a la carga de la guild. Envía tu opinión desde la pestaña de soporte de tu aplicación si eso te ayudaría.

Errores

  • 502 Bad Gateway. La instancia autoalojada devolvió una respuesta mal formada. Poco frecuente; suele ser un desfase de versiones durante una actualización.
  • 503 Service Unavailable. El canal de control no está conectado ahora mismo. Reinténtalo con backoff.
  • 504 Gateway Timeout. La instancia no respondió en 12 s.

← Volver a la documentación