WhatsApp API reference

WApenda turns your own WhatsApp number into a REST API. Send messages and media, manage groups and contacts, and receive every event on your webhook. The API is compatible with WaSender API — most integrations only change the base URL and key.

Base URL   https://tekservix.com/wapenda/api
Format     JSON (UTF-8) in and out
Auth       Authorization: Bearer <key>

Authentication

There are two kinds of keys, both sent as a Bearer token:

curl https://tekservix.com/wapenda/api/status -H "Authorization: Bearer wpk_your_device_key"

Responses & errors

Every response has success. Successful calls return data; failures return message (and errors for invalid fields).

{ "success": true,  "data": { "msgId": 58213, "jid": "250788123456@s.whatsapp.net", "status": "in_progress" } }
{ "success": false, "message": "\"to\" is required (phone number in international format, or a group/channel JID).", "errors": { "to": "required" } }

Limits & account protection

• Requests: 300 per minute per key (X-RateLimit-Remaining header).
• Messages: unlimited on every plan. Sends are queued and go out one at a time per device, so send-message answers immediately with "status": "in_progress"; track delivery with webhooks or message info.
• Account protection (on by default, per device): random 5–12 s gaps between messages (1–3 s when replying inside a live conversation), a typing indicator, a warm-up for newly linked numbers (60 messages on day 1 rising to 1,500/day over 5 days), 250/hour, no identical message to the same person within 10 minutes, and a check that each new number is on WhatsApp. Turning it off allows ~1–2.5 s gaps and 10,000/day — only do that for opted-in traffic on an established number.
• Media: up to 64 MB per file (WhatsApp itself limits images/video to ~16 MB).

Send a message

One endpoint sends every message type. The aliases /send-image-message, /send-video-message, /send-document-message, /send-audio-message, /send-sticker-message, /send-contact-card, /send-location, /send-poll-message, /send-quoted-message, /send-message-with-mentions and /send-view-once-message accept the same body.

curl -X POST https://tekservix.com/wapenda/api/send-message \
  -H "Authorization: Bearer $WAPENDA_KEY" -H "Content-Type: application/json" \
  -d '{"to":"+250788123456","text":"Hello Aline, your order is ready 🎉"}'

{ "success": true, "data": { "msgId": 58213, "jid": "250788123456@s.whatsapp.net", "status": "in_progress" } }

Examples by type

// Image with caption
{ "to": "+250788123456", "text": "New arrivals 👗", "imageUrl": "https://example.com/catalogue.jpg" }

// Document
{ "to": "+250788123456", "text": "Your invoice", "documentUrl": "https://example.com/inv-1042.pdf", "fileName": "Invoice-1042.pdf" }

// Voice note
{ "to": "+250788123456", "audioUrl": "https://example.com/hello.ogg", "ptt": true }

// Location
{ "to": "+250788123456", "location": { "latitude": -1.9441, "longitude": 30.0619, "name": "Our shop" } }

// Contact card
{ "to": "+250788123456", "contact": { "name": "Support", "phone": "+250788000000" } }

// Poll
{ "to": "120363000000000000@g.us", "poll": { "question": "Best delivery day?", "options": ["Monday", "Friday"] } }

// Reply to a message, with a mention
{ "to": "120363000000000000@g.us", "text": "Thanks @250788123456!", "replyTo": 58190, "mentions": ["250788123456"] }

// Older WaSender style (base64) is accepted too
{ "to": "+250788123456", "document": { "data": "JVBERi0xLjQK…", "filename": "report.pdf" }, "caption": "Report" }

Info, edit, delete, resend

{id} is the msgId returned when sending (or a WhatsApp message id).

Status (queued, sent, delivered, read, played, failed), error, WhatsApp key and timestamps.

Edit your own text message: {"text": "corrected text"} (WhatsApp allows about 15 minutes).

Delete for everyone.

Queue a failed message again.

Mark as read

