WhatsApp Manager - API Documentation

Authentication

All private endpoints under /api/sessions and /api/messages require a secure JWT authorization token. Send the token in the Authorization header of your HTTP request.

🔑 Your API Token

Here is your current API authorization token. Copy this token to authenticate your REST calls:

Loading token...

GET /api/token Public

Retrieve the application authorization token securely. Mostly used inside local admin integrations.

Response (200 OK)

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

List Sessions

Fetch all active, inactive, and registering WhatsApp sessions in the database.

GET /api/sessions Requires Token

Response (200 OK)

{
  "success": true,
  "sessions": [
    {
      "sessionId": "qr_1781332832910_5eab537f",
      "mobid": "726757093511112",
      "mobile_number": "917012729389",
      "status": "READY",
      "createdAt": "2026-06-26T06:00:00.000Z"
    }
  ]
}

Official Client SDK Kits & Downloads

Download ready-to-use SDK classes and Postman Collections pre-configured for your domain. Each SDK encapsulates authorization token handling, JSON payload construction, and error parsing for instant integration.

PHP SDK Client

cURL wrapper for PHP 7.4+

Node.js SDK

Native Fetch helper for Node & Browser

Python SDK

Requests wrapper for Python 3.x

Postman Collection

Ready-to-import REST collection v2.1

Prefer the full interactive developer manual with live execution testing? Open Full Developer API Guide

Create Session

Initialize a brand-new WhatsApp connection flow in the manager.

POST /api/sessions Requires Token

Request Body (JSON)

Field	Type	Requirement	Description
name	string	Optional	A custom name label for the session.
method	string	Optional	Linkage method. Use `"qr"` (default) or `"phone"`.

Response (201 Created)

{
  "success": true,
  "message": "Session initialized",
  "session": {
    "sessionId": "qr_1782473171252_bb1a0195",
    "status": "REGISTERING",
    "method": "qr"
  }
}

Session Info

Get current health, database info, and settings of a single session.

GET /api/sessions/:sessionId Requires Token

URL Parameters

Param	Type	Description
:sessionId	string	The unique ID of the session (e.g., `qr_1781332832910_5eab537f`).

Response (200 OK)

{
  "success": true,
  "session": {
    "sessionId": "qr_1781332832910_5eab537f",
    "mobid": "726757093511112",
    "mobile_number": "917012729389",
    "status": "READY",
    "method": "qr"
  }
}

Delete Session

Logs out the session, deletes session auth files locally, and marks the database status as inactive.

DELETE /api/sessions/:sessionId Requires Token

Response (200 OK)

{
  "success": true,
  "message": "Session deleted and logged out successfully"
}

Usage & Credit Limits API

Check message quota limits, real-time usage counts, and remaining available credits for any connected WhatsApp number, mobid, or session ID.

GET /api/sessions/usage/:identifier Requires Token

Get real-time usage statistics and remaining quota for a specific sender. The parameter :identifier accepts a WhatsApp mobile number (e.g. 9890000000), mobid, or sessionId.

Response (200 OK)

{
  "success": true,
  "identifier": "9890000000",
  "sessionId": "qr_1781332832910_5eab537f",
  "mobid": "384729105638274",
  "mobile_number": "9890000000",
  "session_name": "Sales WhatsApp",
  "usage": 150,
  "limit": 1000,
  "remaining": 850,
  "status": "READY",
  "dbStatus": "active"
}

GET /api/sessions/usage/all Requires Token

Get usage counters and credit limits for all registered sessions at once.

Response (200 OK)

{
  "success": true,
  "totalSessions": 2,
  "sessions": [
    {
      "sessionId": "qr_1781332832910_5eab537f",
      "mobid": "384729105638274",
      "mobile_number": "9890000000",
      "session_name": "Sales WhatsApp",
      "usage": 150,
      "limit": 1000,
      "remaining": 850,
      "status": "READY",
      "dbStatus": "active"
    }
  ]
}

Lead Scrapper API

Extract real contact numbers from active WhatsApp sessions and export them directly to CSV, Google Sheets, or MySQL database tables.

GET /api/sessions/contacts/scrape Requires Token

Extract clean, real phone numbers from connected WhatsApp accounts (automatically filters out group JIDs and system LIDs).

Query Param	Type	Requirement	Description
sessionIds	string	Optional	Comma-separated session IDs to extract from. If omitted, extracts from all active sessions.
mobile	string	Optional	Target connected phone number (e.g. `919876543210`) to extract leads specifically from that number.

Response (200 OK)

