WhatsApp API Guide
Send text, images and other media, personalized bulk messages, and campaigns using the WhizText messaging gateway.
Base URL: https://api.whiztext.com/v1
Getting started
- Sign in to the messaging portal, connect WhatsApp, and check your available quota.
- In the portal's API Keys page, generate a gateway key and save it securely. It is shown only once.
- Set
WHIZTEXT_API_KEYin your server environment and try the examples below with a recipient who has agreed to receive messages. Include the country code in phone numbers.
Gateway keys are managed in the messaging portal and are separate from API keys created on this website. Do not expose keys in browser code or public repositories.
Authentication and responses
Send your gateway key as X-API-Key or Authorization: Bearer YOUR_API_KEY. The health endpoint does not require a key. JSON requests use Content-Type: application/json; for uploads let your client set the multipart boundary.
A successful send or campaign response means the request was accepted for background processing, not that WhatsApp delivered it. A single-send messageId is a database log ID and may be null if logging failed; it is not the WhatsApp message ID. Check message history in the messaging portal for later outcomes.
Typical errors include 400 for invalid input, 401 for a missing or invalid key, 403 for denied access, 404 for a missing resource, 429 for quota or rate limits, and 500 for server errors. Campaign quota checks can return 400. Inspect the JSON error before retrying; blindly retrying an accepted request may send duplicates.
Send a text message
POST /send accepts to and message. No instance ID is required; the gateway key identifies the account.
curl -X POST 'https://api.whiztext.com/v1/send' \
-H "X-API-Key: $WHIZTEXT_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"to":"+923001234567","message":"Hello from WhizText!"}'
Example response
{
"success": true,
"messageId": 123,
"timestamp": "2026-01-01T12:00:00.000Z",
"recipient": "+923001234567",
"mediaType": null,
"quotaUsed": 5,
"quotaRemaining": 95,
"status": "sending",
"message": "Message sent"
}
Status can also be queued when reconnecting. Even when the response says “Message sent”, processing is asynchronous.
Send an image or other media
Use the same POST /send endpoint with multipart form data. Set to, attach one file as media, and optionally provide message as its caption. A file can be sent without text. Do not use file, caption, or a media URL in place of these fields.
curl -X POST 'https://api.whiztext.com/v1/send' \
-H "X-API-Key: $WHIZTEXT_API_KEY" \
-F 'to=+923001234567' \
-F 'message=Here is your image' \
-F 'media=@/path/to/image.jpg;type=image/jpeg'
Maximum file size: 16 MiB. Supported images: JPEG, PNG, GIF and WebP. The upload also accepts MP4, 3GPP and QuickTime video; MPEG, MP4, OGG and WAV audio; PDF, Word and Excel documents. For audio, text is sent as a separate message rather than a caption.
Keep WhatsApp connected when sending media. File contents are not restored from the message log if a queued job is reloaded after a restart or disconnection; check the result and resend the file if necessary.
Personalized bulk messages
POST /bulk/personalized accepts a non-empty messages array. Each entry must have mobile and message; this endpoint sends text only. The account must have enough quota for the entire batch.
curl -X POST 'https://api.whiztext.com/v1/bulk/personalized' \
-H "X-API-Key: $WHIZTEXT_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"messages":[{"mobile":"+923001234567","message":"Hello Ali!"},{"mobile":"+923001234568","message":"Hello Sara!"}]}'
The response contains success, total, queuedIds, message and quota. IDs may be incomplete if database logging fails; acceptance does not guarantee delivery.
Create a campaign
POST /campaign accepts name, a non-empty recipients array, and message or a media upload. The same content is sent to every recipient. Check quota for the whole recipient list first.
curl -X POST 'https://api.whiztext.com/v1/campaign' \
-H "X-API-Key: $WHIZTEXT_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"name":"Offer","message":"Hello!","recipients":["+923001234567","+923001234568"]}'
Campaign with an image
For multipart requests, send recipients as a JSON array encoded in a form field, or as comma-separated numbers.
curl -X POST 'https://api.whiztext.com/v1/campaign' \
-H "X-API-Key: $WHIZTEXT_API_KEY" \
-F 'name=Image offer' \
-F 'message=See our offer' \
-F 'recipients=["+923001234567","+923001234568"]' \
-F 'media=@/path/to/image.jpg;type=image/jpeg'
The response includes campaignId, recipientCount, messageIds and status: "queued". A fallback campaign ID can be returned if persistence fails. Media uploads have the same limits and recovery caveat as single sends.
The gateway also exposes GET /campaigns and GET /campaign/{campaignId}, but the current implementation does not reliably return campaign data. Check the messaging portal rather than depending on these endpoints for tracking.
Health check
GET /health is public and returns service information and a timestamp. It does not confirm that your account or WhatsApp session is connected.
curl 'https://api.whiztext.com/v1/health'
Image upload in application code
Python (requests)
import os
import requests
with open("image.jpg", "rb") as image:
response = requests.post(
"https://api.whiztext.com/v1/send",
headers={"X-API-Key": os.environ["WHIZTEXT_API_KEY"]},
data={"to": "+923001234567", "message": "Here is your image"},
files={"media": ("image.jpg", image, "image/jpeg")},
timeout=30,
)
response.raise_for_status()
print(response.json())
PHP (cURL)
<?php
$ch = curl_init('https://api.whiztext.com/v1/send');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['X-API-Key: ' . getenv('WHIZTEXT_API_KEY')],
CURLOPT_POSTFIELDS => [
'to' => '+923001234567',
'message' => 'Here is your image',
'media' => new CURLFile('/path/to/image.jpg', 'image/jpeg'),
],
]);
$body = curl_exec($ch);
if ($body === false) {
throw new RuntimeException(curl_error($ch));
}
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($status >= 400) {
throw new RuntimeException("HTTP $status: $body");
}
echo $body;