facebook Skip to main content
Meta Tech BSP · REST API · Webhooks

Business WhatsApp API
Integration & Developer Guide

Architect highly scalable messaging pipelines. Connect to the official WhatsApp Cloud API with our robust REST endpoints, webhook callbacks, sandbox environment, and ready-to-deploy SDKs.

<30 min Integration Time
99.99% API Uptime SLA
JSON Standard Protocol

Platform Architecture

The QuickMessage integration acts as a high-throughput middleware between your SaaS backend and the WhatsApp Cloud API.

1

Authentication

We utilize secure OAuth 2.0 System User access tokens. Generate long-lived Bearer tokens directly from your developer dashboard to authorize all outbound requests.

2

Outbound REST

Send POST requests to our normalized endpoints to trigger messages, upload media, or create templates. We handle rate-limit throttling automatically.

3

Inbound Webhooks

Provide a single HTTPS callback URL. We instantly push JSON payloads for user replies and message status updates (Delivered, Read, Failed) via POST.

Endpoint Reference

Core REST API Documentation

POST
/v1/messages
Send Message API
Dispatch text, images, videos, audio, documents, interactive buttons, or list messages. Requires an active 24-hour session or approved template.
POST
/v1/media
Media Upload API
Upload media securely to Meta servers via multipart/form-data. Returns a media_id for subsequent message API calls.
POST
/v1/templates
Template API
Submit Marketing, Utility, or Authentication templates for Meta review.
POST
/v1/contacts
Contacts API
Verify identity. Check if a phone number holds an active WhatsApp account before initiating bulk campaign sends to preserve quality rating.
POST
/v1/business_profile
Business Profile API
Programmatically update your WhatsApp Business description, address, vertical, email, and websites.
GET
/v1/analytics
Campaign Analytics API
Fetch real-time delivery rates, read receipts, and failure codes for specific campaigns.
Identity API

Programmatically Manage
Your Business Profile

Trust is the highest converting currency in B2B messaging. Utilize the Business Profile API to ensure your public-facing WhatsApp presence dynamically reflects your current service offerings and contact routing.

Strategic API Note

Ensure your payload description builds immediate trust. Explicitly listing "Transparent Pricing" sets the right expectations for high-value leads directly inside the WhatsApp interface.

POST /v1/business_profile
{
  "messaging_product": "whatsapp",
  "about": "B2B SaaS Messaging Platform. Transparent Pricing. High Delivery Rates.",
  "vertical": "PROF",
  "email": "api@quickmessage.in",
  "websites": [
    "https://quickmessage.in"
  ]
}

Official SDK Integrations

Copy, paste, and ship. Code samples are available across major backend stacks.

whatsapp.js Node 18+ · npm i axios
const axios = require("axios");

async function sendInteractiveMessage(to) {
    const payload = {
        messaging_product: "whatsapp",
        recipient_type: "individual",
        to: to,
        type: "interactive",
        interactive: {
            type: "button",
            body: { text: "Did you complete the API integration?" },
            action: {
                buttons: [
                    { type: "reply", reply: { id: "btn_yes", title: "Yes, Done" } },
                    { type: "reply", reply: { id: "btn_no", title: "Need Help" } }
                ]
            }
        }
    };

    try {
        const response = await axios.post(`https://api.quickmessage.in/v1/messages`, payload, {
            headers: { Authorization: `Bearer ${process.env.WA_API_KEY}` }
        });
        return response.data;
    } catch (error) {
        console.error(error.response.data);
    }
}

Webhook Integration &
Security Best Practices

A robust WhatsApp integration relies heavily on processing inbound asynchronous webhooks. You must return a `200 OK` HTTP status within 20 seconds; otherwise, Meta considers the delivery failed and will attempt retries.

Security Critical: Never trust inbound data blindly. Every webhook POST contains an X-Hub-Signature-256 header. You must compute the HMAC-SHA256 signature of the raw payload using your App Secret and validate it matches the header before database ingestion.

Performance Optimization

  • Decouple Processing: Use message queues (BullMQ, RabbitMQ, Kafka) to offload webhook payload ingestion from the actual business logic processing.
  • Idempotency: WhatsApp may occasionally send duplicate webhooks. Use the unique wamid (WhatsApp Message ID) as a unique key in your database to prevent duplicate row entries.
HMAC Validation (Node.js)
const crypto = require('crypto');

function verifyWebhookSignature(req, appSecret) {
    const signature = req.headers['x-hub-signature-256'];
    if (!signature) return false;

    const hmac = crypto.createHmac('sha256', appSecret);
    const digest = Buffer.from(
        'sha256=' + hmac.update(req.rawBody).digest('hex'), 
        'utf8'
    );
    const checksum = Buffer.from(signature, 'utf8');
    
    return crypto.timingSafeEqual(digest, checksum);
}

Testing & Debugging

Before writing production code, map out your JSON schemas and test delivery states.

  • Postman Collection

    Download our complete QuickMessage Postman Collection to hit sandbox endpoints without writing code.

  • Ngrok for Webhooks

    Tunnel Meta's webhooks directly to your localhost:3000 for rapid iteration and testing.

Versioning & API Limits

We maintain strict adherence to Meta's Cloud API limits and versioning requirements.

API Throughput Limits:

  • Maximum API Request rate: 80 requests per second.
  • Exceeding this limit returns HTTP 429 Too Many Requests.

Migration Guide:

Ensure endpoints explicitly declare the version (e.g., /v1/). Deprecation notices are delivered to your admin email 90 days before an endpoint is retired.

Common API Error Codes

130472
User number not on WhatsApp
Fix: Use /contacts endpoint to validate the number before sending.
131047
Session expired (>24h)
Fix: Send an approved template to re-engage the user.
132000
Template not found/approved
Fix: Verify template name, language code, and Meta approval status.
132001
Template hydration error
Fix: Component variable count mismatch. Match JSON parameters to template placeholders exactly.
130429
Rate limit hit
Fix: Implement exponential backoff in your queue. (e.g., bullmq backoff strategy).
190
Invalid OAuth Token
Fix: System User token is invalid or expired. Refresh it from your dashboard.

Developer FAQ

Which HTTP methods are supported?

The REST API strictly requires POST for dispatches (messages, media uploads, templates), GET for data retrieval, and DELETE for media cleanup. Headers must contain application/json.

How do I handle OTP verification?

Create a template with category UTILITY or AUTHENTICATION. Pass the OTP code as a dynamic parameter in the API call. Ensure your server-side logic handles delivery receipts to resend if necessary.

Is there a limit to API Sandbox usage?

Sandbox environments are free and rate-limited strictly for testing (max 5 pre-verified destination phone numbers).

Can I send interactive list messages?

Yes. Set type to "interactive" and build a payload containing up to 10 rows across multiple list sections. Highly effective for e-commerce menu navigation.

Start Building Right Now

Get your free API Key, connect to our sandbox, and dispatch your first WhatsApp message in minutes.

Ready to 10x your customer engagement? Join 3,000+ businesses using QuickMessage

Wait! Here's a Special Gift

Get our exclusive "WhatsApp Marketing Playbook" FREE - 50+ templates & strategies used by top brands

No spam. Unsubscribe anytime.