# Zapini API — Messages

**Version:** 1.2.0
**Base URL:** `https://zapini.app/api/v1`

---

## Authentication

All endpoints require a Bearer Token:

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

Generate API tokens in your admin panel under **API Docs → Manage Tokens**.

---

## Messages

### GET /messages

List messages with filters.

**Query Parameters:**

| Field | Type | Description |
|-------|------|-------------|
| instance_id | string | Instance UUID |
| conversation_id | integer | Conversation ID |
| direction | string | Direction (incoming, outgoing) |
| status | string | Status (pending, sent, delivered, read, failed) |
| from | datetime | Start date |
| to | datetime | End date |
| search | string | Search in message body |
| per_page | integer | Items per page (default: 20) |

---

### POST /messages/send

Send a text message.

**Parameters:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| instance_id | string | Yes | Instance UUID |
| recipient | string | Yes | Recipient number (format: +15551234567) |
| message | string | Yes | Message content (max 4096 chars) |
| schedule_at | datetime | No | Schedule send for specific date/time |
| reply_to | string | No | UUID or ID of message to reply to |

**Example Request:**

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

**Response:**

```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

Send a message with media.

**Parameters:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| instance_id | string | Yes | Instance UUID |
| recipient | string | Yes | Recipient number |
| media_url | string | Yes | Public URL of the file |
| media_type | string | Yes | Type (image, video, audio, document) |
| caption | string | No | Caption (max 4096 chars) |
| filename | string | No | Filename (for documents) |
| schedule_at | datetime | No | Schedule send |

**Example:**

```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}

Returns message details.

---

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

Returns only the message status.

**Response:**

```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

Edit a sent message.

**Parameters:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| message | string | Yes | New message content |

**Notes:**
- Only outgoing messages can be edited
- Message must have status sent, delivered or read

---

### DELETE /messages/{uuid}

Delete a message.

**Notes:**
- Only outgoing messages can be deleted
- Message will also be deleted from recipient's WhatsApp

---

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

Add a reaction to a message.

**Parameters:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| emoji | string | Yes | Reaction emoji |

---

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

Remove reaction from a message.

---

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

List all reactions for a message.

---

*Generated by Zapini — https://zapini.app*