Discord

La integracion con Discord conecta tu servidor de Discord con Almirant para ejecutar comandos de agentes, recibir notificaciones de eventos del proyecto y controlar sesiones de trabajo directamente desde el chat.

Como funciona

Almirant se integra con Discord a traves de un bot que usa OAuth2 para conectarse a tu servidor. El bot puede:

• Ejecutar slash commands -- Comandos como /implement y /plan para lanzar trabajos de agente desde Discord.
• Enviar notificaciones -- Almirant notifica via Discord sobre eventos relevantes (work items, sprints, PRs, CI/CD).
• Controlar sesiones -- Botones interactivos para detener, pausar o responder a preguntas de los agentes.
• Crear threads automaticos -- Cada trabajo de agente crea un thread dedicado para seguir su progreso.

Configurar la integracion de Discord

1. Conectar via OAuth

A diferencia de otros bots, Discord usa OAuth2 para una conexion segura:

1. Accede a Configuracion > Integraciones > Discord.
2. Haz clic en Conectar Discord.
3. Discord te pedira que selecciones un servidor donde tienes permisos de administrador.
4. Autoriza los permisos solicitados (enviar mensajes, crear threads, usar slash commands).
5. Almirant registrara automaticamente los slash commands en tu servidor.

2. Configurar canal por defecto

Despues de conectar:

1. Accede a Configuracion > Integraciones > Discord.
2. Selecciona el canal por defecto donde el bot enviara notificaciones.
3. Guarda la configuracion.

3. Verificar la conexion

1. En la configuracion de Discord, haz clic en Enviar mensaje de prueba.
2. Verifica que el mensaje aparezca en el canal seleccionado.

Slash commands

El bot de Discord soporta slash commands para interactuar con Almirant:

Comando	Descripcion
/implement [work_item_id]	Lanza un trabajo de implementacion para el work item especificado
/plan [work_item_id]	Lanza un trabajo de planificacion para el work item especificado
/status	Muestra los trabajos activos (queued, running, waiting_for_input)
/status [job_id]	Muestra el estado detallado de un trabajo especifico

Opciones de comandos

Los comandos /implement y /plan aceptan opciones adicionales:

Opcion	Descripcion
work_item_id	(Requerido) El ID del work item (ej: A-123)
provider	(Opcional) El proveedor de agente: claude-code, codex, o zipu

Ejemplo de uso

/implement work_item_id:A-1189
/implement work_item_id:A-1189 provider:claude-code
/plan work_item_id:A-1190
/status job_id:abc123-def456

Threads automaticos

Cuando ejecutas un slash command, el bot crea automaticamente un thread privado para ese trabajo:

• El nombre del thread indica el tipo de trabajo y el task ID
• Todos los mensajes de progreso del agente van al thread
• Los botones de control (Stop, Shutdown) aparecen en el thread
• El thread se archiva automaticamente despues de 24 horas de inactividad

Botones interactivos

Durante la ejecucion de un trabajo, el bot muestra botones para controlar la sesion:

Boton	Accion
Stop	Detiene el trabajo actual pero mantiene el estado
Shutdown	Detiene completamente y cierra la sesion

Cuando el agente tiene una pregunta, aparecen opciones como botones o menu de seleccion. Selecciona la opcion deseada para responder.

Notificaciones

Configura que eventos del proyecto quieres recibir como notificaciones en Discord:

Evento	Descripcion
Work item creado	Se crea un nuevo work item
Work item movido	Un work item cambia de columna en el board
Work item asignado	Un work item se asigna a alguien
Work item completado	Un work item se marca como done
Sprint iniciado/cerrado	Comienza o termina un sprint
Milestone completado	Se completa un milestone
PR abierto/merged	Se abre o mergea un pull request
CI fallido	Una build de CI falla
Trabajo de agente completado/fallido	Un trabajo de agente termina

Para configurar las notificaciones:

1. Accede a Configuracion > Integraciones > Discord.
2. Haz clic en Configurar notificaciones.
3. Activa o desactiva los eventos deseados.
4. Guarda los cambios.

Vincular proyectos a canales

Puedes configurar canales especificos para diferentes proyectos:

1. Accede a la configuracion del proyecto.
2. En la seccion de Discord, selecciona el canal de destino.
3. Las notificaciones y threads de ese proyecto iran al canal configurado.

Si no hay canal especifico, se usa el canal por defecto de la organizacion.

Desconectar Discord

Para desconectar el bot:

1. Accede a Configuracion > Integraciones > Discord.
2. Haz clic en Desconectar.
3. Confirma la desconexion.

aviso

Desconectar el bot detendra los slash commands y notificaciones via Discord. Los trabajos en curso no se cancelaran automaticamente.

Para Developers

Arquitectura de la integracion

La integracion de Discord se compone de dos rutas principales:

• OAuth routes (/api/integrations/discord): Maneja el flujo OAuth2, gestion de conexiones, canales y preferencias de notificacion.
• Interactions webhook (/webhooks/discord/interactions): Recibe y procesa slash commands, botones y menus de seleccion.

Flujo de OAuth

Usuario --> GET /authorize --> Discord OAuth --> GET /callback
                                                      |
                                    +------------ Token exchange
                                    |
                            Create connection + Register slash commands

Flujo de interacciones

Discord --> POST /webhooks/discord/interactions --> Verify signature
                                                         |
                              +--------------------------+
                              |           |              |
                            PING     Command        Component
                              |           |              |
                           PONG    Queue job      Process action

Slash commands registrados

Los comandos se registran automaticamente en el guild durante OAuth:

• implement: Lanza trabajo de implementacion
• plan: Lanza trabajo de planificacion
• status: Consulta estado de trabajos

Verificacion de firma

Todas las interacciones se verifican usando Ed25519 con la clave publica de Discord (DISCORD_PUBLIC_KEY). Esto asegura que los requests provienen de Discord.

Variables de entorno

Variable	Descripcion
DISCORD_CLIENT_ID	ID de la aplicacion de Discord
DISCORD_CLIENT_SECRET	Secret de la aplicacion
DISCORD_PUBLIC_KEY	Clave publica para verificar firmas
DISCORD_BOT_TOKEN	Token del bot para enviar mensajes
DISCORD_APPLICATION_ID	ID de la aplicacion (para slash commands)
DISCORD_OAUTH_REDIRECT_URI	URI de callback OAuth