WhatsApp Nucleo

Sistema de gestión centralizada de múltiples instancias de WhatsApp para Nucleo V3.

MCP Server para Claude Code

Agregar el MCP a tu proyecto (usa tu NUXT_MASTER_API_KEY):

claude mcp add --transport http whatsapp https://whatsapp.nucleoriofrio.com/api/mcp --header "Authorization: Bearer <NUXT_MASTER_API_KEY>"

---

Setup

npm install

Development

npm run dev

Production

npm run build
node .output/server/index.mjs

---

API REST

Autenticación

API Externa (servicios, bots, agentes):

Authorization: Bearer <NUXT_MASTER_API_KEY>

Resumen de Endpoints

Endpoint	Descripción
POST /api/messages/send	Enviar mensaje de texto
GET /api/instances	Listar instancias
GET /api/messages/:instanceId/chats	Listar chats/contactos
GET /api/messages/:instanceId/:chatId	Obtener mensajes de un chat
POST /api/messages/:instanceId/react	Reaccionar a un mensaje

Instancias

Método	Endpoint	Descripción
GET	/api/instances	Listar todas las instancias
POST	/api/instances	Crear nueva instancia
GET	/api/instances/:id	Obtener detalles de instancia
GET	/api/instances/:id/qr	Obtener código QR
POST	/api/instances/:id/connect	Conectar instancia
POST	/api/instances/:id/disconnect	Desconectar instancia
DELETE	/api/instances/:id	Eliminar instancia

Ejemplo - Listar instancias:

curl -X GET "https://whatsapp.nucleoriofrio.com/api/instances" \
  -H "Authorization: Bearer <API_KEY>"

Ejemplo - Crear instancia:

curl -X POST "https://whatsapp.nucleoriofrio.com/api/instances" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Mi WhatsApp"}'

Obtener Lista de Chats/Contactos

GET /api/messages/:instanceId/chats

Retorna todos los chats (contactos individuales y grupos) de una instancia, ordenados por última actividad.

Ejemplo:

curl -X GET "https://whatsapp.nucleoriofrio.com/api/messages/{instanceId}/chats" \
  -H "Authorization: Bearer <API_KEY>"

Respuesta:

[
  {
    "id": "chat_abc123",
    "jid": "5491155551234@s.whatsapp.net",
    "name": "Juan Pérez",
    "isGroup": false,
    "unreadCount": 2,
    "lastMessageAt": "2025-01-15T10:30:00Z",
    "lastMessage": "Hola, ¿cómo estás?",
    "lastMessageType": "text"
  },
  {
    "id": "chat_xyz789",
    "jid": "120363123456789012@g.us",
    "name": "Grupo de Trabajo",
    "isGroup": true,
    "unreadCount": 0,
    "lastMessageAt": "2025-01-15T09:00:00Z",
    "lastMessage": "Reunión a las 3pm",
    "lastMessageType": "text"
  }
]

Campos de respuesta:

Campo	Tipo	Descripción
id	string	ID interno del chat (usar en otros endpoints)
jid	string	JID de WhatsApp del contacto/grupo
name	string	Nombre del contacto o grupo
isGroup	boolean	true si es un grupo
unreadCount	number	Cantidad de mensajes no leídos
lastMessageAt	string	Fecha ISO del último mensaje
lastMessage	string	Contenido del último mensaje
lastMessageType	string	Tipo del último mensaje

---

Obtener Mensajes de un Chat

GET /api/messages/:instanceId/:chatId

Obtiene los mensajes de un chat con soporte para paginación.

Parámetros de Query:

Parámetro	Tipo	Default	Descripción
limit	number	50	Cantidad de mensajes (máx: 100)
offset	number	0	Saltar N mensajes
before	string	-	Timestamp ISO para scroll infinito

Ejemplo - Obtener últimos 50 mensajes:

curl -X GET "https://whatsapp.nucleoriofrio.com/api/messages/{instanceId}/{chatId}" \
  -H "Authorization: Bearer <API_KEY>"

Ejemplo - Paginación con limit/offset:

curl -X GET "https://whatsapp.nucleoriofrio.com/api/messages/{instanceId}/{chatId}?limit=20&offset=40" \
  -H "Authorization: Bearer <API_KEY>"

