Developer Integration Guide

How it works

The gateway runs alongside your application and manages one or more WhatsApp connections (called sessions). Each session is an independent WhatsApp account linked via QR code — the same way WhatsApp Web works.

Your app communicates with the gateway over HTTP. Incoming messages are pushed to your app in real time via a webhook URL you register.

Architecture

  Your App
    │
    ├─ POST /send          → sends outbound messages
    ├─ POST /init          → creates a new WhatsApp session
    │
    │                WhatsApp Gateway (this service)
    │                         │
    │                         ↔  WhatsApp Web protocol (Baileys)
    │
    └─ POST {webhookUrl}   ← gateway pushes inbound messages here

Getting credentials

Contact the gateway administrator to receive:

• The gateway base URL (e.g. https://whatsapp.yourdomain.com)
• A session ID for your application (or permission to create one)
• The session API key for that session

Key types

Passing your key

Include the key in every request as an HTTP header. Avoid query-string keys in production — they appear in server logs.

x-api-key: YOUR_SESSION_KEY

Step 1 — Create a session

A session represents a single WhatsApp account. Create one per WhatsApp number you want to connect. You only do this once — sessions persist across server restarts.

POST /init
x-api-key: MASTER_KEY
Content-Type: application/json

{
  "label": "Support Desk"
}

// Response
{
  "success": true,
  "sessionId": "a1b2c3d4"
}Copy

Save the sessionId — you will use it in every subsequent API call. To get the session's API key, call GET /status?sessionId=a1b2c3d4 and read the apiKey field from the response.

Step 2 — Scan the QR code

The polling flow

POST /init
  → { sessionId: "a1b2c3d4" }
          ↓
Poll GET /status?sessionId=a1b2c3d4  (every 2s)
  until status === "WAITING_FOR_SCAN"
          ↓
GET /qr?sessionId=a1b2c3d4
  → { image: "data:image/png;base64,..." }
          ↓
Display QR to user → they scan in WhatsApp → Linked Devices
          ↓
Poll GET /status?sessionId=a1b2c3d4  (every 2s)
  until status === "CONNECTED"
          ↓
Session is live ✓Copy

Complete polling example

const GATEWAY = 'https://whatsapp.yourdomain.com';
const KEY     = process.env.WH_SESSION_KEY;

async function api(method, path, body) {
  const res = await fetch(`${GATEWAY}${path}`, {
    method,
    headers: { 'x-api-key': KEY, 'Content-Type': 'application/json' },
    body: body ? JSON.stringify(body) : undefined,
  });
  return res.json();
}

async function waitForStatus(sessionId, targetStatus, intervalMs = 2000) {
  while (true) {
    const { sessions } = await api('GET', `/status?sessionId=${sessionId}`);
    const status = sessions[sessionId]?.status;
    console.log(`[${sessionId}] status: ${status}`);
    if (status === targetStatus) return;
    if (status === 'DISCONNECTED' || status === 'FAILED') {
      throw new Error(`Session entered terminal state: ${status}`);
    }
    await new Promise(r => setTimeout(r, intervalMs));
  }
}

async function setupSession(label) {
  // 1. Create session
  const { sessionId } = await api('POST', '/init', { label });
  console.log('Created session:', sessionId);

  // 2. Wait until QR is ready
  await waitForStatus(sessionId, 'WAITING_FOR_SCAN');

  // 3. Fetch and display QR — refresh every 30s in case it expires
  let qrInterval = setInterval(async () => {
    const { image } = await api('GET', `/qr?sessionId=${sessionId}`);
    if (image) renderQR(image); // replace this with your UI logic
  }, 30_000);

  const { image } = await api('GET', `/qr?sessionId=${sessionId}`);
  renderQR(image); // show immediately

  // 4. Wait for user to scan
  await waitForStatus(sessionId, 'CONNECTED');
  clearInterval(qrInterval);

  console.log('Session connected:', sessionId);
  return sessionId;
}

// Example: display QR as an  tag
function renderQR(dataUrl) {
  document.getElementById('qr-img').src = dataUrl;
}Copy

import requests, time, os

GATEWAY = 'https://whatsapp.yourdomain.com'
KEY     = os.environ['WH_SESSION_KEY']

def api(method, path, body=None):
    resp = requests.request(
        method, f'{GATEWAY}{path}',
        headers={'x-api-key': KEY},
        json=body,
    )
    return resp.json()

def wait_for_status(session_id, target, interval=2):
    while True:
        data   = api('GET', f'/status?sessionId={session_id}')
        status = data['sessions'][session_id]['status']
        print(f'[{session_id}] status: {status}')
        if status == target:
            return
        if status in ('DISCONNECTED', 'FAILED'):
            raise RuntimeError(f'Session entered terminal state: {status}')
        time.sleep(interval)

def setup_session(label):
    # 1. Create session
    result     = api('POST', '/init', {'label': label})
    session_id = result['sessionId']
    print('Created session:', session_id)

    # 2. Wait for QR
    wait_for_status(session_id, 'WAITING_FOR_SCAN')

    # 3. Fetch QR image (base64 PNG)
    qr_data = api('GET', f'/qr?sessionId={session_id}')
    save_qr(qr_data['image'])   # replace with your display logic
    print('QR saved — scan it in WhatsApp → Linked Devices')

    # 4. Wait for scan (re-fetch QR if it expires before scan)
    deadline = time.time() + 300  # 5 min max
    while True:
        data   = api('GET', f'/status?sessionId={session_id}')
        status = data['sessions'][session_id]['status']
        if status == 'CONNECTED':
            break
        if status == 'WAITING_FOR_SCAN' and time.time() % 30 < 2:
            # Refresh QR every ~30s in case it expired
            qr_data = api('GET', f'/qr?sessionId={session_id}')
            save_qr(qr_data['image'])
        if time.time() > deadline:
            raise TimeoutError('QR not scanned within 5 minutes')
        time.sleep(2)

    print('Session connected:', session_id)
    return session_id

def save_qr(data_url):
    import base64
    img_data = data_url.split(',')[1]
    with open('qr.png', 'wb') as f:
        f.write(base64.b64decode(img_data))
    print('QR written to qr.png')Copy

Fetching the QR image

GET /qr?sessionId=a1b2c3d4
x-api-key: YOUR_KEY

// Response
{
  "success": true,
  "qr":    "2@rawqrstring...",
  "image": "data:image/png;base64,iVBORw0KGgo..."
}Copy

The image field is a data:image/png;base64,… string — set it directly as the src of an <img> tag, or decode the base64 portion and write it to a .png file. On the phone: open WhatsApp → Settings → Linked Devices → Link a Device, then scan.

Session status values

Step 3 — Register your webhook

A webhook is an HTTP endpoint on your server that the gateway calls whenever a message arrives. Register it once per session (it persists in the database).

POST /session/webhook
x-api-key: YOUR_KEY
Content-Type: application/json

{
  "sessionId": "a1b2c3d4",
  "webhookUrl": "https://yourapp.com/whatsapp/incoming"
}

// Response
{ "success": true }Copy

Webhook delivery behaviour

• The gateway POSTs each incoming message to your URL within milliseconds of receipt.
• If your server returns a non-2xx response (or times out after 10s), the gateway retries up to 3 times with a 30-second delay between attempts.
• After 3 failures, the delivery is logged as failed and not retried further.
• Your endpoint must respond with any 2xx status to acknowledge the message.

Step 4 — Receive messages

The gateway POSTs this JSON payload to your webhook URL when a message arrives. The type field tells you exactly what was sent:

{
  "sessionId": "a1b2c3d4",
  "from":      "[email protected]",
  "isGroup":   false,
  "type":      "text",
  "body":      "Hello! I need help with my order.",
  "extra":     null,
  "pushname":  "Arun Kumar",
  "timestamp": 1746355200
}Copy

Extracting the phone number from from

The from field is a WhatsApp JID. To get a plain phone number, strip everything from @ onwards:

// from = "[email protected]"
const phone = payload.from.split('@')[0]; // "919495236004"
const display = '+' + phone;              // "+919495236004"Copy

# from_ = "[email protected]"
phone = payload['from'].split('@')[0]   # "919495236004"
display = '+' + phone                   # "+919495236004"Copy

// $from = "[email protected]"
$phone = explode('@', $payload['from'])[0]; // "919495236004"
$display = '+' . $phone;                    // "+919495236004"Copy

Example webhook server

const express = require('express');
const app = express();
app.use(express.json());

app.post('/whatsapp/incoming', (req, res) => {
  const { sessionId, from, body, pushname, timestamp } = req.body;
  const phone = from.split('@')[0];

  console.log(`[${sessionId}] Message from +${phone} (${pushname}): ${body}`);

  // Your business logic here
  // e.g. store in DB, trigger a reply, etc.

  res.sendStatus(200); // acknowledge — must respond 2xx
});

app.listen(3001, () => console.log('Webhook listening on :3001'));Copy

from flask import Flask, request

app = Flask(__name__)

@app.route('/whatsapp/incoming', methods=['POST'])
def incoming():
    data = request.get_json()
    session_id = data['sessionId']
    phone      = data['from'].split('@')[0]
    body       = data['body']
    pushname   = data['pushname']

    print(f"[{session_id}] From +{phone} ({pushname}): {body}")

    # Your business logic here

    return '', 200  # acknowledge

if __name__ == '__main__':
    app.run(port=3001)Copy

<?php
$payload = json_decode(file_get_contents('php://input'), true);

$sessionId = $payload['sessionId'];
$phone     = explode('@', $payload['from'])[0];
$body      = $payload['body'];
$pushname  = $payload['pushname'];

error_log("[{$sessionId}] From +{$phone} ({$pushname}): {$body}");

// Your business logic here

http_response_code(200);
echo 'OK';Copy

Step 5 — Send messages

All outbound messages go to POST /send. The type of message is determined by which fields are present in the request body.

Send a text message

POST /send
x-api-key: YOUR_KEY
Content-Type: application/json

{
  "sessionId": "a1b2c3d4",
  "to":        "+919495236004",
  "message":   "Hello! Your order #1234 has been shipped."
}

// Response
{
  "success":   true,
  "messageId": "3EB0C1A2B3C4D5E6F7"
}Copy

The to field accepts any common phone number format — the gateway strips all non-digit characters automatically. +919495236004, 919495236004, and +91 94952 36004 all work.

Send an image or video

Provide a publicly accessible URL to the file. URLs ending in .mp4 are sent as video; everything else is sent as an image.

{
  "sessionId": "a1b2c3d4",
  "to":        "+919495236004",
  "mediaUrl":  "https://yourapp.com/receipts/order-1234.jpg",
  "caption":   "Your receipt for order #1234"
}Copy

Send a location pin

{
  "sessionId": "a1b2c3d4",
  "to":        "+919495236004",
  "location": {
    "lat": 9.9312,
    "lng": 76.2673
  }
}Copy

Send a contact card

{
  "sessionId": "a1b2c3d4",
  "to":        "+919495236004",
  "contact": {
    "name":   "Jane Doe",
    "number": "+919495000000"
  }
}Copy

Send to a group

Pass the group's JID as to. You get the group JID from the from field of any incoming group message (isGroup: true).

{
  "sessionId": "a1b2c3d4",
  "to":        "[email protected]",
  "message":   "Hello everyone!"
}

// Response
{ "success": true, "messageId": "3EB0..." }Copy

Replying to an incoming message

To send a reply in the context of an existing conversation, you use the same POST /send with the to field set to the sender's phone number extracted from the webhook payload:

app.post('/whatsapp/incoming', async (req, res) => {
  const { sessionId, from, body } = req.body;
  res.sendStatus(200); // acknowledge first, then process

  if (body.toLowerCase().includes('hello')) {
    await fetch('https://gateway.yourapp.com/send', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': process.env.WH_SESSION_KEY,
      },
      body: JSON.stringify({
        sessionId,
        to: from.split('@')[0], // strip @s.whatsapp.net
        message: 'Hi there! How can I help you today?',
      }),
    });
  }
});Copy

