Developers
The QuikPair WhatsApp API lets your website, CRM, booking system or app send and receive WhatsApp messages through your own WhatsApp Business number connected to QuikPair. Everything sent through the API also appears in your QuikPair inbox.
https://backend.quikpair.com/api/v1/whatsapp+, e.g. 919446088633.Five steps from sign-up to your first real message. You can build and test everything with a test key before your number is even connected.
qp_wa_test_.POST /messages with a test key checks the request body the same way a live send does (and, once your number is connected, that the template is approved). It returns 202, and fires message.status webhooks (sent, delivered, read) marked "test": true. Nothing reaches WhatsApp, nothing is charged, and nothing counts towards your plan. Send to a number ending in 0000 to get a failed status instead. Test sends skip the live-only checks: the 24-hour window, opt-outs, paid-message settings and your monthly quota.POST /templates. Meta reviews each one, often within minutes. For paid messages, add a payment method in Meta and turn on Allow paid messages.| Test keys can call | Test keys cannot call |
|---|---|
POST /messages (test send), GET /account and GET /templates (once a number is connected), and the /webhook-endpoints routes | Anything else, such as template changes, media upload and reading messages. These return 403 test_key_not_allowed. |
Send the key as a bearer token. The full key is shown once when you create it; store it in a secret manager and never put it in browser or mobile-app code.
Authorization: Bearer qp_wa_3f9a1c2b_9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e| Ability | Allows |
|---|---|
messages:send | POST /messages, POST /messages/{wamid}/read |
messages:read | GET /messages, GET /messages/{id} |
conversations:read | GET /conversations… |
contacts:write | GET / PATCH /contacts |
media:write | POST / GET /media |
templates:read / templates:write | List, or create and delete, templates |
profile:write | PATCH /business-profile |
webhooks:manage | Manage webhook endpoints |
Each key has a rate limit (default 60 requests a minute) and an Allow paid switch. Responses carry X-RateLimit-Limit and X-RateLimit-Remaining. If your plan has a monthly number of API messages, POST /messages also returns X-Quota-Limit, X-Quota-Remaining and X-Quota-Reset; when it is used up you get 402 quota_exceeded until the 1st (UTC).
| Situation | Cost (billed by Meta) |
|---|---|
| Any message within 24 hours of the customer's last message | Free |
| Within 72 hours after a Click-to-WhatsApp ad or Facebook Page button chat | Free |
| Utility / authentication template outside the 24-hour window | Paid |
| Marketing template | Always paid |
Outside the 24-hour window you must send an approved template. A paid send needs Allow paid on both your branch and the API key, otherwise you get 402. Check first with GET /conversations/{wa_id}/window. Every message reports "billing": "free" | "paid".
POST /messages: the body follows Meta's Cloud API message object. Set type and an object of the same name. Send an Idempotency-Key header so a retry never sends twice. Returns 202 with the queued message.
curl -X POST https://backend.quikpair.com/api/v1/whatsapp/messages \
-H "Authorization: Bearer $QUIKPAIR_WA_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"to":"919446088633","type":"template","template":{"name":"repair_ready_for_pickup","language":{"code":"en"},
"components":[{"type":"body","parameters":[{"type":"text","text":"Rahul"},{"type":"text","text":"Quick Fix Mobiles"},{"type":"text","text":"JOB-1042"}]}]}}'{ "id": "msg_1042", "status": "queued", "billing": "paid", "to": "919446088633", "client_ref": null }The same template send in other languages:
curl -X POST https://backend.quikpair.com/api/v1/whatsapp/messages \
-H "Authorization: Bearer $QUIKPAIR_WA_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-1042-ready" \
-d '{"to":"919446088633","type":"template",
"template":{"name":"order_shipped","language":{"code":"en"},
"components":[{"type":"body","parameters":[{"type":"text","text":"Rahul"},{"type":"text","text":"#1042"}]}]}}'Supported types: text, template, image, video, audio, document, sticker, location, contacts, interactive (button, list, cta_url, flow, product, product_list, location_request_message) and reaction. Add context.message_id to reply to a message, and client_ref to tie it to your own order.
{ "to": "919446088633", "type": "text", "text": { "body": "Your phone is ready. Track: https://www.quikpair.com/track-repair", "preview_url": true } }
{ "to": "919446088633", "type": "document",
"document": { "id": "med_17", "filename": "Invoice-1042.pdf", "caption": "Your invoice" } }
{ "to": "919446088633", "type": "interactive",
"interactive": { "type": "button", "body": { "text": "Estimate for JOB-1042 is ₹2,400. Approve?" },
"action": { "buttons": [ { "type": "reply", "reply": { "id": "approve_1042", "title": "Approve" } },
{ "type": "reply", "reply": { "id": "reject_1042", "title": "Not now" } } ] } } }| Endpoint | Purpose |
|---|---|
GET /messages/{id} | Status (queued, sent, delivered, read, failed, skipped), billing, error |
GET /messages?to=&status=&since=&limit= | Search; cursor pages via next_cursor (?cursor=) |
POST /messages/{wamid}/read | Blue ticks for an inbound message; {"typing_indicator": true} shows typing |
| Endpoint | Purpose |
|---|---|
GET /conversations?unread=1 | Threads, newest first |
GET /conversations/{wa_id}/messages | Full thread, including messages sent from the WhatsApp Business app (source: business_app) |
GET /conversations/{wa_id}/window | { window_open, closes_at, free_entry_until, next_message_billing } |
GET /contacts?search= | Contacts with opt-in / opt-out |
PATCH /contacts/{wa_id} | { "name", "opted_in", "opted_out" }: record consent |
POST /media (multipart file) | Upload; returns { "id": "med_…" } for use in messages |
GET /media/{id} | Download media you sent or received |
A customer who replies STOP is opted out automatically.
A template is a message Meta has approved in advance. You need one to message a customer who has not written to you in the last 24 hours. Build them with a live preview under WhatsApp → Templates, or through the API:
| Endpoint | Purpose |
|---|---|
GET /templates?status=APPROVED | Your templates with status, category, components and rejection_reason |
POST /templates | Create one and submit it for review |
PUT /templates/{name} | Change an approved, rejected or paused template ({ "language", "components" }). It goes back to review |
DELETE /templates/{name}?language=en | Delete it. Meta deletes every language of the name, and the name cannot be reused for 30 days |
{ "name": "appointment_reminder", "language": "en", "category": "UTILITY",
"components": [ { "type": "BODY",
"text": "Hi {{1}}, reminder: your appointment at {{2}} is on {{3}}.",
"example": { "body_text": [ ["Rahul", "Quick Fix Mobiles", "5 Oct, 5 PM"] ] } } ] }Checked before it reaches Meta. A template that breaks one of these rules returns 400 validation_failed, with the field in details, so you find out at once instead of after a rejection:
| Part | Rule |
|---|---|
| Name | Lowercase letters, numbers and _, for example order_shipped. Unique per language |
| Body | Up to 1024 characters. Variables are {{1}}, {{2}}… in order with no gaps; not at the very start or end; never two side by side; an example value for each |
| Header | Optional text, up to 60 characters, at most one variable (with an example) |
| Footer | Optional, up to 60 characters, no variables |
| Buttons | Up to 10. Quick replies first; at most 2 website buttons (one variable, only at the end of the URL), 1 call button, 1 copy-code button (Marketing only). Button text up to 25 characters |
| Authentication | Meta writes the text. Send BODY with add_security_recommendation, optional FOOTER with code_expiration_minutes (1–90) and an OTP button |
Why Meta rejects templates. Meta can still reject one for its wording. The reason arrives in the template.status webhook and in rejection_reason:
| Reason | What it usually means | What to do |
|---|---|---|
INVALID_FORMAT | Formatting Meta does not accept, such as a missing sample value or odd variable placement | Check every variable has a sample and sits inside a sentence |
TAG_CONTENT_MISMATCH / INCORRECT_CATEGORY | The text does not match the category: often an offer sent as Utility | Submit it as Marketing, or remove the promotional wording |
PROMOTIONAL | A Utility template reads as marketing | Keep Utility templates about an order, booking or account the customer has |
ABUSIVE_CONTENT / SCAM | Content that breaks Meta's rules, or looks misleading | Rewrite plainly. Say who you are and why you are writing |
NONE with status PAUSED or DISABLED | Customers blocked or reported it too often | Improve the wording and targeting, then edit it to resubmit |
template.category webhook, because they change the price.Register an HTTPS endpoint in WhatsApp → API & Webhooks, or with POST /webhook-endpoints { "url", "events" }. The signing secret (whsec_…) is shown once. Events: message.received, message.status, message.echo (sent from the phone app), template.status, template.category, account.status.
{
"id": "evt_01j9zq3w…",
"event": "message.received",
"created_at": "2026-10-03T10:20:11+00:00",
"data": { "message": { "id": "msg_88", "wamid": "wamid.HBgM…", "from": "919446088633", "name": "Rahul",
"type": "text", "text": { "body": "Is my phone ready?" } } }
}Verify X-QuikPair-Signature: t=<unix>,v1=<hex>, where v1 = HMAC_SHA256(secret, "<t>.<raw body>"), and reject requests more than 5 minutes old.
$sig = [];
parse_str(str_replace(',', '&', $_SERVER['HTTP_X_QUIKPAIR_SIGNATURE'] ?? ''), $sig);
$body = file_get_contents('php://input');
$expected = hash_hmac('sha256', $sig['t'].'.'.$body, getenv('QUIKPAIR_WEBHOOK_SECRET'));
if (! hash_equals($expected, $sig['v1'] ?? '') || abs(time() - (int) $sig['t']) > 300) {
http_response_code(401); exit;
}
http_response_code(200); // respond fast, process in the backgroundapp.post('/hooks/quikpair', express.raw({ type: 'application/json' }), (req, res) => {
const sig = Object.fromEntries(req.get('X-QuikPair-Signature').split(',').map(p => p.split('=')));
const expected = crypto.createHmac('sha256', process.env.QUIKPAIR_WEBHOOK_SECRET)
.update(`${sig.t}.${req.body}`).digest('hex');
const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig.v1 || ''))
&& Math.abs(Date.now() / 1000 - Number(sig.t)) < 300;
if (!ok) return res.sendStatus(401);
res.sendStatus(200);
handle(JSON.parse(req.body));
});2xx within 10 seconds. Otherwise we retry after 1 minute, 5 minutes, 30 minutes, 2 hours and 12 hours.id, and order by created_at.id.{ "error": { "code": "outside_customer_window", "message": "More than 24 hours since the customer last wrote…", "meta_code": 131047 } }| HTTP | code | Meaning |
|---|---|---|
| 400 | validation_failed | Invalid body; details lists the fields |
| 401 | invalid_api_key | Missing, wrong or revoked key |
| 402 | paid_not_allowed · free_only_mode · payment_issue · budget_reached | A paid message that isn't allowed right now |
| 402 | quota_exceeded | Your plan's API messages for this month are used up |
| 403 | insufficient_ability · own_number_required · contact_opted_out · module_disabled · plan_limit_reached | Not permitted |
| 403 | test_key_not_allowed | A test key called an endpoint that changes something on WhatsApp; use a live key |
| 403 | account_banned · account_suspended | Meta disabled your number (keys work again once Meta reinstates it), or the account is suspended; contact support |
| 404 | not_found | Unknown message, conversation, template or media |
| 409 | template_not_approved | Template missing or not approved |
| 422 | outside_customer_window · template_params_mismatch · recipient_unavailable | Meta would reject it |
| 429 | rate_limited | Slow down; see Retry-After |
| 502 / 503 | meta_error · meta_unavailable | Meta problem; retry with backoff |
Meta allows roughly 80 messages a second per number (about 20 for numbers shared with the WhatsApp Business app); QuikPair queues sends so bursts are smoothed. Daily business-initiated conversations are capped by your Meta messaging tier (GET /account).
Idempotency-Key with every POST /messages.id and wamid; drive your UI from message.status webhooks instead of polling./v1. Fields may be added; breaking changes go to a new version with 90 days' overlap.Questions or need a higher rate limit?
Email [email protected]. Prefer to try it first? Create a test key (see Getting started): nothing is sent or charged.
Features
Resources
© 2026 Quikpair, a product of ATSCOM Technology Experts LLP. All rights reserved.