API del webhook

La API de jaleo-api expone los siguientes endpoints:

Endpoints

GET `/`

Pagina de inicio (landing page). Muestra informacion sobre Jaleo con un enlace para anadir al bot al grupo de WhatsApp.

GET `/login?groupId=X`

Inicia el flujo de autorizacion OAuth con Spotify. Redirige al usuario a la pagina de login de Spotify.

| Parametro | Tipo | Descripcion | |-----------|------|-------------| | 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 autorizacion y lo intercambia por access_token y refresh_token, que se guardan en la base de datos asociados al groupId.

| Parametro | Tipo | Descripcion | |-----------|------|-------------| | code | string | Codigo de autorizacion de Spotify | | state | string | ID del grupo de WhatsApp (se recibe del paso anterior) |

Respuesta exitosa: Pagina HTML de confirmacion con lista de comandos disponibles.

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

El endpoint principal. Ejecuta una accion sobre la reproduccion de Spotify del grupo.

| Parametro | Tipo | Requerido | Descripcion | |-----------|------|-----------|-------------| | action | string | Si | La accion 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

| Accion | Query | Descripcion | Ejemplo | |--------|-------|-------------|---------| | play | track:CANCION+artist:ARTISTA | Reproduce una cancion | ?action=play&query=track:Despacito+artist:Luis+Fonsi&groupId=120363...@g.us | | queue | track:CANCION+artist:ARTISTA | Anade a la cola | ?action=queue&query=track:Bad+Bunny&groupId=120363...@g.us | | pause | (vacio) | Pausa la reproduccion | ?action=pause&groupId=120363...@g.us | | resume | (vacio) | Reanuda la reproduccion | ?action=resume&groupId=120363...@g.us | | skip | (vacio) | Salta a la siguiente cancion | ?action=skip&groupId=120363...@g.us | | now_playing | (vacio) | Informacion de la cancion 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 numeros: 120363407704072969 — Se le anade automaticamente @g.us
Completo: 120363407704072969@g.us — Se usa tal cual

Respuestas

Exitosa (ejemplo con play):

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

Exitosa (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