{
  "success": true,
  "totalScraped": 45,
  "targetSessions": ["WAMAX-QR-20260815184502-389"],
  "contacts": [
    {
      "phone_number": "919890000000",
      "formatted_number": "+91 98900 00000",
      "name": "Rahul Sharma",
      "session_id": "WAMAX-QR-20260815184502-389",
      "extracted_at": "2026-08-15T18:40:00.000Z"
    }
  ]
}

POST /api/sessions/contacts/export Requires Token

Export extracted lead contacts into CSV file, Google Sheet, or MySQL database table.

Body Field	Type	Requirement	Description
exportType	string	Required	Choice of export destination: `"csv"`, `"googlesheet"`, or `"mysql"`.
sessionIds	array / string	Optional	List or comma-separated session IDs to extract leads from.
mobile	string	Optional	Filter leads by specific connected WhatsApp mobile number.

cURL Example (Export to MySQL)

curl -X POST "https://socket.wamax.in/api/sessions/contacts/export" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "exportType": "mysql"
  }'

Send Message

Send text messages, images, documents, audio, videos, or push-to-talk voice notes through any connected session.

POST /api/messages/send Requires Token

Request Body (JSON)

Field	Type	Requirement	Description
sessionId	string	Required	The active session ID.
to	string	Required	Phone number with country code (e.g. `"919846303025"`).
type	string	Required	Message type: `"text"`, `"image"`, `"pdf"`, `"document"`, `"audio"`, `"video"`, `"voice"`, `"template"`.
text	string	Optional	Message content. Required for `text`.
url	string	Optional	Public URL of media file (Required for image, pdf, video, and voice notes).
caption	string	Optional	Media text caption (for image or video).
fileName	string	Optional	Custom filename for PDF/document attachments (e.g. `"invoice_2026.pdf"`).
duration	number	Optional	Audio playback duration in seconds for voice notes (e.g. `12`). Default: `5`.
params	array	Optional	Replacement values for template placeholders `{{1}}`, `{{2}}`, etc.

📱 Message Type Examples

1

Send Text Message

type: "text"

Send a plain text message to any WhatsApp number.

curl -X POST "https://socket.wamax.in/api/messages/send" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "qr_1781332832910_5eab537f",
    "to": "918281885620",
    "type": "text",
    "text": "Hello! Welcome to WaMax API 🚀"
  }'

2

Send Image

type: "image"

Send a direct image from any public URL. No caption attached.

curl -X POST "https://socket.wamax.in/api/messages/send" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "qr_1781332832910_5eab537f",
    "to": "918281885620",
    "type": "image",
    "url": "https://wamax.in/assets/images/logo.png"
  }'

3

Send Image with Caption

type: "image"

Image with a text caption displayed below the image in the chat.

curl -X POST "https://socket.wamax.in/api/messages/send" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "qr_1781332832910_5eab537f",
    "to": "918281885620",
    "type": "image",
    "url": "https://wamax.in/assets/images/promo-banner.jpg",
    "caption": "🎉 Summer Sale is LIVE! Get 50% off on all products. Shop now at wamax.in"
  }'

4

Send PDF / Document

type: "pdf"

Send a PDF or document file with a custom filename that the recipient sees.

curl -X POST "https://socket.wamax.in/api/messages/send" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "qr_1781332832910_5eab537f",
    "to": "918281885620",
    "type": "pdf",
    "url": "https://wamax.in/assets/docs/invoice_june_2026.pdf",
    "fileName": "Invoice_June_2026.pdf"
  }'

5

Send Audio File

type: "audio"

Send an audio file (MP3, OGG, etc.) as a standard audio attachment.

curl -X POST "https://socket.wamax.in/api/messages/send" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "qr_1781332832910_5eab537f",
    "to": "918281885620",
    "type": "audio",
    "url": "https://wamax.in/assets/audio/welcome-greeting.mp3"
  }'

6

Send Voice Note (From URL)

type: "voice"

Send an audio file (MP3, OGG, WAV) from a public URL as a push-to-talk voice note.

curl -X POST "https://socket.wamax.in/api/messages/send" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "qr_1781332832910_5eab537f",
    "to": "918281885620",
    "type": "voice",
    "url": "https://wamax.in/assets/audio/welcome-greeting.mp3",
    "duration": 5
  }'

7

Send Template Message

type: "template"

Send a pre-defined template stored in your database. Use params to replace placeholders like {{1}}, {{2}}.

curl -X POST "https://socket.wamax.in/api/messages/send" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "qr_1781332832910_5eab537f",
    "to": "918281885620",
    "type": "template",
    "text": "order_confirmation",
    "params": ["Sheffin", "ORD-20260628", "₹1,299"]
  }'

