Introducción a la API

WhatsUY expone una API REST HTTP para integraciones externas. También envía webhooks salientes cuando ocurren eventos sobre las conversaciones (mensajes, status, datos, llamadas, suscripción).

📘 Fuente única de verdad: la documentación completa y viva está en api-documentation/ (carpeta hermana). Esta sección de whatsuy-doc es el resumen público navegable. El Swagger UI está disponible en /swagger del backend.

Stack técnico

Componente	Tecnología
Framework	NestJS 10 (Node.js + TypeScript)
Persistencia	MongoDB (Mongoose)
Autenticación	JWT (Authorization: Bearer <token>)
WebSockets / Realtime	Socket.IO interno para bots
Proveedores de chat	Baileys, Meta Cloud API, Messenger Graph API
IA / Bots	Bot v2 (Flow Editor), AIFlows, OpenAI-compatible, LiteLLM

URL base

http(s)://<host>:3000

Por defecto el backend escucha en el puerto 3000 (configurable vía env).

Convenciones

• Content-Type: application/json salvo indicación contraria.
• Fechas: UNIX epoch en segundos.
• ID de referencia: entero único.
• ID de chat: depende del proveedor:
  • Baileys: <phone>@s.whatsapp.net o @g.us
  • Meta Cloud API: <phone> sin sufijo
  • Messenger: <psid>@messenger
• ID de mensaje: string (formato depende del proveedor).

Autenticación

La mayoría de endpoints requieren JWT. Lo obtenés con POST /user/login y lo enviás en el header Authorization: Bearer <jwt>.

Los webhooks salientes hacia tu servicio no usan JWT: configurás tu propio secreto en headers desde el panel admin.

Endpoints públicos (sin JWT): callback de Meta, login, signup, payments, probe.

Endpoints principales

Recurso	Endpoints clave
Auth	POST /user/login, POST /user/signup, POST /user/reset
Users	GET /user/me, PATCH /user/:id, /user/permissions
References	POST /reference, GET /reference/list, GET /reference/:id
Sessions	POST /reference/session/start, /session/logout, /session/status
Chats	GET /chats/list, GET /chats/messages, POST /chats/send
Bots v2	POST /bot, PATCH /bot/:id, GET /bot/:id
AIFlows	POST /aiflow/project, POST /aiflow/flow, POST /aiflow/run
AIUsage	GET /aiusage/rollup, GET /aiusage/detail, GET /aiusage/missing-pricing
MCP	GET /whats-uy-mcp/functions, POST /whats-uy-mcp/execute
Webhooks	POST /references/hookconf, POST /references/registerWebHook

Detalle completo de cada endpoint en la documentación interna api-documentation/.