Portal de Desarrolladores
Experimental La plataforma de bots y apps está en desarrollo activo. Los servidores autoalojados ejecutan bots, comandos de barra y componentes de mensaje, con algunas diferencias respecto a la nube. Consulta qué se admite.
← Documentación

Servidores autoalojados

Los clientes pueden ejecutar GameVox en su propio hardware, y tu bot funciona allí. La API en la nube reenvía las llamadas REST con formato de Discord por el canal de control del cliente, la instancia autoalojada las ejecuta contra su base de datos local y la respuesta vuelve por la misma vía. Los eventos de gateway viajan en sentido contrario. La mayoría de los endpoints son transparentes. Las diferencias se indican abajo.

Cómo funciona

Cuando tu bot llama a GET /guilds/{id} o POST /channels/{id}/messages, la API 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 persistente del canal de control que la instancia del cliente mantiene abierto con nosotros. El proceso autoalojado comprueba los permisos de tu bot frente a sus propios roles, ejecuta el manejador equivalente contra sus propias bases de datos SQLite y devuelve un envoltorio de respuesta, que reenviamos a tu bot.

El reenvío ocurre en la nube. 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 app-api.gamevox.com tanto si la guild está en la nube como si es autoalojada. Tu bot debe ser miembro del servidor autoalojado; de lo contrario, las llamadas responden 403.

Latencia

El tiempo de ida y vuelta está limitado por el enlace WAN del cliente 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 (90 s para un mensaje que incluye archivos, porque la instancia los descarga). Si la instancia no está conectada, tu bot recibe 503 de inmediato. Si está conectada pero no responde a tiempo, tu bot recibe 504.

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. Embeds, componentes, respuestas (message_reference), archivos adjuntos (multipart files[n] más payload_json) y encuestas. tts se acepta y se ignora.
  • Reacciones: añadir, quitar la propia, quitar la de un usuario, quitar todas, quitar todas las de un emoji, listar usuarios.
  • Fijados: fijar, desfijar, listar.
  • Escribiendo: POST /channels/{id}/typing.
  • Canales: obtener, modificar, eliminar, listar, crear (incluidos los canales de app), reordenar.
  • Excepciones de permisos por canal: PUT y DELETE .../channels/{id}/permissions/{oid}, y permission_overwrites en cada objeto de canal (y en CHANNEL_UPDATE). Leer permission_overwrites es, por ahora, exclusivo del autoalojado: los objetos de canal en la nube no incluyen el campo, y la API en la nube solo admite las escrituras PUT y DELETE. En un servidor autoalojado solo existen excepciones de rol: oid es un id de rol y type debe ser 0; una excepción de miembro (type: 1) se rechaza. La excepción cubre ver el canal, enviar mensajes, adjuntar archivos, añadir reacciones, conectar, hablar, usar la actividad de voz y transmitir. Un permiso concedido nunca otorga más de lo que el propio rol tiene permitido, así que un permiso concedido que el rol no tiene no se devuelve. Un canal sin excepciones devuelve una lista vacía.
  • 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, añadir, quitar.
  • Roles: listar, obtener, crear, modificar (incluido color), 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, entradas de las acciones realizadas a través de la API de bots.
  • URL personalizada: GET (siempre la estructura vacía).
  • Estado de voz: GET (en vivo desde la SFU), PATCH con mute, deaf y channel_id (mover, o null para desconectar), en cualquier combinación. mute y deaf son los indicadores del servidor; self_mute y self_deaf son los del propio miembro.
  • Webhooks: CRUD completo y ejecución. Los registros de los webhooks viven en la nube; los mensajes ejecutados se escriben en el canal autoalojado y aparecen con el nombre del webhook.
  • Eventos programados: listar, crear, obtener, modificar, eliminar, listar las personas interesadas y fijar o quitar la confirmación de asistencia (RSVP) de un miembro, con las mismas formas que en la nube. La configuración de repetición se guarda, pero no se generan las siguientes ocurrencias de un evento recurrente.
  • Publicaciones de foro: iniciar una publicación (POST /channels/{forum}/threads), leerla y responder en ella. El mensaje inicial de una publicación está limitado a 10.000 caracteres (20.000 en la nube).
  • Comandos de barra: invocación, con los permisos comprobados contra los roles de la propia instancia. El registro es el mismo que en la nube.
  • Componentes de mensaje: botones, selectores de texto, modales y respuestas efímeras, incluidos los endpoints de callback de la interacción, de seguimiento y de respuesta original. Consulta Componentes de mensaje.