Ejemplo - Scroll infinito (mensajes antes de fecha):

curl -X GET "https://whatsapp.nucleoriofrio.com/api/messages/{instanceId}/{chatId}?limit=20&before=2025-01-15T10:00:00Z" \
  -H "Authorization: Bearer <API_KEY>"

Respuesta:

[
  {
    "id": "msg_123",
    "messageId": "3EB0A1B2C3D4E5F6",
    "chatId": "chat_abc123",
    "fromJid": "5491155551234@s.whatsapp.net",
    "fromMe": false,
    "type": "text",
    "content": "Hola, ¿cómo estás?",
    "caption": null,
    "media": null,
    "timestamp": "2025-01-15T10:30:00Z",
    "status": "read",
    "pushName": "Juan",
    "isGroup": false
  },
  {
    "id": "msg_124",
    "messageId": "3EB0A1B2C3D4E5F7",
    "chatId": "chat_abc123",
    "fromJid": "me",
    "fromMe": true,
    "type": "image",
    "content": null,
    "caption": "Mira esta foto",
    "media": {
      "mimetype": "image/jpeg",
      "filesize": 245000,
      "width": 1920,
      "height": 1080,
      "thumbnail": "base64..."
    },
    "timestamp": "2025-01-15T10:31:00Z",
    "status": "delivered",
    "isGroup": false
  }
]

Campos de respuesta por tipo:

Campo	Descripción
messageId	ID de WhatsApp (usar para reaccionar o citar)
fromMe	true si lo envié yo
type	text, image, video, audio, document, sticker, contact, location, poll, event
content	Texto del mensaje
caption	Caption de media
media	Info de archivo (mimetype, filesize, thumbnail, etc.)
poll	Datos de encuesta (name, options, selectableCount)
event	Datos de evento (name, startDate, location)
quoted	Mensaje citado (id, content, type)
pushName	Nombre del remitente
participant	JID del participante (en grupos)

---

Enviar Mensajes

POST /api/messages/send

Este es el endpoint principal para enviar mensajes desde servicios externos. Solo requiere el número de teléfono, no necesitas buscar el chatId previamente.

Parámetros:

Campo	Requerido	Descripción
instanceId	Sí	ID de la instancia de WhatsApp
to	Sí	Número de teléfono (con o sin código país)
message	Sí	Texto del mensaje

Ejemplo:

curl -X POST "https://whatsapp.nucleoriofrio.com/api/messages/send" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceId": "4b57e897-f29b-4562-bd41-9a6fa32d584b",
    "to": "5491155551234",
    "message": "Hola! Este es un mensaje de texto"
  }'

Respuesta:

{
  "success": true,
  "messageId": "3EB06791F557866FDA1823",
  "to": "5491155551234@s.whatsapp.net"
}

Nota: El número se formatea automáticamente a JID. Puedes enviar 5491155551234 o +54 9 11 5555-1234, ambos funcionan.

---

Reaccionar a Mensajes

POST /api/messages/:instanceId/react

Envía una reacción (emoji) a un mensaje existente.

Body:

{
  "messageId": "3EB0A1B2C3D4E5F6",
  "emoji": "👍"
}

Ejemplo - Agregar reacción:

curl -X POST "https://whatsapp.nucleoriofrio.com/api/messages/{instanceId}/react" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"messageId": "3EB0A1B2C3D4E5F6", "emoji": "👍"}'

Ejemplo - Quitar reacción:

curl -X POST "https://whatsapp.nucleoriofrio.com/api/messages/{instanceId}/react" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"messageId": "3EB0A1B2C3D4E5F6", "emoji": ""}'

Emojis comunes:

Emoji	Significado
👍	Me gusta
❤️	Amor
😂	Risa
😮	Sorpresa
😢	Tristeza
🙏	Gracias

Respuesta:

{
  "success": true,
  "messageId": "3EB0A1B2C3D4E5F6",
  "emoji": "👍"
}

Nota: El messageId se obtiene de la respuesta al obtener mensajes (GET /api/messages/:instanceId/:chatId)

---

Stack

• Frontend: Nuxt 3, Vue 3, Nuxt UI, TailwindCSS
• Backend: Nitro, PostgreSQL
• WhatsApp: Baileys v6.7.9
• Auth: Authentik + Traefik