8

Send via MobID (Cloud API Format)

/:mobid/messages

Use the MobID (unique DB identifier) as the sender instead of sessionId. The Cloud API endpoint at /api/messages/:phoneNumberId/messages auto-resolves mobid → mobile_number → session_id. This is ideal for CRM integrations where the sender is identified by their MobID.

# Replace 384729105638274 with your actual MobID from the database
curl -X POST "https://socket.wamax.in/api/messages/384729105638274/messages" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "to": "918281885620",
    "type": "text",
    "text": {
      "body": "Hello! Sent using MobID as sender identifier 🚀"
    }
  }'

# Image via MobID
curl -X POST "https://socket.wamax.in/api/messages/384729105638274/messages" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "to": "918281885620",
    "type": "image",
    "image": {
      "link": "https://wamax.in/assets/images/logo.png",
      "caption": "Sent via MobID 📱"
    }
  }'

# Document via MobID
curl -X POST "https://socket.wamax.in/api/messages/384729105638274/messages" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "to": "918281885620",
    "type": "document",
    "document": {
      "link": "https://wamax.in/assets/docs/invoice.pdf",
      "filename": "Invoice_June_2026.pdf"
    }
  }'

9

Media Upload & Send (Single-Step Multipart)

POST /upload-send

Upload a local media file (PDF, Image, Document, Audio, or Video) and send it immediately to a recipient. The API automatically saves the file to a public directory, generates a public URL, dispatches the WhatsApp message, and schedules secure file deletion after a 5-second delay to conserve system storage.

Supports both standard format (using sessionId, mobid, or phoneNumberId in multipart fields) and Cloud API format (using :phoneNumberId in the URL path).

# 1. Standard Multipart Upload & Send (using sessionId in form fields)
curl -X POST "https://socket.wamax.in/api/messages/upload-send" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@/path/to/invoice.pdf" \
  -F "to=918281885620" \
  -F "sessionId=YOUR_SESSION_ID" \
  -F "type=pdf" \
  -F "caption=Here is your PDF invoice" \
  -F "fileName=Invoice_June_2026.pdf"

# 2. Cloud API-style Multipart Upload & Send (using MobID in URL path)
curl -X POST "https://socket.wamax.in/api/messages/YOUR_MOBID_HERE/upload-send" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@/path/to/image.png" \
  -F "to=918281885620" \
  -F "caption=Stunning promotional image!"

# Note: If "type" is omitted, it will be automatically detected from the uploaded file's mimetype.
# Files are securely removed from the server 5 seconds after message dispatch.

🔧 SDK Examples (General)

# Send image with caption
curl -X POST "https://socket.wamax.in/api/messages/send" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "YOUR_SESSION_ID",
    "to": "918281885620",
    "type": "image",
    "url": "https://wamax.in/assets/images/logo.png",
    "caption": "Check out our latest update!"
  }'

const fetch = require('node-fetch');

const BASE_URL = 'https://socket.wamax.in';
const TOKEN    = 'YOUR_TOKEN';

async function sendWhatsApp(sessionId, to, type, payload) {
  const response = await fetch(`${BASE_URL}/api/messages/send`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${TOKEN}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ sessionId, to, type, ...payload })
  });
  return response.json();
}

// Text message
await sendWhatsApp('YOUR_SESSION', '918281885620', 'text', {
  text: 'Hello from Node.js!'
});

// Image + caption
await sendWhatsApp('YOUR_SESSION', '918281885620', 'image', {
  url: 'https://wamax.in/assets/images/logo.png',
  caption: 'Our latest product launch 🚀'
});

// PDF document
await sendWhatsApp('YOUR_SESSION', '918281885620', 'pdf', {
  url: 'https://wamax.in/assets/docs/invoice.pdf',
  fileName: 'Invoice_June_2026.pdf'
});

// Template with params
await sendWhatsApp('YOUR_SESSION', '918281885620', 'template', {
  text: 'order_confirmation',
  params: ['Sheffin', 'ORD-20260628', '₹1,299']
});

import requests

BASE_URL = "https://socket.wamax.in"
TOKEN    = "YOUR_TOKEN"
HEADERS  = {
    "Authorization": f"Bearer {TOKEN}",
    "Content-Type": "application/json"
}

def send_whatsapp(session_id, to, msg_type, **kwargs):
    payload = {"sessionId": session_id, "to": to, "type": msg_type, **kwargs}
    r = requests.post(f"{BASE_URL}/api/messages/send", json=payload, headers=HEADERS)
    return r.json()

