# Zapini API — Mensajes

**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**.

---

## Mensajes

### GET /messages

Listar mensajes con filtros.

**Parámetros de Consulta:**

| Campo | Tipo | Descripción |
|-------|------|-------------|
| instance_id | string | UUID de instancia |
| conversation_id | integer | ID de conversación |
| direction | string | Dirección (incoming, outgoing) |
| status | string | Estado (pending, sent, delivered, read, failed) |
| from | datetime | Fecha de inicio |
| to | datetime | Fecha de fin |
| search | string | Buscar en el cuerpo del mensaje |
| per_page | integer | Elementos por página (por defecto: 20) |

---

### POST /messages/send

Enviar un mensaje de texto.

**Parámetros:**

| Campo | Tipo | Requerido | Descripción |
|-------|------|-----------|-------------|
| instance_id | string | Sí | UUID de instancia |
| recipient | string | Sí | Número del destinatario (formato: +15551234567) |
| message | string | Sí | Contenido del mensaje (máx. 4096 caracteres) |
| schedule_at | datetime | No | Programar envío para fecha/hora específica |
| reply_to | string | No | UUID o ID del mensaje al que responder |

**Ejemplo de Solicitud:**

```bash
curl -X POST https://zapini.app/api/v1/messages/send \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "instance_id": "550e8400-e29b-41d4-a716-446655440000",
    "recipient": "+15551234567",
    "message": "Hello! This is a test message."
  }'
```

**Respuesta:**

```json
{
  "success": true,
  "message": "Message added to queue",
  "data": {
    "uuid": "660e8400-e29b-41d4-a716-446655440001",
    "status": "pending",
    "scheduled_at": null,
    "delay_seconds": 15,
    "remaining_quota": 449
  }
}
```

---

### POST /messages/send-media

Enviar un mensaje con multimedia.

**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 pública del archivo |
| media_type | string | Sí | Tipo (image, video, audio, document) |
| caption | string | No | Leyenda (máx. 4096 caracteres) |
| filename | string | No | Nombre del archivo (para documentos) |
| schedule_at | datetime | No | Programar envío |

**Ejemplo:**

```bash
curl -X POST https://zapini.app/api/v1/messages/send-media \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "instance_id": "550e8400-e29b-41d4-a716-446655440000",
    "recipient": "+15551234567",
    "media_url": "https://example.com/image.jpg",
    "media_type": "image",
    "caption": "Check out this image!"
  }'
```

---

### GET /messages/{uuid}

Retorna detalles del mensaje.

---

### GET /messages/{uuid}/status

Retorna solo el estado del mensaje.

**Respuesta:**

```json
{
  "success": true,
  "data": {
    "uuid": "660e8400-e29b-41d4-a716-446655440001",
    "status": "delivered",
    "sent_at": "2025-01-15T10:30:00Z",
    "delivered_at": "2025-01-15T10:30:05Z",
    "read_at": null,
    "error_message": null,
    "retry_count": 0
  }
}
```

---

### PATCH /messages/{uuid}/edit

Editar un mensaje enviado.

**Parámetros:**

| Campo | Tipo | Requerido | Descripción |
|-------|------|-----------|-------------|
| message | string | Sí | Nuevo contenido del mensaje |

**Notas:**
- Solo se pueden editar mensajes salientes
- El mensaje debe tener estado sent, delivered o read

---

### DELETE /messages/{uuid}

Eliminar un mensaje.

**Notas:**
- Solo se pueden eliminar mensajes salientes
- El mensaje también será eliminado del WhatsApp del destinatario

---

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

Agregar una reacción a un mensaje.

**Parámetros:**

| Campo | Tipo | Requerido | Descripción |
|-------|------|-----------|-------------|
| emoji | string | Sí | Emoji de reacción |

---

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

Eliminar reacción de un mensaje.

---

### GET /messages/{uuid}/reactions

Listar todas las reacciones de un mensaje.

---

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