# Zapini API — Chat API

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

---

## Chat API (UI-Optimized)

The Chat API provides endpoints optimized for building WhatsApp-like chat interfaces. Returns pre-formatted data with resolved @mentions, grouped reactions, and alignment helpers.

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

### Key Features

| Field | Description |
|-------|-------------|
| `formatted_body` | Message text with @mentions resolved to names (HTML) |
| `is_from_me` | Boolean for easy message alignment |
| `grouped_reactions` | Reactions grouped by emoji with counts |
| `mentioned_jids` | Array of mentioned WhatsApp JIDs |
| `tags` | Conversation tags included |

---

### GET /chat/conversations

List conversations optimized for chat UI.

**Query Parameters:**

| Field | Type | Description |
|-------|------|-------------|
| instance_id | string | Filter by instance UUID |
| search | string | Search by name or number |
| unread | boolean | Only unread conversations |
| per_page | integer | Items per page |

**Response:**

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

Get messages with formatted body and grouped reactions.

**Query Parameters:**

| Field | Type | Description |
|-------|------|-------------|
| before_id | integer | Messages before this ID |
| after_id | integer | Messages after this ID |
| limit | integer | Message limit (default: 50) |

**Response:**

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

Send a text message with chat-optimized response.

**Parameters:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| instance_id | string | Yes | Instance UUID |
| recipient | string | Yes | Recipient number |
| message | string | Yes | Message content |
| reply_to | string | No | Message UUID to reply |

---

### POST /chat/send-media

Send media with chat-optimized response.

**Parameters:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| instance_id | string | Yes | Instance UUID |
| recipient | string | Yes | Recipient number |
| media_url | string | Yes | Media file URL |
| media_type | string | Yes | Type (image, video, audio, document) |
| caption | string | No | Caption |

---

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

Edit a sent message.

---

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

Delete a sent message.

---

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

Add emoji reaction.

**Parameters:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| emoji | string | Yes | Emoji to react |

---

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

Remove reaction.

---

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

Mark conversation as read.

---

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

Archive conversation.

---

### Alternative: ?format=chat

Use standard endpoints with `?format=chat` parameter:

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

---

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