whatsappNucleo/README.md

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

Todos los endpoints requieren autenticación mediante API Key:

Authorization: Bearer <NUXT_MASTER_API_KEY>

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"}'

Chats y Contactos

Método	Endpoint	Descripción
GET	/api/messages/:instanceId/chats	Listar todos los chats
POST	/api/messages/:instanceId/new-chat	Crear nuevo chat

Ejemplo - Listar chats:

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

Respuesta:

[
  {
    "id": "abc123",
    "jid": "5491155551234@s.whatsapp.net",
    "name": "Juan Pérez",
    "isGroup": false,
    "unreadCount": 2,
    "lastMessageAt": "2025-01-15T10:30:00Z"
  }
]

Mensajes

Método	Endpoint	Descripción
GET	/api/messages/:instanceId/:chatId	Obtener mensajes del chat
POST	/api/messages/send	Enviar mensaje (simple)
POST	/api/messages/:instanceId/:chatId/send	Enviar mensaje (avanzado)

Ejemplo - Obtener mensajes:

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

Ejemplo - Enviar mensaje de texto:

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

Ejemplo - Enviar imagen:

curl -X POST "https://whatsapp.nucleoriofrio.com/api/messages/{instanceId}/{chatId}/send" \
  -H "Authorization: Bearer <API_KEY>" \
  -F "file=@imagen.jpg" \
  -F "caption=Descripción de la imagen"

Ejemplo - Enviar documento:

curl -X POST "https://whatsapp.nucleoriofrio.com/api/messages/{instanceId}/{chatId}/send" \
  -H "Authorization: Bearer <API_KEY>" \
  -F "file=@documento.pdf" \
  -F "caption=Reporte mensual"

Ejemplo - Enviar contacto:

curl -X POST "https://whatsapp.nucleoriofrio.com/api/messages/{instanceId}/{chatId}/send" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "contact",
    "contacts": [{
      "displayName": "Juan Pérez",
      "phoneNumber": "+5491155551234"
    }]
  }'

Ejemplo - Enviar encuesta:

curl -X POST "https://whatsapp.nucleoriofrio.com/api/messages/{instanceId}/{chatId}/send" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "poll",
    "name": "¿Qué día prefieres?",
    "options": ["Lunes", "Martes", "Miércoles"],
    "selectableCount": 1
  }'

Reacciones

Ejemplo - Reaccionar a mensaje:

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": "👍"
  }'

Quitar reacción: enviar emoji como string vacío ""

Formato de Destinatarios (JID)

• Contacto individual: 5491155551234@s.whatsapp.net (código país sin +)
• Grupo: 123456789012345678@g.us

Tipos de Mensaje Soportados

Tipo	Descripción
text	Mensaje de texto
image	Imagen con caption opcional
video	Video con caption opcional
audio	Audio o nota de voz
document	Documento/archivo
sticker	Sticker
contact	Tarjeta de contacto
poll	Encuesta (2-12 opciones)
event	Evento con fecha/ubicación

Límites de Archivos

Tipo	Tamaño Máximo
Imagen	16 MB
Video	64 MB
Audio	16 MB
Documento	100 MB
Sticker	500 KB

---

Stack

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