Como funciona

Flujo de una interaccion

Cuando alguien escribe “pon Rosalia” en el grupo:

1. WhatsApp recibe el mensaje y lo envia a OpenClaw
2. OpenClaw procesa el mensaje con el modelo de lenguaje (por ejemplo, DeepSeek V4 Flash)
3. El modelo interpreta la intencion: accion: play, query: Rosalia
4. OpenClaw hace una peticion webfetch GET a https://tudominio.com/webhook?action=play&query=Rosalia&groupId=120363...@g.us&t=1716000000
5. jaleo-api recibe la peticion:
   • Busca el token de Spotify del grupo en la base de datos SQLite
   • Si el token ha expirado, lo renueva automaticamente con el refresh token
   • Si no hay token, devuelve un error con el enlace de vinculacion
   • Si hay token valido, llama a la Spotify Web API
6. Spotify API busca “Rosalia”, 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 Rosalia, dando”

Flujo de vinculacion (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 musica” 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 aqui: https://tudominio.com/login?groupId=120363…”
4. La persona con Spotify Premium toca el enlace
5. jaleo-api redirige a la pagina de autorizacion 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 pagina de confirmacion con los comandos disponibles

A partir de este momento, cualquier persona del grupo puede controlar la reproduccion.

Las tres capas

Capa de usuario

• WhatsApp Grupo — Donde los usuarios escriben mensajes
• Navegador Web Mobile — Donde se hace la vinculacion OAuth con Spotify

Capa de intermediacion

• 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-renovacion de tokens

Los tokens de acceso de Spotify expiran cada hora. jaleo-api los renueva automaticamente:

1. Cada vez que llega una peticion al webhook, verifica si el access token es valido
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. Continua con la peticion original

Esto significa que la vinculacion solo se hace una vez. Despues, todo es automatico.