import requests, os

@app.route('/whatsapp/incoming', methods=['POST'])
def incoming():
    data    = request.get_json()
    session = data['sessionId']
    from_   = data['from'].split('@')[0]
    body    = data['body']

    if 'hello' in body.lower():
        requests.post(
            'https://gateway.yourapp.com/send',
            headers={'x-api-key': os.environ['WH_SESSION_KEY']},
            json={
                'sessionId': session,
                'to':        from_,
                'message':   'Hi there! How can I help you today?',
            }
        )

    return '', 200Copy

Full integration flow at a glance

API Reference — Sessions

{ "success": true, "sessionId": "a1b2c3d4" }Copy

{
  "success": true,
  "sessions": {
    "a1b2c3d4": {
      "status":     "CONNECTED",
      "hasQr":      false,
      "info":       { "user": "919495236004", "pushname": "Arun" },
      "webhookUrl": "https://yourapp.com/webhook",
      "apiKey":     "abc123...",
      "label":      "Support Desk"
    }
  }
}Copy

{
  "success": true,
  "qr":    "2@rawqrstring...",
  "image": "data:image/png;base64,..."
}Copy

DELETE /session/a1b2c3d4

{ "success": true }Copy

{ "success": true }Copy

{ "success": true, "apiKey": "new64hexcharstring..." }Copy

