# Zapini API — Instances

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

---

## WhatsApp Instances

### GET /instances

List all WhatsApp instances.

**Query Parameters:**

| Field | Type | Description |
|-------|------|-------------|
| status | string | Filter by status (connected, disconnected, qr_ready, pending) |

**Response:**

```json
{
  "success": true,
  "data": {
    "instances": [
      {
        "uuid": "550e8400-e29b-41d4-a716-446655440000",
        "phone_number": "15551234567",
        "status": "connected",
        "connected": true,
        "messages_sent_today": 50,
        "remaining_quota": 450,
        "can_send_messages": true,
        "last_activity_at": "2025-01-15T10:30:00Z",
        "created_at": "2025-01-01T00:00:00Z"
      }
    ]
  }
}
```

---

### GET /instances/{uuid}

Returns instance details.

---

### GET /instances/{uuid}/qr

Get QR Code for WhatsApp connection.

**Response:**

```json
{
  "success": true,
  "data": {
    "status": "qr_ready",
    "qr_code": "data:image/png;base64,...",
    "qr_code_text": "2@...",
    "qr_generated_at": "2025-01-15T10:30:00Z",
    "qr_expired": false,
    "message": "QR code ready to scan"
  }
}
```

---

### GET /instances/{uuid}/status

Returns instance connection status.

**Query Parameters:**

| Field | Type | Description |
|-------|------|-------------|
| realtime | boolean | Get real-time status from server |

---

### GET /instances/{uuid}/stats

Returns instance statistics.

**Response:**

```json
{
  "success": true,
  "data": {
    "messages_sent_today": 50,
    "remaining_quota": 450,
    "daily_limit": 500,
    "messages_this_week": 200,
    "messages_this_month": 800,
    "messages_received_today": 30,
    "conversations_count": 150,
    "contacts_count": 500,
    "failed_attempts": 0,
    "last_activity_at": "2025-01-15T10:30:00Z"
  }
}
```

---

### POST /instances/{uuid}/disconnect

Disconnect the WhatsApp instance.

---

### POST /instances/{uuid}/reconnect

Start reconnection process.

---

## Direct WhatsApp Endpoints (Instance Subdomain)

These endpoints are available **only** via the instance subdomain URL (`https://instance-{id}.zapini.app`). They provide direct access to WhatsApp operations with lower latency.

### GET /status

Get real-time connection status.

```bash
curl https://instance-18.zapini.app/status \
  -H "Authorization: Bearer sk_abc123..."
```

**Response:**
```json
{
  "success": true,
  "status": "connected",
  "connected": true,
  "connecting": false,
  "uptime": 3600.5,
  "phoneNumber": "5511999999999",
  "lastHeartbeat": "2025-01-15T10:30:00Z"
}
```

---

### GET /qr

Get QR code for authentication.

**Response:**
```json
{
  "success": true,
  "status": "qr_ready",
  "qr_code": "data:image/png;base64,...",
  "qr_code_text": "2@abc..."
}
```

---

### POST /send-message

Send a text message directly via WhatsApp.

**Parameters:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| number | string | Yes | Recipient number (e.g., 5511999999999) |
| message | string | Yes | Message content |

**Example:**
```bash
curl -X POST https://instance-18.zapini.app/send-message \
  -H "Authorization: Bearer sk_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "number": "5511999999999",
    "message": "Hello from the API!"
  }'
```

**Response:**
```json
{
  "success": true,
  "messageId": "3EB0...",
  "timestamp": 1705312200
}
```

---

### POST /send-media

Send media (image, video, audio, document).

**Parameters:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| number | string | Yes | Recipient number |
| media_url | string | Yes | Public URL of the media file |
| media_type | string | Yes | Type: image, video, audio, document |
| caption | string | No | Caption for the media |
| filename | string | No | Filename (for documents) |

---

### POST /send-reaction

React to a message with an emoji.

**Parameters:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| message_id | string | Yes | WhatsApp message ID |
| remote_jid | string | Yes | Chat JID |
| emoji | string | Yes | Reaction emoji |

---

### POST /delete-message

Delete a sent message.

**Parameters:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| message_id | string | Yes | WhatsApp message ID |
| remote_jid | string | Yes | Chat JID |

---

### GET /groups

List all WhatsApp groups.

**Response:**
```json
{
  "success": true,
  "groups": [
    {
      "jid": "120363001234567890@g.us",
      "subject": "My Group",
      "participants_count": 15,
      "creation": 1705312200
    }
  ]
}
```

---

### POST /group/create

Create a new WhatsApp group.

**Parameters:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| subject | string | Yes | Group name |
| participants | array | Yes | Array of phone numbers |

---

### GET /group/{jid}/metadata

Get group details and participants.

---

### POST /reconnect

Force reconnection to WhatsApp.

---

### POST /logout

Logout and clear session (requires new QR scan).

---

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