---
title: "WhatsApp Inbox & Messages API"
description: "Query message logs, retrieve incoming customer messages, view message status, and download media."
---

# WhatsApp Inbox & Messages API

Bulkit provides full visibility into your WhatsApp traffic, enabling you to inspect outbound and inbound messages, review customer replies, and retrieve decrypted attachments.

---

## 1. Query Messages History

Retrieve a paginated list of sent and received WhatsApp messages with flexible search and filtering.

### Endpoint

```http
GET /api/v2/messages/whatsapp
```

### Query Parameters

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `page` | integer | `1` | Page number for pagination. |
| `limit` | integer | `50` | Items per page (max `100`). |
| `direction` | string | `all` | Filter by message direction: `all`, `inbound` (or `inbox`), `outbound` (or `sent`). |
| `mobile` | string | - | Filter by recipient or sender phone number (e.g. `254700000001`). Aliases: `phone`, `chat_jid`. |
| `status` | string | - | Filter by status: `sent`, `delivered`, `read`, `failed`, `pending`. |
| `start_date` | string | - | Filter messages sent after this ISO 8601 timestamp (e.g. `2026-09-01T00:00:00Z`). |
| `end_date` | string | - | Filter messages sent before this ISO 8601 timestamp. |

### Example Request

```bash
curl -X GET "https://api.bulkitsms.com/api/v2/messages/whatsapp?direction=outbound&limit=10" \
  -H "Authorization: Bearer bk_live_8n6JQv3K1h9Lp0Md"
```

### Example Response

```json
{
  "status": "success",
  "data": [
    {
      "id": "7b8f844a-f5e2-4144-84c4-f655e88b2a1a",
      "message_id": "3EB0C34B8F56D254",
      "direction": "outbound",
      "from": "254700000000",
      "to": "254700000001@s.whatsapp.net",
      "chat_jid": "254700000001@s.whatsapp.net",
      "text": "Hello! Your payment has been received.",
      "media_type": "text",
      "media_url": "",
      "file_name": "",
      "file_size": 0,
      "mime_type": "",
      "status": "delivered",
      "cost": 0.03,
      "timestamp": "2026-09-19T06:30:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 10,
    "total": 45
  }
}
```

---

## 2. Retrieve Incoming WhatsApp Inbox

A dedicated shortcut endpoint returning only inbound messages sent by your customers to your WhatsApp number.

### Endpoint

```http
GET /api/v2/messages/whatsapp/inbox
```

### Query Parameters

Accepts the same pagination (`page`, `limit`) and filtering (`mobile`, `start_date`, `end_date`) parameters as the messages history endpoint.

### Example Request

```bash
curl -X GET "https://api.bulkitsms.com/api/v2/messages/whatsapp/inbox?page=1&limit=20" \
  -H "Authorization: Bearer bk_live_8n6JQv3K1h9Lp0Md"
```

---

## 3. Get Single Message Details

Fetch the full metadata and status for a specific message using either its internal UUID or the WhatsApp message ID.

### Endpoint

```http
GET /api/v2/messages/whatsapp/:id
```

### Path Parameter

| Parameter | Required | Type | Description |
| --- | --- | --- | --- |
| `:id` | Yes | string | Internal Bulkit message UUID or WhatsApp message ID (e.g. `3EB0C34B8F56D254`). |

### Example Request

```bash
curl -X GET "https://api.bulkitsms.com/api/v2/messages/whatsapp/7b8f844a-f5e2-4144-84c4-f655e88b2a1a" \
  -H "Authorization: Bearer bk_live_8n6JQv3K1h9Lp0Md"
```

---

## 4. Download Decrypted Media Attachment

When receiving or sending files (images, PDFs, documents, audio, video), the media content is stored securely encrypted. Use this endpoint with your API credentials to download or stream the decrypted binary data.

### Endpoint

```http
GET /api/v2/messages/whatsapp/:id/media
```

### Query Parameters

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `download` | string | `0` | If set to `1`, sets `Content-Disposition: attachment` to trigger a file download in browsers. Defaults to `inline`. |

### Example Request

```bash
curl -X GET "https://api.bulkitsms.com/api/v2/messages/whatsapp/7b8f844a-f5e2-4144-84c4-f655e88b2a1a/media" \
  -H "Authorization: Bearer bk_live_8n6JQv3K1h9Lp0Md" \
  --output downloaded_attachment.pdf
```