API Reference — Send

{ "sessionId": "a1b2c3d4", "to": "+919495236004", "message": "Hello!" }
// → { "success": true, "messageId": "3EB0..." }Copy

{ "sessionId": "a1b2c3d4", "to": "+919495236004", "mediaUrl": "https://yourapp.com/img.jpg", "caption": "See attached" }
// → { "success": true }Copy

{ "sessionId": "a1b2c3d4", "to": "+919495236004", "location": { "lat": 9.9312, "lng": 76.2673 } }
// → { "success": true }Copy

{ "sessionId": "a1b2c3d4", "to": "+919495236004", "contact": { "name": "Jane Doe", "number": "+919495000000" } }
// → { "success": true }Copy

API Reference — Webhook payload

Every inbound message triggers a POST to your registered webhook URL. The payload always includes a type field so your app knows exactly what was received.

Base fields (all message types)

{
  "sessionId": "a1b2c3d4",
  "from":      "[email protected]",
  "isGroup":   false,
  "type":      "text",
  "body":      "Hello! I need help with my order.",
  "extra":     null,
  "pushname":  "Arun Kumar",
  "timestamp": 1746355200
}Copy

Message types & their extra fields

Example payloads by type

Image with caption

{
  "type":  "image",
  "body":  "Here is my receipt",
  "extra": { "mimetype": "image/jpeg" }
}Copy

