Bulkit
Register

WhatsApp Inbox & Messages API

Query message logs, retrieve incoming customer messages, view message status, and download media.

Last updated · Markdown version

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

ParameterTypeDefaultDescription
pageinteger1Page number for pagination.
limitinteger50Items per page (max 100).
directionstringallFilter by message direction: all, inbound (or inbox), outbound (or sent).
mobilestring-Filter by recipient or sender phone number (e.g. 254700000001). Aliases: phone, chat_jid.
statusstring-Filter by status: sent, delivered, read, failed, pending.
start_datestring-Filter messages sent after this ISO 8601 timestamp (e.g. 2026-09-01T00:00:00Z).
end_datestring-Filter messages sent before this ISO 8601 timestamp.

Example Request

cURL / 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

cURL / 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

ParameterRequiredTypeDescription
:idYesstringInternal Bulkit message UUID or WhatsApp message ID (e.g. 3EB0C34B8F56D254).

Example Request

cURL / 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

ParameterTypeDefaultDescription
downloadstring0If set to 1, sets Content-Disposition: attachment to trigger a file download in browsers. Defaults to inline.

Example Request

cURL / 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
PreviousSend Bulk WhatsApp BroadcastNextWhatsApp Connection Status