API Documentation

The KhabeerSoft WhatsApp REST API lets you connect WhatsApp numbers, send single and bulk messages, and track delivery — all over simple HTTP requests that return JSON.

Base URL

https://api.khabeersoft.cloud/api/v1

All requests must be sent over HTTPS in production and include your API key. Request bodies are JSON (Content-Type: application/json).

Authentication

Authenticate every request with your API key in the x-api-key header. You can generate and revoke keys from your dashboard.

Authorization header

x-api-key: YOUR_API_KEY

Keep your API key secret. Never expose it in client-side code or public repositories.

POST /api/v1/messages/send

Send a message

Queues a single message for delivery. Returns immediately with a message id you can poll for status.

Body parameters

Field	Type	Description
instance_id	integer	The connected WhatsApp number to send from. Required.
to	string	Recipient in international format, no `+` or leading `0` (e.g. `201001234567`). Required.
type	string	`text` (default), `image`, or `document`.
text	string	Message body for `text` type.
content	object	For media: `{ url, caption }` (image) or `{ url, filename, mimetype }` (document).

Example request

curl -X POST https://api.khabeersoft.cloud/api/v1/messages/send \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instance_id": 1,
    "to": "201001234567",
    "type": "text",
    "text": "Hello from the API 👋"
  }'

Response · 202 Accepted

{
  "id": 123,
  "status": "queued"
}

POST /api/v1/messages/send-bulk

Send bulk messages

Queue up to 100 messages in one request. Each is processed individually with rate limiting.

Example request

curl -X POST https://api.khabeersoft.cloud/api/v1/messages/send-bulk \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instance_id": 1,
    "messages": [
      { "to": "201001234567", "text": "Hi Ahmed" },
      { "to": "201009999999", "text": "Hi Sara" }
    ]
  }'

Response · 202 Accepted

{
  "queued": 2,
  "messages": [
    { "id": 124, "to": "201001234567", "status": "queued" },
    { "id": 125, "to": "201009999999", "status": "queued" }
  ]
}

GET /api/v1/messages/{id}

Get message status

Retrieve the current status of a message you previously sent.

Example request

curl https://api.khabeersoft.cloud/api/v1/messages/123 \
  -H "x-api-key: YOUR_API_KEY"

Response · 200 OK

{
  "id": 123,
  "to_phone": "201001234567",
  "type": "text",
  "status": "sent",
  "error": null,
  "queued_at": "2026-06-23T14:00:00.000Z",
  "sent_at": "2026-06-23T14:00:02.000Z"
}

POST /api/v1/instances

Create an instance

Creates a new WhatsApp session. After creating, fetch the QR code to link a phone. Subject to your plan's number limit.

Example request

curl -X POST https://api.khabeersoft.cloud/api/v1/instances \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Main Store Number" }'

Response · 201 Created

{
  "id": 5,
  "status": "waiting_scan",
  "qr_url": "/api/v1/instances/5/qr"
}

GET /api/v1/instances · /api/v1/instances/{id}

List & get instances

List all your instances, or fetch a single one by id.

Response · 200 OK

[
  {
    "id": 1,
    "name": "Main Store Number",
    "phone": "201093619140",
    "status": "connected",
    "created_at": "2026-06-20T10:00:00.000Z"
  }
]

GET /api/v1/instances/{id}/qr

Get QR code

Returns the QR code to link the WhatsApp number. Poll this endpoint every few seconds until status becomes connected. Add ?format=image to get a PNG instead of JSON.

Response while waiting

{
  "qr_base64": "data:image/png;base64,iVBORw0...",
  "status": "waiting_scan"
}

Response once linked

{
  "status": "connected",
  "phone": "201093619140"
}

DELETE /api/v1/instances/{id}

Delete an instance

Disconnects the WhatsApp session and removes it.

Response · 200 OK

{
  "status": "disconnected"
}

GET /api/v1/usage

Usage stats

Returns your current monthly and daily message usage against your plan limits.

Response · 200 OK

{
  "monthly": { "used": 320, "limit": 1000, "remaining": 680, "percentage": 32 },
  "daily":   { "used": 45,  "limit": 500,  "remaining": 455, "percentage": 9 }
}

Message statuses

queuedAccepted and waiting in the queue.

sendingBeing delivered to WhatsApp right now.

sentSuccessfully handed off to WhatsApp.

failedCould not be delivered — see the error field.

Errors & status codes

Code	Meaning
200 / 201 / 202	Success — request accepted or completed.
400	Bad request — invalid phone number or missing field.
401	Missing or invalid API key.
403	Account disabled, or plan limit reached.
404	Resource not found.
429	Monthly or daily message limit reached.

Error responses always include a JSON error message describing what went wrong.

Ready to build?جاهز تبدأ؟

Contact Usتواصل معنا