API del webhook

La API de jaleo-api expone los siguientes endpoints:

Endpoints

GET `/`

página de inicio (landing page). Muestra información sobre Jaleo con un enlace para añadir al bot al grupo de WhatsApp.

GET `/login?groupId=X`

Inicia el flujo de autorización OAuth con Spotify. Redirige al usuario a la página de login de Spotify.

Parametro	Tipo	descripción
`groupId`	string	ID del grupo de WhatsApp (15-20 digitos)

El groupId se pasa como parametro state en el flujo de OAuth para que Spotify lo devuelva en el callback y podamos asociar los tokens al grupo correcto.

GET `/callback?code=X&state=X`

Callback de Spotify OAuth. Recibe el codigo de autorización y lo intercambia por access_token y refresh_token, que se guardan en la base de datos asociados al groupId.

Parametro	Tipo	descripción
`code`	string	Codigo de autorización de Spotify
`state`	string	ID del grupo de WhatsApp (se recibe del paso anterior)

Respuesta exitoso: página HTML de confirmación con lista de comandos disponibles.

GET/POST `/webhook?action=X&query=X&groupId=X`

El endpoint principal. Ejecuta una acción sobre la reproducción de Spotify del grupo.

Parametro	Tipo	Requerido	descripción
`action`	string	Si	La acción a ejecutar (ver tabla abajo)
`groupId`	string	Si	ID del grupo de WhatsApp
`query`	string	Depende	Termino de busqueda o nivel de volumen
`t`	number	Recomendado	Timestamp para evitar cache

acciones disponibles

acción	Query	descripción	Ejemplo
`play`	`track:canción+artist:ARTISTA`	Reproduce una canción	`?action=play&query=track:Despacito+artist:Luis+Fonsi&groupId=120363…@g.us`
`queue`	`track:canción+artist:ARTISTA`	añade a la cola	`?action=queue&query=track:Bad+Bunny&groupId=120363…@g.us`
`pause`	(vacio)	Pausa la reproducción	`?action=pause&groupId=120363…@g.us`
`resume`	(vacio)	Reanuda la reproducción	`?action=resume&groupId=120363…@g.us`
`skip`	(vacio)	Salta a la siguiente canción	`?action=skip&groupId=120363…@g.us`
`now_playing`	(vacio)	información de la canción actual	`?action=now_playing&groupId=120363…@g.us`
`volume`	Numero (0-100)	Ajusta el volumen	`?action=volume&query=50&groupId=120363…@g.us`

Formato del groupId

El groupId puede recibirlo en dos formatos:

solo números: 120363407704072969 - Se le añade automáticamente @g.us
Completo: 120363407704072969@g.us - Se usa tal cual

Respuestas

exitoso (ejemplo con play):

{
  "status": "OK",
  "track": "SAOKO"
}

exitoso (ejemplo con now_playing):

{
  "status": "OK",
  "info": "SAOKO de Rosalia"
}

Grupo no vinculado:

{
  "status": "ERROR",
  "error": "USUARIO_NO_VINCULADO",
  "link": "https://tudominio.com/login?groupId=120363...@g.us"
}

Error de Spotify (sin dispositivo activo):

{
  "error": "Error de Spotify (¿Dispositivo activo?)"
}

GET `/debug`

Muestra el estado de las vinculaciones (solo para desarrollo).

Respuesta:

{
  "groups": [
    { "groupId": "120363...@g.us", "linked": "LINKED" }
  ],
  "timestamp": "2026-05-28T12:00:00.000Z"
}

API del webhook

Endpoints

GET /

GET /login?groupId=X

GET /callback?code=X&state=X

GET/POST /webhook?action=X&query=X&groupId=X