Developers

WhatsApp API

Overview

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.

  • Base URL: https://backend.quikpair.com/api/v1/whatsapp
  • Format: JSON in and out, except media upload (multipart).
  • Phone numbers: international digits without +, e.g. 919446088633.
  • Billing: Meta bills paid messages to your own WhatsApp Business account. QuikPair does not charge per message.

Getting started

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.

  • 1. Create a test key. In QuikPair go to WhatsApp → API & Webhooks, create a key and choose Test. It starts with qp_wa_test_.
  • 2. Build against it. 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.
  • 3. Connect your number under WhatsApp → Connection & billing (log in with Facebook). The API never uses the shared QuikPair number.
  • 4. Create your templates under WhatsApp → Templates, or with POST /templates. Meta reviews each one, often within minutes. For paid messages, add a payment method in Meta and turn on Allow paid messages.
  • 5. Switch to a live key. Create a key of type Live and replace the test key in your app. Live and test keys work the same way.
Test keys can callTest keys cannot call
POST /messages (test send), GET /account and GET /templates (once a number is connected), and the /webhook-endpoints routesAnything else, such as template changes, media upload and reading messages. These return 403 test_key_not_allowed.

Authentication

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
AbilityAllows
messages:sendPOST /messages, POST /messages/{wamid}/read
messages:readGET /messages, GET /messages/{id}
conversations:readGET /conversations…
contacts:writeGET / PATCH /contacts
media:writePOST / GET /media
templates:read / templates:writeList, or create and delete, templates
profile:writePATCH /business-profile
webhooks:manageManage 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).

Free vs paid

SituationCost (billed by Meta)
Any message within 24 hours of the customer's last messageFree
Within 72 hours after a Click-to-WhatsApp ad or Facebook Page button chatFree
Utility / authentication template outside the 24-hour windowPaid
Marketing templateAlways 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".

Send a message

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" } } ] } } }
EndpointPurpose
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}/readBlue ticks for an inbound message; {"typing_indicator": true} shows typing

Conversations, contacts & media

EndpointPurpose
GET /conversations?unread=1Threads, newest first
GET /conversations/{wa_id}/messagesFull 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.

Templates

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:

EndpointPurpose
GET /templates?status=APPROVEDYour templates with status, category, components and rejection_reason
POST /templatesCreate 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=enDelete 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:

PartRule
NameLowercase letters, numbers and _, for example order_shipped. Unique per language
BodyUp 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
HeaderOptional text, up to 60 characters, at most one variable (with an example)
FooterOptional, up to 60 characters, no variables
ButtonsUp 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
AuthenticationMeta 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:

ReasonWhat it usually meansWhat to do
INVALID_FORMATFormatting Meta does not accept, such as a missing sample value or odd variable placementCheck every variable has a sample and sits inside a sentence
TAG_CONTENT_MISMATCH / INCORRECT_CATEGORYThe text does not match the category: often an offer sent as UtilitySubmit it as Marketing, or remove the promotional wording
PROMOTIONALA Utility template reads as marketingKeep Utility templates about an order, booking or account the customer has
ABUSIVE_CONTENT / SCAMContent that breaks Meta's rules, or looks misleadingRewrite plainly. Say who you are and why you are writing
NONE with status PAUSED or DISABLEDCustomers blocked or reported it too oftenImprove the wording and targeting, then edit it to resubmit
  • Write like a real update: "Hi {{1}}, your order {{2}} has shipped." works; "{{1}}" on its own does not.
  • Use realistic samples. Meta reviews the samples, not your real data.
  • Category changes made by Meta arrive as a template.category webhook, because they change the price.

Webhooks

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 background
app.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));
});
  • Answer 2xx within 10 seconds. Otherwise we retry after 1 minute, 5 minutes, 30 minutes, 2 hours and 12 hours.
  • Events can repeat or arrive out of order: de-duplicate on id, and order by created_at.
  • An endpoint that fails 50 times in a row is disabled. Re-enable it in QuikPair.
  • Every delivery is listed under WhatsApp → Logs, with its payload and a Resend button. A resend keeps the same event id.

Errors & limits

{ "error": { "code": "outside_customer_window", "message": "More than 24 hours since the customer last wrote…", "meta_code": 131047 } }
HTTPcodeMeaning
400validation_failedInvalid body; details lists the fields
401invalid_api_keyMissing, wrong or revoked key
402paid_not_allowed · free_only_mode · payment_issue · budget_reachedA paid message that isn't allowed right now
402quota_exceededYour plan's API messages for this month are used up
403insufficient_ability · own_number_required · contact_opted_out · module_disabled · plan_limit_reachedNot permitted
403test_key_not_allowedA test key called an endpoint that changes something on WhatsApp; use a live key
403account_banned · account_suspendedMeta disabled your number (keys work again once Meta reinstates it), or the account is suspended; contact support
404not_foundUnknown message, conversation, template or media
409template_not_approvedTemplate missing or not approved
422outside_customer_window · template_params_mismatch · recipient_unavailableMeta would reject it
429rate_limitedSlow down; see Retry-After
502 / 503meta_error · meta_unavailableMeta 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).

Best practices

  • Get the customer's opt-in before messaging them, and honour STOP.
  • Prefer utility templates for transactional updates; marketing is always paid and reviewed more strictly.
  • Send an Idempotency-Key with every POST /messages.
  • Store id and wamid; drive your UI from message.status webhooks instead of polling.
  • Keep your quality rating GREEN: no unsolicited messages, specific and useful templates.
  • Version: /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.

© 2026 Quikpair, a product of ATSCOM Technology Experts LLP. All rights reserved.