Qué devuelve 501 (aceptado, no implementado)

  • PATCH .../guilds/{id}/vanity-url. Los servidores autoalojados no tienen URL personalizada.

Los responde la nube, no la instancia

Estos endpoints tratan sobre cuentas de GameVox y no sobre un servidor concreto, así que la nube los responde para todos los bots. Los miembros de servidores autoalojados son cuentas normales de GameVox.

  • GET /users/{id} y GET /users/by-name/{name}.
  • GET /users/@me/guilds, que incluye los servidores autoalojados en los que está instalada tu app.
  • POST /users/@me/channels devuelve un canal de MD, pero enviarle mensajes todavía no está admitido, ni en la nube ni en servidores autoalojados.

Eventos del gateway

Las instancias autoalojadas publican eventos por la misma sesión de gateway que la nube. Sin un modelo de suscripción distinto. Los eventos de canal solo se entregan a los bots que pueden ver el canal, y los intents se aplican igual que en la nube.

Emitidos por las acciones de las personas en la instancia y por las propias llamadas REST de tu bot:

  • MESSAGE_CREATE, MESSAGE_UPDATE, MESSAGE_DELETE
  • MESSAGE_DELETE_BULK (también cuando una expulsión o un baneo elimina los mensajes del miembro)
  • 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 (cambios de nombre / descripción)
  • GUILD_MEMBER_ADD
  • GUILD_MEMBER_REMOVE (salida, expulsión, baneo, limpieza de invitados inactivos)
  • GUILD_MEMBER_UPDATE (cambio de rol, de nombre de usuario o de avatar)
  • GUILD_BAN_ADD
  • GUILD_ROLE_CREATE, GUILD_ROLE_UPDATE, GUILD_ROLE_DELETE (crear, renombrar, reordenar, cambios de color y de permisos)
  • GUILD_EMOJIS_UPDATE
  • TYPING_START
  • PRESENCE_UPDATE (requiere el intent GUILD_PRESENCES; solo cambios, sin una instantánea de los miembros que ya están en línea cuando te conectas)
  • VOICE_STATE_UPDATE (entrar, salir, mover, silencio y ensordecimiento propios y del servidor)
  • INTERACTION_CREATE (comandos de barra, clics en componentes y envíos de modales; los reenvía la nube)

Emitidos solo por los cambios que tu bot hace por REST:

  • GUILD_BAN_REMOVE (la instancia no tiene una acción para que las personas quiten un baneo)
  • MESSAGE_REACTION_REMOVE_ALL, MESSAGE_REACTION_REMOVE_EMOJI (la instancia no tiene esa acción para las personas)

No emitidos (tampoco en la nube):

  • THREAD_*, INVITE_*, GUILD_SCHEDULED_EVENT_*.

Diferencias conocidas de fidelidad

  • Mover entre canales de voz dispara dos eventos: el PATCH de Discord a voice-states/{uid} con un nuevo channel_id emite un único VOICE_STATE_UPDATE; en servidores autoalojados, 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. Un mute o deaf enviado junto con un movimiento se aplica cuando el miembro vuelve a entrar.
  • URLs de adjuntos: la url de un adjunto en un servidor autoalojado apunta a la instancia del cliente y requiere una sesión de miembro para descargarlo. Tu bot puede ver el nombre, el tamaño y el tipo del archivo, pero todavía no puede descargarlo. width, height y description no se conservan en servidores autoalojados.

Detectar autoalojamiento

El objeto guild no lleva hoy un indicador de “autoalojado” (nos mantenemos idénticos byte a byte con Discord). Si tu bot necesita actuar de forma distinta, la señal es un 501 de alguno de los endpoints de arriba, con el motivo de la instancia en el cuerpo de error JSON, como:

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

Un 404 ("Unknown resource") significa que falta el recurso, no que el servidor sea autoalojado. Si suficientes bots necesitan una detección más barata, añadiremos una entrada en features (por ejemplo "SELF_HOSTED") al payload del servidor. 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