---
title: "WhatsApp API Overview"
description: "Send direct WhatsApp messages, media files, and personalized broadcasts via API v2."
---

# WhatsApp API Overview

The Bulkit WhatsApp API v2 allows businesses and developers to send direct WhatsApp messages, media attachments (images, PDFs, documents, audio, video), and personalized bulk broadcasts directly from their connected WhatsApp accounts.

## Key Capabilities

- **Single Message Dispatch**: Send text notifications, OTP codes, order confirmations, and receipts.
- **Rich Media**: Send PDFs (invoices, statements), images, audio notes, and video attachments up to 50MB.
- **Bulk Broadcasts**: Send personalized broadcasts to multiple recipients with dynamic `{variables}` and rate limiting.
- **Two-way Inbox**: Fetch incoming customer replies via REST API or subscribe via real-time webhooks.
- **Automated Delivery Tracking**: Receive `whatsapp.message.sent`, `whatsapp.receipt.updated` (delivered, read/blue-tick), and `whatsapp.message.failed` webhook events.

## Prerequisites

Before calling the WhatsApp API:

1. **Connect your WhatsApp Account**: Go to the Bulkit dashboard at `/whatsapp` and scan the QR code with your WhatsApp or WhatsApp Business mobile app (**Linked Devices** -> **Link a Device**).
2. **Generate API Token**: Navigate to **API Keys** in the dashboard to generate your API token (`bk_live_...`).
3. **Verify Connection**: Call the `GET /api/v2/whatsapp/status` endpoint to confirm your session is active.

<Info>
Bulkit connects directly through WhatsApp Web protocols. All messages are dispatched from your connected phone number, maintaining your brand identity and allowing seamless two-way chat.
</Info>

## Endpoints Summary

| Method | Endpoint | Description |
| --- | --- | --- |
| `POST` | `/api/v2/messages/whatsapp` | Send a single WhatsApp message (text, media URL, or file upload) |
| `POST` | `/api/v2/messages/whatsapp/bulk` | Send personalized WhatsApp broadcast to multiple recipients |
| `GET` | `/api/v2/messages/whatsapp` | Query sent and received message history with filtering |
| `GET` | `/api/v2/messages/whatsapp/inbox` | Retrieve inbound customer replies |
| `GET` | `/api/v2/messages/whatsapp/:id` | Get single message status and details |
| `GET` | `/api/v2/messages/whatsapp/:id/media` | Download decrypted media attachment |
| `GET` | `/api/v2/whatsapp/status` | Check device pairing and session connection status |

## Authentication

All WhatsApp endpoints authenticate using the standard HTTP `Authorization: Bearer` header:

- **Bearer Token (Recommended)**:
  ```http
  Authorization: Bearer bk_live_8n6JQv3K1h9Lp0Md
  ```
- **Legacy Dual Headers**:
  ```http
  X-API-Key: bk_live_8n6JQv3K1h9Lp0Md
  X-API-Secret: sk_live_4jPzT5uN8xA1rC6
  ```
- **HTTP Basic Auth**:
  ```http
  Authorization: Basic <base64(api_key:api_secret)>
  ```
- **Query Parameter** (for `GET` endpoints):
  ```http
  ?apikey=bk_live_8n6JQv3K1h9Lp0Md
  ```

## Supported Media Types

Bulkit supports sending attachments up to **50MB** in size:

- **Images**: JPEG, PNG, WEBP, GIF
- **Documents**: PDF, DOCX, XLSX, CSV, TXT
- **Audio**: MP3, OGG, WAV, M4A, AAC
- **Video**: MP4, MOV, 3GP

## Webhook Events

Bulkit automatically emits real-time events to your configured **DLR Webhook** and **Inbox Webhook**:

- `whatsapp.message.received`: When a customer messages your connected WhatsApp account.
- `whatsapp.receipt.updated`: When a message is delivered or read (`status`: `"delivered"` or `"read"`).

See [Webhooks Overview](/webhooks/overview) for details on setting up webhooks.