# Zapini API — Chat API

**Versión:** 1.2.0
**Base URL:** `https://zapini.app/api/v1`

---

## Autenticación

Todos los endpoints requieren un Bearer Token:

```
Authorization: Bearer {your_token}
Accept: application/json
Content-Type: application/json
```

Genera tokens de API en el panel admin en **API Docs → Gestionar Tokens**.

---

## Chat API (Optimizado para UI)

La Chat API proporciona endpoints optimizados para construir interfaces de chat similares a WhatsApp. Devuelve datos pre-formateados con @menciones resueltas, reacciones agrupadas y helpers de alineación.

**Base URL:** `/api/v1/chat`

### Características Principales

| Campo | Descripción |
|-------|-------------|
| `formatted_body` | Texto del mensaje con @menciones resueltas a nombres (HTML) |
| `is_from_me` | Booleano para fácil alineación de mensajes |
| `grouped_reactions` | Reacciones agrupadas por emoji con conteos |
| `mentioned_jids` | Array de JIDs de WhatsApp mencionados |
| `tags` | Tags de conversación incluidas |

---

### GET /chat/conversations

Listar conversaciones optimizadas para UI de chat.

**Parámetros de Consulta:**

| Campo | Tipo | Descripción |
|-------|------|-------------|
| instance_id | string | Filtrar por UUID de instancia |
| search | string | Buscar por nombre o número |
| unread | boolean | Solo conversaciones no leídas |
| per_page | integer | Elementos por página |

**Respuesta:**

```json
{
  "success": true,
  "data": {
    "data": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440045",
        "contact_number": "5521999999999",
        "display_name": "John Doe",
        "profile_picture_url": "https://...",
        "last_message": "Hello!",
        "unread_count": 3,
        "tags": [{"id": "550e8400-e29b-41d4-a716-446655440001", "name": "VIP", "color": "#f59e0b"}],
        "instance": {"uuid": "abc-123", "status": "connected"}
      }
    ]
  }
}
```

---

### GET /chat/conversations/{uuid}/messages

Obtener mensajes con cuerpo formateado y reacciones agrupadas.

**Parámetros de Consulta:**

| Campo | Tipo | Descripción |
|-------|------|-------------|
| before_id | integer | Mensajes antes de este ID |
| after_id | integer | Mensajes después de este ID |
| limit | integer | Límite de mensajes (por defecto: 50) |

**Respuesta:**

```json
{
  "success": true,
  "data": {
    "messages": [
      {
        "id": 456,
        "direction": "incoming",
        "is_from_me": false,
        "message_body": "Hello @5521999999999!",
        "formatted_body": "Hello <span class=\"mention\">@John</span>!",
        "mentioned_jids": ["5521999999999@s.whatsapp.net"],
        "grouped_reactions": [
          {"emoji": "👍", "count": 2, "has_my_reaction": true}
        ]
      }
    ],
    "has_more": true
  }
}
```

---

### POST /chat/send

Enviar un mensaje de texto con respuesta optimizada para chat.

**Parámetros:**

| Campo | Tipo | Requerido | Descripción |
|-------|------|-----------|-------------|
| instance_id | string | Sí | UUID de instancia |
| recipient | string | Sí | Número del destinatario |
| message | string | Sí | Contenido del mensaje |
| reply_to | string | No | UUID del mensaje al que responder |

---

### POST /chat/send-media

Enviar multimedia con respuesta optimizada para chat.

**Parámetros:**

| Campo | Tipo | Requerido | Descripción |
|-------|------|-----------|-------------|
| instance_id | string | Sí | UUID de instancia |
| recipient | string | Sí | Número del destinatario |
| media_url | string | Sí | URL del archivo de medios |
| media_type | string | Sí | Tipo (image, video, audio, document) |
| caption | string | No | Leyenda |

---

### PATCH /chat/messages/{uuid}

Editar un mensaje enviado.

---

### DELETE /chat/messages/{uuid}

Eliminar un mensaje enviado.

---

### POST /chat/messages/{uuid}/reaction

Agregar reacción emoji.

**Parámetros:**

| Campo | Tipo | Requerido | Descripción |
|-------|------|-----------|-------------|
| emoji | string | Sí | Emoji para reaccionar |

---

### DELETE /chat/messages/{uuid}/reaction

Eliminar reacción.

---

### POST /chat/conversations/{uuid}/mark-read

Marcar conversación como leída.

---

### POST /chat/conversations/{uuid}/archive

Archivar conversación.

---

### Alternativa: ?format=chat

Usa endpoints estándar con el parámetro `?format=chat`:

```bash
GET /api/v1/conversations?format=chat
GET /api/v1/conversations/550e8400-e29b-41d4-a716-446655440045/messages?format=chat
```

---

*Generado por Zapini — https://zapini.app*