Cómo funciona

Flujo de una interacción

Cuando alguien escribe “pon Rosalía” en el grupo:

1. WhatsApp recibe el mensaje y lo envía a OpenClaw
2. OpenClaw procesa el mensaje con el modelo de lenguaje (por ejemplo, DeepSeek V4 Flash)
3. El modelo interpreta la intención: action: play, query: Rosalía
4. OpenClaw hace una petición webfetch GET a https://tudominio.com/webhook?action=play&query=Rosalia&groupId=120363...@g.us&t=1716000000
5. jaleo-api recibe la petición:
   • Busca el token de Spotify del grupo en la base de datos SQLite
   • Si el token ha expirado, lo renueva automáticamente con el refresh token
   • Si no hay token, devuelve un error con el enlace de vinculación
   • Si hay token válido, llama a la Spotify Web API
6. Spotify API busca “Rosalía”, reproduce el primer resultado
7. jaleo-api devuelve { status: "OK", track: "SAOKO" }
8. OpenClaw recibe la respuesta y genera un mensaje en lenguaje natural
9. El bot responde en el grupo: “SAOKO de Rosalía, dando”

Flujo de vinculación (OAuth)

La primera vez que un grupo intenta usar el bot, no tiene una cuenta de Spotify vinculada. El flujo es:

1. Alguien escribe “pon música” en el grupo
2. OpenClaw llama al webhook - jaleo-api responde con USUARIO_NO_VINCULADO y un enlace
3. OpenClaw responde en el grupo: “Vincula tu Spotify aquí: https://tudominio.com/login?groupId=120363…”
4. La persona con Spotify Premium toca el enlace
5. jaleo-api redirige a la página de autorización de Spotify
6. La persona autoriza (scopes: user-modify-playback-state, user-read-playback-state, user-read-currently-playing)
7. Spotify redirige a https://tudominio.com/callback?code=xxx&state=120363...
8. jaleo-api intercambia el code por un access_token y refresh_token
9. Se guardan en la base de datos SQLite asociados al groupId
10. Se muestra la página de confirmación con los comandos disponibles

A partir de este momento, cualquier persona del grupo puede controlar la reproducción.

Las tres capas

Capa de usuario

• WhatsApp Grupo - Donde los usuarios escriben mensajes
• Navegador Web Mobile - Donde se hace la vinculación OAuth con Spotify

Capa de intermediación

• OpenClaw - Bot + modelo de lenguaje. Lee los mensajes, interpreta intenciones y llama al webhook. Se configura con archivos de personalidad (SOUL.md, AGENTS.md, TOOLS.md, IDENTITY.md).
• jaleo-api - Servidor Express en Node.js. Expone el webhook, gestiona los tokens de Spotify y la base de datos SQLite.

Capa de servicios externos

• Spotify Web API - /v1/me/player/play, /v1/me/player/queue, /v1/me/player/pause, /v1/me/player/volume, /v1/me/player/next, /v1/me/player/currently-playing, /v1/search, /authorize

Auto-renovación de tokens

Los tokens de acceso de Spotify expiran cada hora. jaleo-api los renueva automáticamente:

1. Cada vez que llega una petición al webhook, verifica si el access token es válido
2. Si ha expirado (error 401), usa el refresh token para obtener uno nuevo
3. Guarda el nuevo access token en la base de datos
4. Continúa con la petición original

Esto significa que la vinculación solo se hace una vez. Después, todo es automático.