# API pública

Esta documentación cubre los dos métodos públicos disponibles para integraciones externas: enviar mensajes y escuchar eventos en tiempo real por Socket.IO.

## Resumen rápido

- Autenticación: `Authorization: Bearer <apiKey>`.
- Enviar mensaje: `POST /api/public/messages/send` con `target`.
- Bootstrap realtime: `GET /api/public/socket`.
- Conectar realtime: `io({ path: "/api/socketio", auth: { apiKey } })`.

## Métodos públicos

La API pública expone exactamente dos métodos HTTP: uno para enviar mensajes y otro para preparar la conexión realtime pública.

### `POST /api/public/messages/send`

Envía un mensaje desde una integración externa a un número o chatId.

- **Alcance**: Público
- **Cabeceras**:
  - `Authorization: Bearer <apiKey>`
  - `Content-Type: application/json`
- **Body**:

```json
{
  "target": "string",
  "message": "string"
}
```

- **Respuesta esperada**:

```json
{
  "ok": true,
  "message": {
    "id": "message_id",
    "chatId": "12345@c.us"
  }
}
```

- **Notas**:
  - La API key debe pertenecer a la sesión elegida.
  - Para responder a grupos, reutiliza el `chatId` recibido en eventos como `message:create` y envíalo como `target`.

### `GET /api/public/socket`

Valida la API key y deja listo el servidor Socket.IO público.

- **Alcance**: Público
- **Cabeceras**:
  - `Authorization: Bearer <apiKey>`
- **Respuesta esperada**:

```json
{
  "ok": true,
  "sessionId": "session_id"
}
```

- **Notas**:
  - Luego conecta con `socket.io-client` usando `path: "/api/socketio"` y `auth.apiKey`.
  - El canal realtime emite `ready` al autenticar y sincroniza mensajes entrantes y salientes.

## Socket.IO público

La conexión realtime pública se realiza con `io({ path: "/api/socketio", auth: { apiKey } })`. Al autenticarse emite `ready` y sincroniza mensajes entrantes y salientes.

### `ready`

Se emite apenas la API key fue validada correctamente.

- **Alcance**: Público
- **Respuesta esperada**:

```json
{
  "ok": true,
  "sessionId": "session_id"
}
```

- **Notas**:
  - Este evento confirma que el socket público quedó autenticado para la sesión elegida.

### `message:create`

Se emite al persistir un mensaje entrante o saliente. Incluye el nombre y el teléfono del remitente cuando están disponibles.

- **Alcance**: Público
- **Respuesta esperada**:

```json
{
  "id": "message_id",
  "sessionId": "session_id",
  "chatId": "12345@c.us",
  "sender": "them",
  "senderName": "Maria",
  "senderPhone": "+595987654321",
  "text": "Hola",
  "sentAt": "2026-04-17T00:00:00.000Z"
}
```

- **Notas**:
  - El campo `senderPhone` se agrega para identificar el remitente desde el evento Socket.IO.
  - Cuando el mensaje pertenece a un grupo, `chatId` puede terminar en `@g.us` y debe reutilizarse como `target` al responder.

### `message:update`

Se emite cuando cambia el estado, contenido o metadata de un mensaje ya persistido.

- **Alcance**: Público
- **Respuesta esperada**:

```json
{
  "id": "message_id",
  "sessionId": "session_id",
  "chatId": "12345@c.us",
  "deliveryStatus": "read"
}
```


### `chat:update`

Se emite cuando cambia el resumen del chat, incluyendo último mensaje y no leídos.

- **Alcance**: Público
- **Respuesta esperada**:

```json
{
  "sessionId": "session_id",
  "chat": {
    "id": "12345@c.us",
    "name": "Maria",
    "unreadCount": 1
  }
}
```


### `message:delete`

Se emite cuando un mensaje se elimina para mí o para todos.

- **Alcance**: Público
- **Respuesta esperada**:

```json
{
  "sessionId": "session_id",
  "chatId": "12345@c.us",
  "messageId": "message_id",
  "scope": "everyone"
}
```


## Errores

Las rutas públicas devuelven JSON con la forma `{ "error": "mensaje" }` cuando la API key es inválida, falta la cabecera `Authorization` o el body/query no pasa la validación.
Los status más comunes son `400`, `401` y `500`.

## Versión HTML

La página pública equivalente está en `/tutorial`.