Documentación para Desarrolladores

Crea bots de moderación, integraciones con webhooks, sistemas de música o herramientas comunitarias. La API de Larixy ofrece endpoints RESTful y un Gateway WebSocket para sincronización en tiempo real.

1. Autenticación

Para realizar peticiones a la API o conectar al Gateway necesitas un token de bot. Todas las llamadas deben incluir la cabecera HTTP Authorization.

HTTP Headers
Authorization: Bot MTA5NzI2Mjg4MjM1MjA4MzcyNg.xxxxxx.xxxxxx
Content-Type: application/json

2. Gateway WebSocket (Eventos en Tiempo Real)

El Gateway te permite escuchar eventos de servidores en vivo (mensajes nuevos, ingresos de usuarios, reacciones). Conéctate mediante WebSocket seguro a wss://larixy.xyz/gateway.

Payload de Identificación (Opcode 2 IDENTIFY):

identify.json
{
  "op": 2,
  "d": {
    "token": "Bot MTA5NzI2Mjg4MjM1MjA4MzcyNg.xxxxxx.xxxxxx",
    "capabilities": 0,
    "properties": {
      "os": "linux",
      "client": "larixy_bot"
    }
  }
}

Eventos de Dispatch (t):

Evento Cuándo se emite
READYAutenticación completada y sesión lista
MESSAGE_CREATESe envió un mensaje en un canal de texto
MESSAGE_UPDATEUn mensaje fue editado o se procesaron embeds
MESSAGE_DELETEUn mensaje fue eliminado
MESSAGE_DELETE_BULKBorrado masivo de mensajes
GUILD_MEMBER_ADDUn nuevo usuario ingresó a la comunidad
GUILD_MEMBER_REMOVEUn usuario abandonó o fue expulsado
VOICE_STATE_UPDATEEstado de voz actualizado (conectar, mutear, ensordecer)

3. Rich Embeds

Los Rich Embeds permiten formatear respuestas de bots con bordes de color personalizados, campos organizados en cuadrículas, autor, miniatura, imágenes y fecha.

Vista Previa de cómo se renderiza en Larixy:

LX
Larixy Sentinel

🛡️ Acción de Moderación: Advertencia Aplicada

Se detectó una infracción automática en el canal #general.

Usuario Infractor
@Lyxtem
Moderador
AutoMod v2
Sanción
Timeout (10 min)
Larixy Security Sentinel • Hoy a las 15:10

Petición HTTP para Enviar el Embed:

POST /api/v1/channels/{channel_id}/messages
{
  "content": "Notificación de moderación del servidor:",
  "embeds": [
    {
      "title": "🛡️ Acción de Moderación: Advertencia Aplicada",
      "description": "Se detectó una infracción automática en el canal #general.",
      "color": 5793266,
      "author": {
        "name": "Larixy Sentinel",
        "icon_url": "https://larixy.xyz/landing-assets/favicon.png"
      },
      "fields": [
        {
          "name": "Usuario Infractor",
          "value": "<@1572628823520837632>",
          "inline": true
        },
        {
          "name": "Moderador",
          "value": "AutoMod v2",
          "inline": true
        },
        {
          "name": "Sanción",
          "value": "Timeout (10 min)",
          "inline": true
        }
      ],
      "footer": {
        "text": "Larixy Security Sentinel"
      },
      "timestamp": "2026-11-19T15:10:00.000Z"
    }
  ]
}

4. Borrado Masivo (Bulk Delete)

Permite a bots de moderación eliminar de 2 a 100 mensajes simultáneamente (por ejemplo, para comandos como !clear 50).

POST /api/v1/channels/{channel_id}/messages/bulk-delete
{
  "message_ids": [
    "1572628823520837632",
    "1572628823520837633",
    "1572628823520837634"
  ]
}

5. Endpoints de Moderación

PATCH /api/v1/guilds/{guild_id}/members/{user_id}
Timeout / Silenciar

Deshabilita temporalmente la capacidad de un usuario para enviar mensajes y hablar.

{
  "communication_disabled_until": "2026-11-19T16:00:00.000Z"
}
PUT /api/v1/guilds/{guild_id}/bans/{user_id}
Banear Usuario

Expulsa al usuario y borra sus mensajes recientes de forma opcional.

{
  "delete_message_days": 1,
  "reason": "Spam continuo en canales comunitarios"
}