{ "msgId": "3EB0X123456789", "jid": "250788123456@s.whatsapp.net" }
// or the key from a webhook
{ "key": { "id": "3EB0X123456789", "remoteJid": "250788123456@s.whatsapp.net", "fromMe": false } }

Typing indicator

{ "jid": "+250788123456", "type": "typing" }   // typing | recording | paused | available | unavailable

Upload & decrypt media

Multipart file, or JSON {"base64": "…", "fileName": "photo.jpg"}. Returns a publicUrl to use in imageUrl/documentUrl… Files are kept for 48 hours.

Send the webhook payload of a received image, video, audio or document ({"data": {"messages": {…}}}) and get a temporary publicUrl to the decrypted file.

Contacts

{"exists": true, "jid": "…@s.whatsapp.net"} — check before you message a new number.

Contacts synced from the phone, plus people who messaged you.

{"phone": "+250788123456", "name": "Aline"} — save a name in WApenda.

WhatsApp sometimes identifies people by a private “LID” instead of a phone number. Webhooks always include cleanedSenderPn when the phone number is known, and you can reply to either form.

Groups

{"subject": "VIP customers", "participants": ["250788123456", "250722000000"]}

{"participants": ["250788123456"]} (you must be an admin)

{"participants": ["250788123456"], "action": "promote"} — or demote.

{"subject": "…", "description": "…", "announce": true, "restrict": false} — announce: only admins send; restrict: only admins edit info.

{"inviteCode": "AbCdEf123"}

Status & user

{"status": "connected"} — one of connected, connecting, need_scan, disconnected, logged_out, expired.

The linked WhatsApp account: {"id", "number", "name"}.

Manage devices (personal access token)

Your devices, including each api_key and webhook_secret.

{ "name": "Sales line", "webhook_url": "https://your-app.com/wa", "webhook_events": ["messages.received","messages.update"],
  "account_protection": true, "log_messages": true, "read_incoming_messages": false, "auto_reject_calls": false }

{"method": "qr"}, or {"method": "code", "phone": "250788123456"} for an 8-character pairing code. Then poll:

{"qrCode": "2@…", "qrImage": "data:image/png;base64,…", "pairingCode": null, "status": "need_scan"} — the QR changes every ~20 s.

A device key may also call these for its own device id.

Webhooks

Set a webhook URL per device (dashboard or PUT /whatsapp-sessions/{id}). We send a POST with JSON for each event you selected, and retry 3 times (after ~4 s and 30 s) unless you answer 2xx. Answer quickly and process in the background.

POST https://your-app.com/wa
Content-Type: application/json
X-Webhook-Signature: <your device's webhook secret>
X-WApenda-Event: messages.received

{ "event": "messages.received", "sessionId": 12, "timestamp": 1758822000,
  "data": { "messages": {
    "key": { "id": "3EB0X123456789", "fromMe": false, "remoteJid": "250788123456@s.whatsapp.net",
             "addressingMode": "pn", "senderPn": "250788123456@s.whatsapp.net", "cleanedSenderPn": "250788123456" },
    "messageBody": "Hello, is this available?", "pushName": "Aline", "type": "text",
    "message": { "conversation": "Hello, is this available?" } } } }

Verify the request came from WApenda:

// Node.js (Express)
app.post('/wa', express.json(), (req, res) => {
  if (req.get('X-Webhook-Signature') !== process.env.WAPENDA_WEBHOOK_SECRET) return res.sendStatus(401);
  res.sendStatus(200);                       // acknowledge first
  handle(req.body).catch(console.error);     // then do the work
});

// PHP
if (!hash_equals(getenv('WAPENDA_WEBHOOK_SECRET'), $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '')) { http_response_code(401); exit; }
$event = json_decode(file_get_contents('php://input'), true);

Events

WaSender compatibility

Coming from WaSender API? Change the base URL and use your WApenda key:

- https://www.wasenderapi.com/api
+ https://tekservix.com/wapenda/api

Not available: Passkey (WebAuthn) linking — use the QR code or a phone pairing code.