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):

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

---

## Setup

```bash
npm install
```

## Development

```bash
npm run dev
```

## Production

```bash
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:**
```bash
curl -X GET "https://whatsapp.nucleoriofrio.com/api/instances" \
  -H "Authorization: Bearer <API_KEY>"
```

**Ejemplo - Crear instancia:**
```bash
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:**
```bash
curl -X GET "https://whatsapp.nucleoriofrio.com/api/messages/{instanceId}/chats" \
  -H "Authorization: Bearer <API_KEY>"
```

**Respuesta:**
```json
[
  {
    "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:**
```bash
curl -X GET "https://whatsapp.nucleoriofrio.com/api/messages/{instanceId}/{chatId}" \
  -H "Authorization: Bearer <API_KEY>"
```

**Ejemplo - Paginación con limit/offset:**
```bash
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):**
```bash
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:**
```json
[
  {
    "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:**
```bash
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:**
```json
{
  "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:**
```json
{
  "messageId": "3EB0A1B2C3D4E5F6",
  "emoji": "👍"
}
```

**Ejemplo - Agregar reacción:**
```bash
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:**
```bash
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:**
```json
{
  "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