Desarrollar bots de Sibrel

Crea tu primer bot

• Abre Ajustes → Bots → Crear bot. Tu anfitrión puede desactivar la creación de bots.
• Elige un nombre de usuario con a-z0-9_, de 2 a 32 caracteres. Guarda el token: solo se muestra una vez.
• Añade el bot en los ajustes de la comunidad y concede solo los permisos necesarios. La gestión requiere MANAGE_BOTS.
• Ejecuta el programa del bot en tu equipo o servidor. Una cuenta de bot no ejecuta código.
• Usa la dirección de la API del anfitrión que emitió el token.

Los bots actúan en los canales de las comunidades a las que se han unido. La API de bots no admite mensajes directos ni espacios públicos.

Autenticación y secretos

Authorization: Bearer <BOT_TOKEN>

Las acciones de bot requieren un token de bot. Crear o editar un bot, añadirlo a una comunidad y definir sus permisos requieren el token de cuenta del propietario o de un administrador. Mantén esas autorizaciones separadas.

Guarda los tokens en variables de entorno, nunca en código de navegador ni en Git. La base de datos del anfitrión guarda hashes de tokens. Revoca cualquier token filtrado y emite uno nuevo. La pasarela envía el token en la cadena de consulta, así que oculta las URL en los registros de los proxies inversos y de supervisión. Usa HTTPS/WSS.

Ejemplo mínimo funcional

Requiere Node.js 22+ con fetch y WebSocket integrados. Descargar ping-bot.en.mjs. El ejemplo registra /ping, responde en un canal y se reconecta tras una desconexión.

$env:SIBREL_API_URL = "https://api.example.org"
$env:SIBREL_BOT_TOKEN = "your-token"
node ./ping-bot.en.mjs

API REST de bots

POST /api/bots/messages
{
  "channel_id": 42,
  "content": "¡Hola desde el bot!",
  "reply_to_id": 123
}

Envío correcto: 201 { message }. No envíes Content-Type: application/json sin cuerpo: una solicitud JSON vacía puede devolver 400.

Gestionar bots y permisos

Los bots tienen su propia máscara de permisos por comunidad, no roles de miembro normales. Ver canales: 16384; enviar mensajes: 32768; voz: 65536. Estos tres permisos suman 114688. Los bots no obtienen acceso de administrador.

Comandos de barra

PUT /api/bots/commands
{ "commands": [
  { "name": "ping", "description": "Check the bot response", "options": [] },
  { "name": "echo", "description": "Repeat text", "options": [
    { "name": "text", "description": "Your text", "type": "string", "required": true }
  ] }
] }

Nombres: de 1 a 32 caracteres, a-z0-9_-. Hasta 100 comandos y 10 opciones por comando. Tipos: string, number, boolean, user, channel, role; hasta 25 choices. Descripciones de comando: 200 caracteres.

PUT sustituye toda la lista, así que envía siempre el conjunto completo. En message:create, una invocación detectada contiene command: {bot_id, name, options, args}. Comprueba bot_id para no responder a comandos de otro bot. Los comandos desactivados o desconocidos llegan como texto normal.

Elegir un miembro, un canal o un rol

Las opciones de tipo user, channel y role se eligen en una lista con búsqueda en lugar de escribirlas a mano. El bot recibe un token de mención en lugar de un nombre, así que renombrar un canal, un rol o un miembro nunca rompe una invocación ya enviada.

• La búsqueda abarca el nombre y, en el caso de los miembros, también los apodos y el identificador de inicio de sesión.
• Las palabras de servicio también funcionan: «voice» encuentra canales de voz, «role» encuentra roles y «text» encuentra canales de texto.
• Las coincidencias al inicio del nombre aparecen por encima de las demás.
• Se muestran ocho opciones como máximo; afina la búsqueda si falta la tuya.
• Intro elige la primera opción, las flechas mueven la selección, Esc vacía la búsqueda y Retroceso vuelve a la escritura normal.

El valor llega como token en command.options ({ "user": "<@42>" }) y en la misma posición en command.args. También se acepta un identificador sin formato, pero solo el token se muestra como mención en el texto de respuesta.

Pasarela y eventos

wss://api.example.org/api/bots/gateway?token=<BOT_TOKEN>

{ "type": "ready", "bot_id": 7, "guilds": [1, 2] }
{ "type": "ping" }
{ "type": "pong" }

Eventos: message:create, message:update, message:delete, reaction:add, reaction:remove, interaction. Los datos de los eventos de acción están en data; ready lleva bot_id y guilds en el primer nivel.

La cola de la conexión guarda 256 mensajes. Un desbordamiento genera message:drop; pueden perderse eventos anteriores. Implementa reconexiones con retardo, supervisión de pong y restauración del estado por REST. No supongas una entrega exactamente una vez.

Botones, embeds e interacciones

{
  "channel_id": 42,
  "embeds": [{ "title": "Prueba", "description": "Pulsa el botón", "color": 5793266 }],
  "components": [{ "type": 1, "components": [
    { "custom_id": "ping", "label": "Ping", "style": 1 }
  ] }]
}

Un botón tiene una etiqueta de hasta 80 caracteres y un custom_id único de hasta 100. Los botones de enlace usan una URL http/https en lugar de custom_id. Hasta 5 filas de 5 botones, 25 en total. Estilos 1 a 4: primary, secondary, success, danger. Se admiten disabled y emoji.

{ "type": "interaction-reply", "nonce": "from the event",
  "action": "ephemeral", "content": "¡Pong!" }

Responde en un plazo de 3 segundos. ephemeral solo lo ve quien hace clic; message publica en el canal; update edita el mensaje con el botón. Las respuestas efímeras permanecen en memoria hasta 15 minutos y desaparecen al reiniciar; no son un almacén secreto.

content: hasta 2000 caracteres; hasta 10 embeds con 6000 caracteres en total. Emoji personalizados: <:name:id>. Consulta también Webhooks para ver ejemplos de embeds.

Voz

POST /api/bots/voice/join devuelve channel_id, identity y livekit. Si LiveKit está configurado, usa el token y livekitUrl devueltos con un SDK de cliente compatible. Con livekit: null, el bot solo aparece en la lista de miembros y no transmite audio. La solicitud REST por sí sola no inicia la reproducción.

Errores y operación

Oculta los secretos en los registros, limita el acceso a las variables de entorno y no respondas a los propios mensajes del bot. Coordina la recogida de datos con los administradores y los usuarios, y define la conservación y la eliminación.

Canales de voz para bots

Un bot con el permiso independiente CREATE_VOICE_CHANNELS puede crear canales de voz mediante POST /api/bots/guilds/:guildId/channels. Estados: GET /api/bots/guilds/:guildId/voice-states. Solicitud de movimiento: POST /api/bots/guilds/:guildId/voice/move. Eliminar un canal vacío: DELETE /api/bots/channels/:channelId. El host comprueba permisos y límites; un token por sí solo no concede estas acciones.