Voice note

{
  "type":  "audio",
  "body":  "",
  "extra": { "mimetype": "audio/ogg; codecs=opus", "isVoiceNote": true, "seconds": 12 }
}Copy

Location pin

{
  "type":  "location",
  "body":  "Kochi Airport",
  "extra": { "lat": 9.9442, "lng": 76.2699, "address": "Nedumbassery, Kerala" }
}Copy

Emoji reaction

{
  "type":  "reaction",
  "body":  "👍",
  "extra": { "targetMessageId": "3EB0ABC123..." }
}Copy

Handling by type in your webhook

app.post('/whatsapp/incoming', async (req, res) => {
  res.sendStatus(200);
  const { sessionId, from, type, body, extra, pushname } = req.body;
  const phone = from.split('@')[0];

  switch (type) {
    case 'text':
      await handleText(phone, body);
      break;

    case 'image':
    case 'video':
      await send(sessionId, phone, `Thanks ${pushname}, we received your ${type}${body ? ': ' + body : ''}.`);
      break;

    case 'audio':
      const dur = extra?.seconds ? `(${extra.seconds}s)` : '';
      await send(sessionId, phone, `We got your voice note ${dur}. For faster help, please type your query.`);
      break;

    case 'location':
      await handleLocation(phone, extra.lat, extra.lng);
      break;

    case 'document':
      await send(sessionId, phone, `Received your file: ${body || extra?.fileName}. We'll review it shortly.`);
      break;

    case 'reaction':
      console.log(`${pushname} reacted with ${body}`);
      break;

    case 'button_reply':
    case 'list_reply':
      await handleMenuSelection(phone, body, extra?.selectedId);
      break;

    default:
      await send(sessionId, phone, `Hi ${pushname}! We received your message but couldn't read it. Please type your query.`);
  }
});Copy

