QuickWA API

How it works

Step 1 · Connect your WhatsApp number

• A number already running on the WhatsApp Business app can be kept — choose Coexistence. Do that part on a computer, with the phone in your hand for the QR code.
• If the number has two-step verification, you will be asked for its PIN. Lost it? It cannot be switched off, but you can change it: WhatsApp Manager → your number → Settings → Two-step verification → Change PIN.
• After connecting, press Activate number if the dashboard asks. Until it says connected, API sends will fail.

Step 2 · Create an API key

Step 3 · Create a message template

Submitting an OTP template over the API

POST https://quickwa.com/api/templates
Authorization: Bearer <your dashboard session>
Content-Type: application/json

{
  "name": "login_code",
  "category": "AUTHENTICATION",
  "language": "en_US",
  "components": [
    { "type": "BODY",    "add_security_recommendation": true },
    { "type": "FOOTER",  "code_expiration_minutes": 5 },
    { "type": "BUTTONS", "buttons": [
        { "type": "OTP", "otp_type": "COPY_CODE", "text": "Copy code" }
    ]}
  ]
}

Step 4 · Send your first message

cURL

curl -X POST https://quickwa.com/api/send-message \
  -H "X-API-Key: $QUICKWA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "919876543210",
    "template_name": "order_shipped",
    "language": "en_US",
    "variables": { "1": "Amit", "2": "ORD-4821" }
  }'

Node.js

const res = await fetch('https://quickwa.com/api/send-message', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.QUICKWA_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    phone_number: '919876543210',
    template_name: 'order_shipped',
    language: 'en_US',
    variables: { '1': 'Amit', '2': 'ORD-4821' }
  })
});
const out = await res.json();
if (!res.ok) throw new Error(JSON.stringify(out));
console.log(out.message_id);   // keep this to match the delivery receipt

PHP

$ch = curl_init('https://quickwa.com/api/send-message');
curl_setopt_array($ch, [
  CURLOPT_POST           => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER     => [
    'X-API-Key: ' . getenv('QUICKWA_KEY'),
    'Content-Type: application/json'
  ],
  CURLOPT_POSTFIELDS => json_encode([
    'phone_number'  => '919876543210',
    'template_name' => 'order_shipped',
    'language'      => 'en_US',
    'variables'     => ['1' => 'Amit', '2' => 'ORD-4821']
  ])
]);
$out = json_decode(curl_exec($ch), true);

Python

import os, requests

r = requests.post('https://quickwa.com/api/send-message',
    headers={'X-API-Key': os.environ['QUICKWA_KEY']},
    json={
        'phone_number': '919876543210',
        'template_name': 'order_shipped',
        'language': 'en_US',
        'variables': {'1': 'Amit', '2': 'ORD-4821'},
    }, timeout=20)
r.raise_for_status()

Retrying safely

curl -X POST https://quickwa.com/api/send-message \
  -H "X-API-Key: $QUICKWA_KEY" \
  -H "Idempotency-Key: login-4821-otp" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Response

{
  "success": true,
  "message_id": "wamid.HBgMOTE5ODc2NTQzMjEwFQ...",
  "phone_number": "919876543210",
  "type": "template",
  "status": "sent",
  "conversation_id": 4812,
  "contact_id": 9107
}

Step 5 · Receive webhooks

Every delivery carries these headers

Content-Type:         application/json
X-Event-Type:         whatsapp_webhook
X-Webhook-Signature:  sha256=<HMAC-SHA256 of the raw body, keyed with your secret>

A delivery receipt, as it arrives

{
  "object": "whatsapp_business_account",
  "entry": [{
    "changes": [{
      "field": "messages",
      "value": {
        "statuses": [{
          "id": "wamid.HBgMOTE5...",      // the message_id you stored
          "status": "delivered",          // sent | delivered | read | failed
          "timestamp": "1789714000",
          "recipient_id": "919876543210"
        }]
      }
    }]
  }]
}

An inbound reply, as it arrives

{
  "object": "whatsapp_business_account",
  "entry": [{
    "changes": [{
      "field": "messages",
      "value": {
        "contacts": [{ "profile": { "name": "Amit" }, "wa_id": "919876543210" }],
        "messages": [{
          "from": "919876543210",
          "id": "wamid.HBgM...",
          "timestamp": "1789714050",
          "type": "text",
          "text": { "body": "Yes, please" }
        }]
      }
    }]
  }]
}