6. Ejemplos Completos de Bots

🐍 Bot de Moderación en Python (asyncio + aiohttp + websockets)

import asyncio
import json
import os
import aiohttp
import websockets

BOT_TOKEN = os.getenv("BOT_TOKEN")
API_BASE = "https://larixy.xyz/api/v1"
GATEWAY_URL = "wss://larixy.xyz/gateway"

headers = {
    "Authorization": f"Bot {BOT_TOKEN}",
    "Content-Type": "application/json"
}

async def send_embed(session, channel_id, title, description, color=5793266):
    payload = {
        "embeds": [{
            "title": title,
            "description": description,
            "color": color,
            "footer": {"text": "Larixy Python AutoMod"},
            "timestamp": "2026-11-19T15:00:00Z"
        }]
    }
    async with session.post(f"{API_BASE}/channels/{channel_id}/messages", json=payload, headers=headers) as resp:
        return await resp.json()

async def delete_message(session, channel_id, message_id):
    url = f"{API_BASE}/channels/{channel_id}/messages/{message_id}"
    async with session.delete(url, headers=headers) as resp:
        return resp.status == 204

async def run_bot():
    async with aiohttp.ClientSession() as session:
        async with websockets.connect(GATEWAY_URL) as ws:
            # 1. Esperar HELLO
            hello = json.loads(await ws.recv())
            heartbeat_ms = hello["d"]["heartbeat_interval"]

            # 2. Identificar al bot
            identify = {
                "op": 2,
                "d": {
                    "token": f"Bot {BOT_TOKEN}",
                    "capabilities": 0,
                    "properties": {"os": "linux", "client": "larixy_bot"}
                }
            }
            await ws.send(json.dumps(identify))
            print("Bot conectado y autenticado exitosamente en Larixy!")

            # Bucle de escucha de eventos
            while True:
                raw = await ws.recv()
                event = json.loads(raw)
                
                if event.get("t") == "MESSAGE_CREATE":
                    data = event["d"]
                    content = data.get("content", "")
                    channel_id = data["channel_id"]
                    msg_id = data["id"]
                    
                    # Evitar auto-respuestas
                    if data.get("author", {}).get("bot"):
                        continue

                    # Filtro de palabras prohibidas
                    if "discord.gg/" in content:
                        await delete_message(session, channel_id, msg_id)
                        await send_embed(
                            session, 
                            channel_id, 
                            "⚠️ Mensaje Eliminado", 
                            "No está permitido compartir invitaciones externas en este canal.",
                            color=15158332 # Rojo
                        )

if __name__ == "__main__":
    asyncio.run(run_bot())

⚡ Bot de Moderación en JavaScript (Node.js + ws)

import WebSocket from 'ws';

const BOT_TOKEN = process.env.BOT_TOKEN;
const API_BASE = 'https://larixy.xyz/api/v1';
const GATEWAY_URL = 'wss://larixy.xyz/gateway';

const ws = new WebSocket(GATEWAY_URL);

ws.on('open', () => {
  console.log('Conectado al Gateway de Larixy');
  ws.send(JSON.stringify({
    op: 2,
    d: {
      token: `Bot ${BOT_TOKEN}`,
      capabilities: 0,
      properties: { os: 'linux', client: 'larixy_js_bot' }
    }
  }));
});

ws.on('message', async (raw) => {
  const payload = JSON.parse(raw);

  if (payload.t === 'MESSAGE_CREATE') {
    const msg = payload.d;
    if (msg.author?.bot) return;

    // Comando !clear 
    if (msg.content.startsWith('!clear')) {
      const parts = msg.content.split(' ');
      const amount = parseInt(parts[1], 10) || 10;

      // Obtener mensajes recientes
      const fetchResp = await fetch(`${API_BASE}/channels/${msg.channel_id}/messages?limit=${amount}`, {
        headers: { 'Authorization': `Bot ${BOT_TOKEN}` }
      });
      const messages = await fetchResp.json();
      const messageIds = messages.map(m => m.id);

      // Borrado masivo
      await fetch(`${API_BASE}/channels/${msg.channel_id}/messages/bulk-delete`, {
        method: 'POST',
        headers: {
          'Authorization': `Bot ${BOT_TOKEN}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({ message_ids: messageIds })
      });
    }
  }
});