# Text message
send_whatsapp("YOUR_SESSION", "918281885620", "text",
              text="Hello from Python!")

# Image + caption
send_whatsapp("YOUR_SESSION", "918281885620", "image",
              url="https://wamax.in/assets/images/logo.png",
              caption="Our latest product launch 🚀")

# PDF document
send_whatsapp("YOUR_SESSION", "918281885620", "pdf",
              url="https://wamax.in/assets/docs/invoice.pdf",
              fileName="Invoice_June_2026.pdf")

# Voice note (URL)
send_whatsapp("YOUR_SESSION", "918281885620", "voice",
              url="https://wamax.in/assets/audio/welcome-greeting.mp3",
              duration=5)

# Template with params
send_whatsapp("YOUR_SESSION", "918281885620", "template",
              text="order_confirmation",
              params=["Sheffin", "ORD-20260628", "₹1,299"])

Meta Cloud API Compatible Format

This manager features a drop-in replacement endpoint matching Facebook's official WhatsApp Cloud API structure. You can route existing CRM plugins and software directly to this local endpoint by replacing the Facebook API base URL with your server address.

POST /api/messages/:phoneNumberId/messages Requires Token

The parameter :phoneNumberId in the URL identifies the sender. It can be any of these three values — the server resolves them automatically:

Identifier	Type	Example	Description
mobid	string	`384729105638274`	Unique 15-digit database identifier. Recommended
mobile_number	string	`918281885620`	The WhatsApp phone number of the connected session.
session_id	string	`qr_1781332832910_5eab537f`	The internal session ID (fallback).

Text Message via MobID

curl -X POST "https://socket.wamax.in/api/messages/384729105638274/messages" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "to": "918281885620",
    "type": "text",
    "text": {
      "body": "Hello from Cloud API via MobID!"
    }
  }'

Image with Caption via MobID

curl -X POST "https://socket.wamax.in/api/messages/384729105638274/messages" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "to": "918281885620",
    "type": "image",
    "image": {
      "link": "https://wamax.in/assets/images/promo-banner.jpg",
      "caption": "🎉 Limited offer! 50% off today only."
    }
  }'

Document via MobID

curl -X POST "https://socket.wamax.in/api/messages/384729105638274/messages" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "to": "918281885620",
    "type": "document",
    "document": {
      "link": "https://wamax.in/assets/docs/invoice.pdf",
      "filename": "Invoice_June_2026.pdf"
    }
  }'

Template via MobID

curl -X POST "https://socket.wamax.in/api/messages/384729105638274/messages" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "to": "918281885620",
    "type": "template",
    "template": {
      "name": "order_confirmation",
      "components": [
        {
          "type": "body",
          "parameters": [
            { "type": "text", "text": "Sheffin" },
            { "type": "text", "text": "ORD-20260628" },
            { "type": "text", "text": "₹1,299" }
          ]
        }
      ]
    }
  }'

Response (Meta Cloud API Format)

{
  "messaging_product": "whatsapp",
  "contacts": [
    {
      "input": "918281885620",
      "wa_id": "918281885620"
    }
  ],
  "messages": [
    {
      "id": "wamid.HBgLOTE5ODQ2MzAzMDI1FQIAERg2Q..."
    }
  ]
}

⚡ Developer Playground

Send a live API test request directly from your browser to your running server!

Target Session

Recipient Number

Message Body

Response Output

No request sent yet. Click "Send Test Message" to execute.

WaMax

WaMax

Active Sessions

API Documentation

Getting Started

Sessions API

Usage & Leads API

Messages API

Authentication

🔑 Your API Token

Response (200 OK)

List Sessions

Response (200 OK)

Official Client SDK Kits & Downloads

PHP SDK Client

Node.js SDK

Python SDK

Postman Collection

Create Session

Request Body (JSON)

Response (201 Created)

Session Info

URL Parameters

Response (200 OK)

Delete Session

Response (200 OK)

Usage & Credit Limits API

Response (200 OK)

Response (200 OK)

Lead Scrapper API

Response (200 OK)

cURL Example (Export to MySQL)

Send Message

Request Body (JSON)

📱 Message Type Examples

Send Text Message

Send Image

Send Image with Caption

Send PDF / Document

Send Audio File

Send Voice Note (From URL)

Send Template Message

Send via MobID (Cloud API Format)

Media Upload & Send (Single-Step Multipart)

🔧 SDK Examples (General)

Meta Cloud API Compatible Format

Text Message via MobID

Image with Caption via MobID

Document via MobID

Template via MobID

Response (Meta Cloud API Format)

⚡ Developer Playground