Website login OTP — the complete flow

1. Generate the code on your server

   Six digits, random, stored against the phone number with an expiry that matches the code_expiration_minutes in your template. Hash it if you keep it at rest, and rate-limit requests per number so nobody can burn your WhatsApp budget.

2. Send it — the code goes in two places

   An AUTHENTICATION template has a copy-code button, so the code must appear in the body parameter and in the button component. This is the one thing people get wrong.

   POST https://quickwa.com/api/send-message
   X-API-Key: <your key>
   
   {
     "phone_number": "919876543210",
     "template_name": "login_code",
     "language": "en_US",
     "components": [
       { "type": "body",
         "parameters": [ { "type": "text", "text": "483920" } ] },
       { "type": "button", "sub_type": "url", "index": "0",
         "parameters": [ { "type": "text", "text": "483920" } ] }
     ]
   }

   Do not use variables for an OTP. That shorthand only fills the body, so the button is left empty and WhatsApp answers 132000 — Number of parameters does not match.

3. Watch the receipt

   Match the webhook's statuses[].id to the message_id you stored. delivered means it reached the phone. failed arrives with a reason — that is your cue to fall back to SMS rather than leaving the user waiting.

4. Verify what the user types

   Compare against your stored code, in constant time, and delete it once used or expired. QuickWA is never asked and never knows the answer.

Reference · Send a message

Reference · Message types

// plain text
{ "phone_number": "919876543210",
  "message": "Your order has shipped." }

// tappable buttons (max 3)
{ "phone_number": "919876543210",
  "type": "interactive_buttons",
  "body": "Confirm your order?",
  "buttons": [ { "id": "yes", "title": "Confirm" },
                { "id": "no",  "title": "Cancel" } ] }

// a scrollable list menu
{ "phone_number": "919876543210",
  "type": "interactive_list",
  "body": "Pick a service", "button_text": "View",
  "sections": [ { "title": "Services",
                 "rows": [ { "id": "s1", "title": "Site visit" } ] } ] }

// image or document, by public URL
{ "phone_number": "919876543210",
  "type": "document",
  "media_url": "https://your-site.com/invoice.pdf",
  "filename": "Invoice.pdf",
  "caption": "Your invoice" }

Reference · Webhook endpoints

Reference · Event catalogue

Reference · Verify signatures

Node.js / Express

const express = require('express'), crypto = require('crypto');
const SECRET = process.env.QUICKWA_WEBHOOK_SECRET;

app.post('/webhooks/whatsapp',
  express.raw({ type: 'application/json' }),      // raw, NOT express.json()
  (req, res) => {
    const expected = 'sha256=' +
      crypto.createHmac('sha256', SECRET).update(req.body).digest('hex');
    const got = req.get('X-Webhook-Signature') || '';

    if (got.length !== expected.length ||
        !crypto.timingSafeEqual(Buffer.from(got), Buffer.from(expected))) {
      return res.sendStatus(401);
    }

    res.sendStatus(200);                             // acknowledge first
    handle(JSON.parse(req.body.toString()));         // then do the work
  });

PHP

$raw = file_get_contents('php://input');
$expected = 'sha256=' . hash_hmac('sha256', $raw, getenv('QUICKWA_WEBHOOK_SECRET'));
$got = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';

if (!hash_equals($expected, $got)) { http_response_code(401); exit; }

http_response_code(200);
$event = json_decode($raw, true);

Python / Flask

import hmac, hashlib, os
from flask import request, abort

SECRET = os.environ['QUICKWA_WEBHOOK_SECRET'].encode()

@app.post('/webhooks/whatsapp')
def hook():
    expected = 'sha256=' + hmac.new(SECRET, request.get_data(),
                                     hashlib.sha256).hexdigest()
    if not hmac.compare_digest(
            expected, request.headers.get('X-Webhook-Signature', '')):
        abort(401)
    return '', 200

Limits & rules

Errors

{
  "detail": {
    "error":   "WhatsApp API error",
    "code":    132000,
    "message": "Number of parameters does not match the expected number",
    "details": { "messaging_product": "whatsapp" }
  }
}