@app.route('/whatsapp/incoming', methods=['POST'])
def incoming():
    data     = request.get_json()
    session  = data['sessionId']
    phone    = data['from'].split('@')[0]
    type_    = data['type']
    body     = data['body']
    extra    = data.get('extra') or {}
    pushname = data['pushname']

    if type_ == 'text':
        handle_text(phone, body)

    elif type_ in ('image', 'video'):
        caption = f': {body}' if body else ''
        send(session, phone, f'Thanks {pushname}, we received your {type_}{caption}.')

    elif type_ == 'audio':
        dur = f"({extra.get('seconds')}s)" if extra.get('seconds') else ''
        send(session, phone, f'We got your voice note {dur}. Please type your query for faster help.')

    elif type_ == 'location':
        handle_location(phone, extra['lat'], extra['lng'])

    elif type_ == 'document':
        name = body or extra.get('fileName', 'file')
        send(session, phone, f'Received your file: {name}. We\'ll review it shortly.')

    elif type_ == 'reaction':
        print(f'{pushname} reacted with {body}')

    elif type_ in ('button_reply', 'list_reply'):
        handle_menu_selection(phone, body, extra.get('selectedId'))

    else:
        send(session, phone, f'Hi {pushname}! Please type your query so we can help you.')

    return '', 200Copy

API Reference — Logs

{
  "success": true,
  "logs": [
    { "id": 42, "session_id": "a1b2c3d4", "event": "CONNECTED", "reason": null, "timestamp": "2026-06-01 08:00:00" }
  ]
}Copy

{
  "success": true,
  "webhooks": [
    {
      "id": 7, "session_id": "a1b2c3d4",
      "endpoint":   "https://yourapp.com/webhook",
      "event_type": "INCOMING",
      "payload":    "{...}",
      "status_code": 200,
      "timestamp":  "2026-06-01 08:01:00"
    }
  ]
}Copy

{ "ok": true }Copy

API Reference — Errors

All error responses share this shape:

{ "success": false, "error": "Human-readable description" }Copy

Handling errors in code

const res = await fetch(`${GATEWAY}/send`, {
  method: 'POST',
  headers: { 'x-api-key': KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({ sessionId, to, message }),
});

const data = await res.json();

if (!data.success) {
  console.error('Send failed:', data.error);
  // handle: session disconnected? retry? alert?
  return;
}

console.log('Sent, messageId:', data.messageId);Copy

import requests

resp = requests.post(
    f'{GATEWAY}/send',
    headers={'x-api-key': KEY},
    json={'sessionId': session_id, 'to': to, 'message': message},
)
data = resp.json()

if not data.get('success'):
    print('Send failed:', data.get('error'))
    # handle: session disconnected? retry? alert?
else:
    print('Sent, messageId:', data.get('messageId'))Copy

Common integration issues