WaMax

Parameter	Type	Presence	Description
key / apiKey	string	Required*	API Key or Authorization Token (e.g. `?key=deb884555a0fcb9659a707794f27a4ed366e1fe61538e5892f93eff2`). Alternatively send Bearer header.
phone / number	string	Optional	Target WhatsApp sender phone number (e.g. `8304064190` or `918304064190`).
sessionId	string	Optional	WhatsApp session ID (e.g. `qr_1781332832910_5eab537f`).
type	string	Optional	Filter direction: `"inbound"` (incoming only), `"outbound"`, or `"all"` (default).
limit	number	Optional	Max messages to retrieve. Default is `50`.

Real-Time SSE Stream (Pure Extractor)

Stream real-time incoming WhatsApp messages directly into client CRM or custom applications using Server-Sent Events (SSE). Zero webhook server setup required. Zero polling. 100% isolated to the client's session.

STREAM /api/public/portal/:portalToken/stream Uses Portal Token

Connection Headers

Accept: text/event-stream
Cache-Control: no-cache
Connection: keep-alive

Real-Time Event Stream Payload (JSON)

{
  "event": "message:inbound",
  "sessionId": "918281885620",
  "sender": "919400464190",
  "sender_name": "Rahul",
  "type": "audio",
  "message": "[Voice Message]",
  "timestamp": 1724982930000,
  "media": {
    "hasMedia": true,
    "mediaType": "audio",
    "mediaUrl": "https://api.whatsapp.wywk.in/mediauploads/voice_918281885620_1724982930.ogg",
    "stt_transcription": "നാളെ പത്തു മണിക്ക് ഒരു കൺസൾട്ടേഷൻ ബുക്ക് ചെയ്യാൻ സാധിക്കുമോ?",
    "confidence": "98%",
    "ocr_text": null
  }
}

JavaScript Connection Example

const stream = new EventSource('https://api.whatsapp.wywk.in/api/public/portal/prt_8458cea4ded89295a4977fed/stream');

stream.onmessage = (event) => {
    const payload = JSON.parse(event.data);
    if (payload.event === 'message:inbound') {
        console.log(`📩 New message from ${payload.sender_name} (${payload.sender}):`, payload.message);
        if (payload.media && payload.media.stt_transcription) {
            console.log('🎙️ Voice Transcription (STT):', payload.media.stt_transcription);
        }
    }
};

Enriched Live Messages Feed (REST)

Batch query the latest inbound or outbound messages for a tenant, including Deepgram Speech-to-Text transcripts, OCR text, and media attachments.

GET /api/public/portal/:portalToken/live-messages Uses Portal Token

Query Parameters

Parameter	Type	Status	Description
type	string	Optional	Filter direction: `"inbound"` (default incoming), `"outbound"`, or `"all"`.
msgType	string	Optional	Filter message kind: `"text"`, `"audio"`, `"image"`, `"document"`.
limit	number	Optional	Number of messages to retrieve (e.g. `50`).

Example URL Request

GET https://api.whatsapp.wywk.in/api/public/portal/prt_8458cea4ded89295a4977fed/live-messages?type=inbound&limit=25

Pure Message Extractor Mode (Disable AI Replies)

Turn off automated AI bot responses so your custom backend has 100% control over conversation replies, while WaMax continues to extract and stream all incoming messages.

POST /api/public/portal/:portalToken/toggle-bot Uses Portal Token

Request Body (JSON)

{
  "enabled": false
}

Response (200 OK)

{
  "success": true,
  "message": "AI Assistant is now PAUSED (Pure Extractor Mode)",
  "enabled": false
}

Dynamic UPI Payment Deep-Link & QR

Generate instant UPI deep links (GPay, PhonePe, Paytm) and high-resolution dynamic QR codes for client billing or advance booking fee collection.

POST /api/public/portal/:portalToken/generate-upi Uses Portal Token

Request Body (JSON)

{
  "amount": 800,
  "bookingId": "BKG-2026-9041",
  "customerName": "Rahul"
}

Response (200 OK)

{
  "success": true,
  "upi_id": "mindtune@okaxis",
  "upi_name": "Mind Tune Clinic",
  "amount": 800,
  "booking_id": "BKG-2026-9041",
  "upi_uri": "upi://pay?pa=mindtune@okaxis&pn=Mind%20Tune%20Clinic&am=800&tn=BKG-2026-9041&cu=INR",
  "qr_image_url": "https://api.qrserver.com/v1/create-qr-code/?size=300x300&data=upi://pay...",
  "gpay_deep_link": "upi://pay?pa=mindtune@okaxis&pn=Mind%20Tune%20Clinic&am=800&tn=BKG-2026-9041&cu=INR"
}

Rumik AI Multilingual Malayalam TTS

Synthesize ultra-realistic Malayalam and multilingual speech with natural voice timbre and tone tags using Rumik AI Silk TTS Engine.

POST /api/public/portal/:portalToken/synthesize-voice Uses Portal Token

Request Body (JSON)

{
  "text": "നമസ്കാരം, താങ്കളുടെ ബുക്കിംഗ് Mind Tune Clinic-ൽ വിജയകരമായി രേഖപ്പെടുത്തിയിട്ടുണ്ട്.",
  "provider": "rumik",
  "model": "mulberry",
  "speaker": "siya",
  "lang": "ml"
}

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"
    }
  ]
}

Multi-Engine AI Architecture & Multimodal Processing

High-availability, zero-downtime AI fallback pipeline with key rotation

Key Rotation Engine

Rotates up to 100 Gemini API keys (using models gemini-3.1-flash-lite, gemini-2.5-flash, etc.) automatically upon quota or rate limit exhaustion.

Puter.js Integration

Zero-cost unlimited multimodal analysis pipeline for large PDF documents, images, video files, and structured text summaries without external API limits.

Deepgram Speech Engine

Automatic voice message transcription (Speech-to-Text) and natural voice audio creation (Text-to-Speech via Deepgram Aura) for inbound voice notes.

OpenRouter Fallback

Redundant failover layer connecting open-source free tier models via OpenRouter (sk-or-v1-*) to ensure continuous chatbot availability.

AI Telemetry & Usage Analytics API

Track real-time AI consumption per session/mobid including vision analysis, document OCR & summary, audio transcription counts, total messages, and remaining credit allocation.

GET /api/v1/usage/stats Requires Token

Fetch aggregated AI usage metrics and breakdowns across all active WhatsApp numbers.

Response (200 OK)

{
  "success": true,
  "stats": {
    "totalSessions": 5,
    "totalAiCalls": 142,
    "totalDocAnalyses": 38,
    "totalAudioTranscriptions": 29,
    "totalMessages": 4510
  },
  "sessions": [
    {
      "mobid": "918281885620",
      "mobile_number": "+91 82818 85620",
      "aiUsageCount": 42,
      "docAnalysisCount": 12,
      "audioTranscribeCount": 8,
      "totalMessages": 1250,
      "totalCreditsUsed": 62
    }
  ]
}

GET /api/v1/usage/:mobid Requires Token

Fetch precise AI telemetry counters for a single sender using mobid or mobile number.

Response (200 OK)

{
  "success": true,
  "usage": {
    "mobid": "918281885620",
    "aiUsageCount": 42,
    "docAnalysisCount": 12,
    "audioTranscribeCount": 8,
    "totalMessages": 1250,
    "totalCreditsUsed": 62
  }
}

AI Chatbot & Dynamic Brain Engine API

Configure intelligent WhatsApp auto-replies powered by session-isolated knowledge bases (brain.json), system personas (prompt.json), automated flow rules, and a 3-tier multi-engine AI pipeline (Gemini Pro/Flash → OpenRouter Fallback Pool → Puter.js Serverless).

Architecture & Execution Lifecycle

When an inbound WhatsApp message arrives, the WaMax engine executes the following evaluation pipeline:

Rule Engine Check: Evaluates active static rules for matching exact, contains, or regex triggers. If matched, responds instantly without consuming AI credits.
AI Fallback Gate: If no rule matches and the session chatbot is enabled, routes the query to the AI engine.
Dynamic Brain & Persona Injection: Loads session-specific brain_<sessionKey>.json (or brain_global.json) and prompt_<sessionKey>.json (or prompt_global.json) to provide accurate domain context (e.g., clinic doctor schedules, fees, slot booking logic).
3-Tier Model Execution: Rotates through Gemini API keys, failing over to OpenRouter (100 free/paid key pool) and Puter.js if quota limits occur.
Telemetry & Webhook Dispatch: Logs token usage in usageStore.js and dispatches full payload to configured client Webhook.

POST /api/v1/chatbot/toggle Requires Token

Dynamically activate or pause auto-reply chatbot flows for a specific session number or globally.

Request Body (JSON)

{
  "mobid": "918281885620",
  "enabled": true
}

Response Example

{
  "status": "success",
  "message": "Chatbot set to enabled for 918281885620",
  "sessionKey": "918281885620",
  "enabled": true
}

GET POST /api/v1/chatbot/brain Requires Token

GET: Fetch the active JSON knowledge base (brain.json) stored for a session or global instance.
POST: Upload dynamic knowledge base directly via raw JSON or synchronize remotely via a public URL (e.g., hosted on GitHub, S3, or your CMS).

Fetch Active Brain (GET)

curl -X GET "https://socket.wamax.in/api/v1/chatbot/brain?sessionKey=918281885620" \
  -H "Authorization: Bearer YOUR_TOKEN"

Upload Direct JSON Payload (POST)

curl -X POST "https://socket.wamax.in/api/v1/chatbot/brain" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionKey": "918281885620",
    "brainData": {
      "businessName": "CarePlus Medical Clinic",
      "location": "MG Road, Kochi, Kerala",
      "contactPhone": "+91-9876543210",
      "doctors": [
        {
          "name": "Dr. Sarah Jenkins",
          "specialization": "Cardiologist",
          "consultationFee": "₹700",
          "availableDays": ["Monday", "Wednesday", "Friday"],
          "slots": ["10:00 AM", "11:30 AM", "04:00 PM"]
        },
        {
          "name": "Dr. Rajesh Kumar",
          "specialization": "Pediatrician",
          "consultationFee": "₹500",
          "availableDays": ["Tuesday", "Thursday", "Saturday"],
          "slots": ["09:00 AM", "02:30 PM", "06:00 PM"]
        }
      ],
      "bookingInstructions": "Collect patient full name, age, preferred doctor, and slot time before confirming."
    }
  }'

Synchronize from Public URL (POST)

curl -X POST "https://socket.wamax.in/api/v1/chatbot/brain" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionKey": "918281885620",
    "brainUrl": "https://raw.githubusercontent.com/your-org/clinic-config/main/brain.json"
  }'

GET POST /api/v1/chatbot/prompt Requires Token

GET: Retrieve current system persona instructions (prompt.json) for a session key.
POST: Set or update system persona instructions defining bot identity, tone, language, and behavior rules.

Fetch Active Persona (GET)

curl -X GET "https://socket.wamax.in/api/v1/chatbot/prompt?sessionKey=918281885620" \
  -H "Authorization: Bearer YOUR_TOKEN"

Direct Persona Instructions (POST)

curl -X POST "https://socket.wamax.in/api/v1/chatbot/prompt" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionKey": "918281885620",
    "prompt": "You are CarePlus Assistant, an empathetic medical receptionist for CarePlus Clinic. Use the uploaded brain knowledge base to answer doctor availability, fees, and appointment bookings. Always maintain a polite and professional tone. Respond in English or Malayalam based on user language."
  }'

Synchronize Persona from Remote URL (POST)

curl -X POST "https://socket.wamax.in/api/v1/chatbot/prompt" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionKey": "918281885620",
    "promptUrl": "https://raw.githubusercontent.com/your-org/clinic-config/main/prompt.json"
  }'

GET /api/v1/chatbot/templates/clinic Optional Token

Download standard pre-built Clinic Booking brain.json and prompt.json template payload structure.

curl -X GET "https://socket.wamax.in/api/v1/chatbot/templates/clinic"

GET POST DELETE /api/v1/chatbot/rules Requires Token

GET: List all configured auto-reply rules for a session or globally.
POST: Add a new keyword or regex auto-reply rule.
DELETE: Remove a rule by ID (e.g. DELETE /api/v1/chatbot/rules/:id).

Fetch Active Rules (GET)

curl -X GET "https://socket.wamax.in/api/v1/chatbot/rules?mobid=918281885620" \
  -H "Authorization: Bearer YOUR_TOKEN"

Create New Rule (POST)

Field	Type	Requirement	Description
mobid	string	Required	Session key or `"*"` for all sessions.
triggerType	string	Required	Trigger type: `"exact"`, `"contains"`, `"regex"`, or `"ai_fallback"`.
keyword	string	Required	Keyword string or Regular Expression pattern.
replyType	string	Required	Response type: `"text"` (static string) or `"ai_response"` (dynamic LLM execution).
response	string	Required	Static reply message or custom AI prompt instructions.

Create Rule cURL Example

curl -X POST "https://socket.wamax.in/api/v1/chatbot/rules" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mobid": "918281885620",
    "triggerType": "contains",
    "keyword": "timing",
    "replyType": "text",
    "response": "CarePlus Clinic is open Monday through Saturday, 9:00 AM to 7:00 PM!"
  }'

Delete Rule cURL Example

curl -X DELETE "https://socket.wamax.in/api/v1/chatbot/rules/rule_17877564" \
  -H "Authorization: Bearer YOUR_TOKEN"

POST /api/v1/chatbot/json-extraction/toggle

Toggle Session AI Structured Data Extraction

Enable or disable automated AI JSON data extraction (e.g. appointment bookings, doctor selection, customer details, leads) for a specific session.

Request Parameters

Field	Type	Presence	Description
sessionKey	string	Required	WhatsApp phone number or session ID (e.g., `"918281885620"`).
enabled	boolean	Required	Set to `true` to enable structured JSON extraction or `false` to disable.

cURL Example

curl -X POST "https://socket.wamax.in/api/v1/chatbot/json-extraction/toggle" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionKey": "918281885620",
    "enabled": true
  }'

GET /api/v1/chatbot/extracted-data

Get AI-Extracted Booking & Lead JSON Records

Retrieve structured JSON records extracted by the AI during customer WhatsApp conversations (e.g., booked appointments, slot times, fees, patient/customer details).

Query Parameters

Parameter	Type	Presence	Description
sessionKey	string	Optional	Target WhatsApp session key or phone number (e.g., `"918281885620"`). Defaults to `"global"`.

cURL Example

curl -X GET "https://socket.wamax.in/api/v1/chatbot/extracted-data?sessionKey=918281885620" \
  -H "Authorization: Bearer YOUR_TOKEN"

GET /api/v1/chatbot/extracted-stream

Real-Time Live SSE Stream for Extracted Data Sync

Open a long-lived Server-Sent Events (SSE) connection to automatically stream newly extracted AI booking JSON records directly into external client databases or custom UI dashboards in real time.

Query Parameters

Parameter	Type	Presence	Description
sessionKey	string	Optional	Target WhatsApp session key or tenant profile (e.g. `"clinic"` or `"918281885620"`). Defaults to `"global"`.

JavaScript EventSource Client Example

const eventSource = new EventSource('https://socket.wamax.in/api/v1/chatbot/extracted-stream?sessionKey=clinic');

eventSource.onmessage = (event) => {
    const data = JSON.parse(event.data);
    console.log('Live Extracted Booking Received:', data);
    if (data.type === 'NEW_EXTRACTION' || data.records) {
        // Sync to custom client SQL/NoSQL Database
        saveToDatabase(data.records);
    }
};

eventSource.onerror = (err) => {
    console.error('SSE Stream Error, reconnecting...', err);
};

Voice Note Audio AI Processing Engine (Deepgram STT & TTS)

Automated processing of inbound WhatsApp Voice Notes (PTT audio) with instant AI intent extraction and optional voice response generation:

1. Inbound Voice Transcription (STT): Voice notes (ogg/mp3 PTT) sent by users on WhatsApp are automatically transcribed using Deepgram Aura Speech-To-Text.
2. AI Intent & Entity Extraction: Transcribed text is analyzed by Gemini / OpenRouter / Puter JS AI to extract appointment bookings, patient names, service requests, and questions.
3. Outbound Voice Response (TTS): When enabled, AI text replies are converted back to audio via Deepgram Aura Text-To-Speech and dispatched as native WhatsApp voice notes.

Human Mimicry & Behavior Simulation Engine

Make AI responses look and feel like a real human receptionist instead of an automated bot:

WhatsApp "Typing..." Status (composing): Automatically dispatches sendPresenceUpdate('composing') status to the WhatsApp client while generating text replies.
WhatsApp "Recording Audio..." Status (recording): Dispatches sendPresenceUpdate('recording') status when generating voice note responses.
Character-Based Dynamic Typing Delay: Calculates typing delay proportional to response character length (e.g. 30ms/char) bounded between configurable min/max constraints (e.g. 1.2s - 5s).
Random Initial Human Pause: Introduces a subtle 300ms - 1000ms random delay before typing/recording starts to simulate natural human reading time.

Live JSON Database & Realtime Webhook Sync

The WaMax AI Engine maintains persistent JSON database files for every active session and streams all chatbot activities in real-time to your custom backend/database:

On-Disk JSON Persistence: Session knowledge is persisted as sessions/brain_<sessionKey>.json, system prompts in sessions/prompt_<sessionKey>.json, rules in chatbot_rules.json, and extracted data in sessions/extracted_<sessionKey>.json.
REST API Data Retrieval: Retrieve any session's full brain, prompt, rule set, extracted JSON records, chat history, or AI credit usage dynamically via REST JSON endpoints.
Live Webhook Database Streaming: Whenever the AI Chatbot processes an incoming message or generates a reply, a complete JSON event payload (including full chat history, media analysis, OCR, extracted booking JSON, and AI telemetry) is immediately posted to your Webhook URL. You can stream this directly into your own MySQL, PostgreSQL, or MongoDB database.

End-to-End Clinic Booking Simulation

Below is a real-world demonstration of how the WaMax AI Engine processes patient interactions using the configured Clinic brain.json knowledge base:

Patient: Hi, I want to book an appointment with Dr. Sarah Jenkins for tomorrow morning.
CarePlus AI Bot: Hello! Dr. Sarah Jenkins (Cardiologist) is available on Wednesday at 10:00 AM and 11:30 AM. Consultation fee is ₹700. Would you like to reserve the 10:00 AM slot? Please reply with your Full Name and Phone Number to confirm.
Patient: Rahul Sharma, 9876543210. 10:00 AM slot please.
CarePlus AI Bot: ✅ Appointment Confirmed!

                                    • Patient: Rahul Sharma (9876543210)

                                    • Doctor: Dr. Sarah Jenkins (Cardiologist)

                                    • Time: Wednesday, 10:00 AM

                                    • Location: CarePlus Clinic, MG Road, Kochi

                                    Thank you for choosing CarePlus Clinic!

Real-Time Webhook, Security & Multi-Number Engine

WaMax features an enterprise-grade real-time event dispatcher. Every incoming message (message.inbound) and outgoing message (message.outbound) across all connected sessions is instantly formatted and forwarded to your webhook endpoints with cryptographic signatures, HTTP Basic Authentication, and automatic deduplication.

No Public Domain? How to Receive Real-Time Webhooks

If your CRM or application runs on localhost or in a private office without a public domain or static IP, you can receive real-time messages in 3 ways:
• Method 1 (Built-in SSE Stream - Zero Setup): Connect your client to GET /api/portal/stream?token=<token> over HTTP. WaMax streams events to your local browser/app in real-time without needing any public IP or domain!
• Method 2 (Free Cloudflare Tunnel / ngrok): Run cloudflared tunnel --url http://localhost:3000 or ngrok http 3000 to obtain an instant free HTTPS domain and paste it into WaMax.
• Method 3 (Webhook.site / Zapier / Make): Paste a free webhook URL from Webhook.site or Zapier to capture live events instantly.

POST YOUR_WEBHOOK_URL Inbound & Outbound Events

1. Security Headers Attached by WaMax

Header	Example Value	Description
X-WaMax-Signature-256	sha256=a5b6c7...	HMAC-SHA256 signature of the raw JSON payload generated using your secret key. Verify this on your server to guarantee authenticity and prevent spoofing.
Authorization	Basic dXNlcjpwYXNz	HTTP Basic Auth credentials (`username:password` in Base64). Username can be set to the client mobile number (e.g. `918281885620`) and password to your secret API key.
X-WaMax-Secret	your_secret_token	Configured secret key string for fast token verification.
X-WaMax-Delivery	3eb0d4f5-9a1b-4c2d	Unique delivery UUID for idempotent message deduplication.
X-WaMax-Timestamp	1729641200	Unix epoch timestamp to prevent replay attacks.
X-WaMax-Event	message.inbound \| message.outbound	Event name header for quick routing without JSON parsing.

2. Real-Time Webhook Payload Schema

{
  "event": "message.inbound",
  "direction": "inbound",
  "tenant_id": "918281885620",
  "session_id": "qr_1781332832910_5eab537f",
  "mobile": "918281885620",
  "mobid": "384729105638274",
  "portal_token": "a1b2c3d4e5f6g7h8",
  "message_id": "3EB0D4F5A1B2C3D4",
  "timestamp": 1729641200,
  "datetime": "2026-10-23T02:30:00.000Z",
  "chat_type": "individual",
  "is_group": false,
  "is_status": false,
  "sender": {
    "phone": "919876543210",
    "jid": "919876543210@s.whatsapp.net",
    "name": "Arjun Kumar"
  },
  "message": {
    "type": "text",
    "text": "Hello, I want to book an appointment for tomorrow.",
    "media_url": null,
    "ocr_text": null,
    "transcription": null
  }
}

POST /api/webhook/session Requires Token

Configure Per-Session / Per-Number Webhook (Multi-Tenant)

Route events from specific WhatsApp numbers to dedicated client CRM endpoints. If a client has their own server or webhook, set it here so Client A (918281885620) forwards to CRM A, while Client B (919876543210) forwards to CRM B!

Request Body Parameters

Parameter	Type	Requirement	Description
sessionId	string	Required	Session ID or phone number (e.g. `"918281885620"`).
webhookUrl	string	Required	The target endpoint URL for this specific number.
secretToken	string	Optional	Secret key used for HMAC-SHA256 signature generation.
authType	string	Optional	`"basic"`, `"hmac"`, `"bearer"`, or `"none"` (default: `"basic"`).
username	string	Optional	Basic Auth username (defaults to the session mobile number).
password	string	Optional	Basic Auth password / API key.

cURL Example (Per-Session Webhook with Basic Auth & HMAC)

curl -X POST "https://socket.wamax.in/api/webhook/session" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "918281885620",
    "webhookUrl": "https://client-crm.com/api/v1/whatsapp/webhook",
    "authType": "basic",
    "username": "918281885620",
    "password": "secret_client_key_999",
    "secretToken": "secret_client_key_999",
    "enabled": true
  }'

POST /api/webhook/config Requires Token

Global Webhook & Whitelisted Domains

Configure the default centralized webhook URL, global secret token, and whitelist allowed target domains to prevent unauthorized outbound requests (SSRF protection).

Request Body Parameters

Parameter	Type	Presence	Description
webhookUrl	string	Optional	Default centralized fallback webhook URL.
secretToken	string	Optional	Global secret token sent in `X-WaMax-Secret` and used for HMAC signatures.
approvedDomains	array \| string	Optional	Whitelisted domains (e.g. `["api.whatsapp.wywk.in", "wamax.in", "client-crm.com"]` or `"*"` for all).
enabled	boolean	Optional	Enable or disable automatic webhook forwarding.

cURL Example

curl -X POST "https://socket.wamax.in/api/webhook/config" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookUrl": "https://api.whatsapp.wywk.in/api/webhook/receiver",
    "secretToken": "deb884555a0fcb9659a707794f27a4ed366e1fe61538e5892f93eff2",
    "approvedDomains": ["api.whatsapp.wywk.in", "wamax.in", "wywk.in", "client-crm.com", "localhost"],
    "enabled": true
  }'

Administrative Export APIs

Export deduplicated lead contacts, personal chat histories, and group interaction logs into CSV or JSON format for administrative reporting.

POST /api/v1/export/contacts Requires Token

Extract deduplicated contact leads across all or selected WhatsApp sessions with Name, Number, and Last Active Timestamp.

Query & Body Parameters

Field	Type	Requirement	Description
format	string	Optional	Export format: `"json"` (default) or `"csv"`.
sessionIds	array	Optional	List of session IDs to extract leads from. If empty, extracts across all active sessions.

Response (200 OK)

{
  "success": true,
  "totalContacts": 128,
  "contacts": [
    {
      "Name": "Rahul Sharma",
      "Number": "+91 82818 85620",
      "RawNumber": "918281885620",
      "LastMsgOn": "2026-08-26 15:42:00",
      "Session": "qr_1781332832910_5eab537f"
    }
  ]
}

POST /api/v1/export/groups Requires Token

Fetch WhatsApp group membership lists, group names, participant phone numbers, total group messages, and active timestamps.

Query & Body Parameters

Field	Type	Requirement	Description
format	string	Optional	Export format: `"json"` (default) or `"csv"`.
sessionId	string	Optional	Filter groups by specific WhatsApp session.

Response (200 OK)

{
  "success": true,
  "totalGroups": 12,
  "groups": [
    {
      "GroupName": "Kerala Tech Community",
      "GroupId": "120363029102930192@g.us",
      "MembersCount": 245,
      "Members": [
        { "Name": "Anand V", "Phone": "+91 98463 03025" }
      ],
      "TotalMessagesInGroup": 1420,
      "LastMsgOn": "2026-08-26 15:30:00"
    }
  ]
}

Formatted Message History API

Fetch clean, human-readable message history for any chat. Automatically converts raw WhatsApp internal identifiers (such as 9563483636436@jid or 528624864864@lid) into clean E.164 phone numbers like +91 82818 85620.

GET /api/v1/formatted Requires Token

Query parameters allow fetching last N messages for a specific chat target.

Query Param	Type	Requirement	Description
mobid	string	Required	Sender WhatsApp number / mobid.
chatId	string	Optional	Target contact number (e.g. `918281885620`). If omitted, returns all recent chats.
limit	number	Optional	Number of messages to return (e.g., `5`, `50`, or `100`). Default: `20`.

cURL Example (Fetch Last 5 Messages)

curl -X GET "https://socket.wamax.in/api/v1/formatted?mobid=918281885620&chatId=917012729389&limit=5" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (Clean Formatted Output)

{
  "success": true,
  "chatId": "+91 70127 29389",
  "total": 5,
  "messages": [
    {
      "id": "WAMID_101",
      "from": "+91 82818 85620",
      "to": "+91 70127 29389",
      "sender_name": "Rahul Sharma",
      "message": "Hi, please send invoice details.",
      "timestamp": "2026-08-26T14:30:00.000Z",
      "status": "read"
    }
  ]
}

Emoji Reactions, Chat Pinning & Status Stories

Interact with chats dynamically by sending emoji reactions, pinning important conversations, or updating WhatsApp status stories.

POST /api/v1/chats/react Requires Token

Send or remove an emoji reaction on any message.

Request Body (JSON)

{
  "sessionId": "qr_1781332832910_5eab537f",
  "to": "918281885620",
  "messageId": "WAMID_9583495834",
  "emoji": "👍"
}

POST /api/v1/chats/pin Requires Token

Pin or unpin a conversation top in WhatsApp.

Request Body (JSON)

{
  "sessionId": "qr_1781332832910_5eab537f",
  "chatId": "918281885620",
  "pin": true
}

POST /api/v1/status Requires Token

Post a text, image, or video status story update.

Request Body (JSON)

{
  "sessionId": "qr_1781332832910_5eab537f",
  "type": "text",
  "content": "🚀 WaMax AI 2.0 is now officially live!",
  "backgroundColor": "#00a884"
}

Groups & Community Management API

Automate WhatsApp group updates, participant additions, admin assignments, and community announcements.

POST /api/v1/groups/manage Requires Token

Manage group subject, description, or participants.

Request Body (JSON)

{
  "sessionId": "qr_1781332832910_5eab537f",
  "groupId": "120363029102930192@g.us",
  "action": "add_participants",
  "participants": ["918281885620", "917012729389"]
}

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, interactive buttons, or push-to-talk voice notes through any connected session. The server provides both REST convenience endpoints and Meta Cloud API-compatible paths.

POST /api/send-message • /api/messages/send Requires Token

Request Body (JSON)

Field	Type	Requirement	Description
sessionId	string	Required	Target sender identifier: accepts MobID (e.g. `"MOB-AD0F-FE8C"`), Mobile Number (e.g. `"918304064190"`), or Session ID (e.g. `"WAMAX-QR-..."`).
to	string	Required	Recipient WhatsApp phone number with country code (e.g. `"919846303025"`).
message / text	string	Optional	Message text content. Required for text messages. (Both `message` and `text` keys are accepted).
type	string	Default: "text"	Message type: `"text"`, `"image"`, `"pdf"`, `"document"`, `"audio"`, `"video"`, `"voice"`, `"template"`, `"buttons"`.
url / media_url	string	Optional	Public URL of media file (Required for image, pdf, video, and voice notes).
caption	string	Optional	Media text caption (for image, document, 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..."
    }
  ]
}

Typing & Voice Presence Indicators

Simulate realistic human typing and audio recording indicators on recipient screens before or during message dispatch. WhatsApp recipients will see the live status indicator ("typing..." or "recording audio...") in the chat header.

POST /api/messages/typing Requires Token

Shows the typing... indicator in the chat window with the target recipient for a designated duration (default: 3 seconds), then automatically restores the state to idle.

Request Body (JSON)

Parameter	Type	Requirement	Description
sessionId	string	Required*	The active WhatsApp session ID (or provide MobID in URL/body).
to	string	Required	Target phone number with country code (e.g. `918281885620`) or group JID.
duration	number	Optional	Duration to display typing indicator in milliseconds (default: `3000` ms). If set to `0`, maintains typing indefinitely until presence update.

cURL Example

curl -X POST "https://socket.wamax.in/api/messages/typing" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "YOUR_SESSION_ID",
    "to": "918281885620",
    "duration": 4000
  }'

Response

{
  "success": true,
  "status": "composing",
  "recipient": "918281885620@s.whatsapp.net",
  "duration": 4000
}

POST /api/messages/recording Requires Token

Shows the recording audio... indicator in the chat window with the target recipient for a designated duration (default: 4 seconds), then automatically restores the state to idle. Perfect to call right before sending a PTT voice note.

Request Body (JSON)

Parameter	Type	Requirement	Description
sessionId	string	Required*	The active WhatsApp session ID.
to	string	Required	Target phone number (e.g. `918281885620`) or group JID.
duration	number	Optional	Duration to display audio recording indicator in milliseconds (default: `4000` ms).

cURL Example

curl -X POST "https://socket.wamax.in/api/messages/recording" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "YOUR_SESSION_ID",
    "to": "918281885620",
    "duration": 5000
  }'

POST /api/messages/presence Requires Token

Low-level WhatsApp presence controller for exact state manipulation: composing, recording, paused, available, or unavailable.

Request Body (JSON)

Parameter	Type	Requirement	Description
sessionId	string	Required	Session key.
to	string	Optional	Target recipient phone number or group JID. If omitted, applies to account globally.
presence	string	Required	One of: `composing`, `recording`, `paused`, `available`, `unavailable`.

WhatsApp Group Management Suite

Comprehensive enterprise APIs for creating groups, fetching group metadata, updating names & descriptions, adding/removing members, promoting/demoting admins, configuring group privacy settings, and managing invite links.

GET /api/messages/groups/:groupJid/metadata Requires Token

Fetch complete metadata for any joined WhatsApp group: group subject, owner, creation date, full participant list with admin flags, description, announcement status, and locked mode.

Query Parameters

Parameter	Type	Requirement	Description
sessionId	string	Required	The active session ID.

cURL Example

curl -X GET "https://socket.wamax.in/api/messages/groups/120363028394819283@g.us/metadata?sessionId=YOUR_SESSION_ID" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

{
  "success": true,
  "metadata": {
    "id": "120363028394819283@g.us",
    "subject": "VIP Customers Club",
    "owner": "918281885620@s.whatsapp.net",
    "creation": 1715000000,
    "desc": "Official VIP discount community for WaMax members.",
    "participants": [
      { "id": "918281885620@s.whatsapp.net", "admin": "superadmin" },
      { "id": "919876543210@s.whatsapp.net", "admin": "admin" },
      { "id": "919447000000@s.whatsapp.net", "admin": null }
    ],
    "announce": false,
    "restrict": true
  }
}

POST /api/messages/groups/create Requires Token

Create a brand new WhatsApp group with subject title and initial participants.

Request Body (JSON)

Parameter	Type	Requirement	Description
sessionId	string	Required	Session key.
subject	string	Required	The group subject title (up to 100 characters).
participants	array<string>	Required	Array of phone numbers to invite into the group.

cURL Example

curl -X POST "https://socket.wamax.in/api/messages/groups/create" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "YOUR_SESSION_ID",
    "subject": "Alpha Test Group",
    "participants": ["918281885620", "919876543210"]
  }'

POST /api/messages/groups/subject & /description Requires Token

Update group subject name or description details.

1. Update Subject (`POST /api/messages/groups/subject`)

curl -X POST "https://socket.wamax.in/api/messages/groups/subject" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "YOUR_SESSION_ID",
    "groupJid": "120363028394819283@g.us",
    "subject": "Elite Partners 2026"
  }'

2. Update Description (`POST /api/messages/groups/description`)

curl -X POST "https://socket.wamax.in/api/messages/groups/description" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "YOUR_SESSION_ID",
    "groupJid": "120363028394819283@g.us",
    "description": "Welcome! Please follow our community guidelines."
  }'

POST /api/messages/groups/participants Requires Token

Manage group members: add new participants, remove members, promote to admin, or demote from admin.

Request Body (JSON)

Parameter	Type	Requirement	Description
sessionId	string	Required	Session ID.
groupJid	string	Required	The group JID (e.g. `120363028394819283@g.us`).
action	string	Required	One of: `add`, `remove`, `promote`, `demote`.
participants	array<string>	Required	Array of phone numbers or participant JIDs.

cURL Example (Add Members)

curl -X POST "https://socket.wamax.in/api/messages/groups/participants" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "YOUR_SESSION_ID",
    "groupJid": "120363028394819283@g.us",
    "action": "add",
    "participants": ["919876543210"]
  }'

POST /api/messages/groups/settings & Invite Codes Requires Token

1. Configure Group Settings (`POST /api/messages/groups/settings`)

Set group announcement mode (only admins can send messages) or locked mode (only admins can edit group info):

announcement: Only admins can send messages.
not_announcement: All participants can send messages.
locked: Only admins can modify group subject, icon, or description.
unlocked: All members can edit group info.

curl -X POST "https://socket.wamax.in/api/messages/groups/settings" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "YOUR_SESSION_ID",
    "groupJid": "120363028394819283@g.us",
    "setting": "announcement"
  }'

2. Get Group Invite Code (`GET /api/messages/groups/invite-code`)

curl -X GET "https://socket.wamax.in/api/messages/groups/invite-code?sessionId=YOUR_SESSION_ID&groupJid=120363028394819283@g.us" \
  -H "Authorization: Bearer YOUR_TOKEN"

3. Revoke & Reset Group Invite Code (`POST /api/messages/groups/invite-code/revoke`)

curl -X POST "https://socket.wamax.in/api/messages/groups/invite-code/revoke" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "YOUR_SESSION_ID",
    "groupJid": "120363028394819283@g.us"
  }'

WhatsApp Status Stories & Broadcast Feed

Complete status lifecycle management: detect incoming contact statuses in real-time, query whether a specific customer has posted a story, reply directly to a contact's status story, or broadcast your own status story (text, image, video, audio).

GET /api/messages/status/list Requires Token

Lists recent WhatsApp status stories captured from connected contacts. Returns sender phone number, story type (text, image, video, audio), caption, timestamp, and unique status ID.

Query Parameters

Parameter	Type	Requirement	Description
sessionId	string	Required	Active session identifier.
limit	number	Optional	Max statuses to retrieve (default: `50`, max: `200`).

cURL Example

curl -X GET "https://socket.wamax.in/api/messages/status/list?sessionId=YOUR_SESSION_ID&limit=20" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

{
  "success": true,
  "count": 2,
  "statuses": [
    {
      "statusId": "3EB0D4F5A1B2C3D4",
      "participant": "919876543210@s.whatsapp.net",
      "phone": "919876543210",
      "type": "image",
      "caption": "Enjoying the sunset in Munnar! 🌄",
      "timestamp": 1729641200000
    },
    {
      "statusId": "3EB0E5F6A2B3C4D5",
      "participant": "918281885620@s.whatsapp.net",
      "phone": "918281885620",
      "type": "text",
      "text": "Flash sale live now on wamax.in!",
      "timestamp": 1729641500000
    }
  ]
}

GET /api/messages/status/contact/:phone Requires Token

Check if a specific customer or contact has posted an active WhatsApp status within the last 24 hours, and retrieve their stories.

cURL Example

curl -X GET "https://socket.wamax.in/api/messages/status/contact/919876543210?sessionId=YOUR_SESSION_ID" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

{
  "success": true,
  "phone": "919876543210",
  "hasStatus": true,
  "count": 1,
  "statuses": [
    {
      "statusId": "3EB0D4F5A1B2C3D4",
      "type": "image",
      "caption": "Enjoying the sunset in Munnar! 🌄",
      "timestamp": 1729641200000
    }
  ]
}

POST /api/messages/status/reply Requires Token

Reply directly to a contact's status story. The reply quotes the original status in the recipient's direct chat, exactly like tapping "Reply" inside WhatsApp.

Request Body (JSON)

Parameter	Type	Requirement	Description
sessionId	string	Required	Session key.
participant	string	Required	The phone number or contact JID who posted the status.
statusId	string	Required	The unique status message ID (from `/status/list` or incoming webhook).
text	string	Required	Your reply text message.

cURL Example

curl -X POST "https://socket.wamax.in/api/messages/status/reply" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "YOUR_SESSION_ID",
    "participant": "919876543210",
    "statusId": "3EB0D4F5A1B2C3D4",
    "text": "Stunning picture! Have a great time! 🙌"
  }'

POST /api/messages/status/post Requires Token

Broadcast a new WhatsApp story / status. Supports colorful text stories with customizable background and font, as well as media stories (images, video, audio).

1. Text Status Story

curl -X POST "https://socket.wamax.in/api/messages/status/post" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "YOUR_SESSION_ID",
    "type": "text",
    "text": "⚡ WaMax v2.2 is now live with Full Group & Status APIs!",
    "backgroundColor": "#1E3C72",
    "font": 2
  }'

2. Image Status Story with Caption

curl -X POST "https://socket.wamax.in/api/messages/status/post" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "YOUR_SESSION_ID",
    "type": "image",
    "url": "https://wamax.in/assets/images/special-offer.jpg",
    "caption": "🔥 Weekend 50% Off Special!"
  }'

Profile & Business Details Management

Complete management of your WhatsApp account identity: fetch profile status and photo, update display name, edit "About" status text, set or remove profile pictures, and configure WhatsApp Business catalog and company profile details.

GET /api/messages/profile Requires Token

Fetch full account profile details: display name, about status, high-resolution profile picture URL, and WhatsApp Business metadata (if applicable).

cURL Example

curl -X GET "https://socket.wamax.in/api/messages/profile?sessionId=YOUR_SESSION_ID" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

{
  "success": true,
  "profile": {
    "jid": "918281885620@s.whatsapp.net",
    "name": "WaMax Official Support",
    "status": "Enterprise Multi-Tenant WhatsApp Gateway",
    "profilePictureUrl": "https://pps.whatsapp.net/v/t61.24694-24/...",
    "businessProfile": {
      "description": "High-speed socket & REST API management.",
      "email": "support@wamax.in",
      "websites": ["https://wamax.in"],
      "category": "TELECOMMUNICATION"
    }
  }
}

POST /api/messages/profile/name & /status Requires Token

1. Update Display Name (`POST /api/messages/profile/name`)

curl -X POST "https://socket.wamax.in/api/messages/profile/name" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "YOUR_SESSION_ID",
    "name": "WaMax Customer Support"
  }'

2. Update About / Status (`POST /api/messages/profile/status`)

curl -X POST "https://socket.wamax.in/api/messages/profile/status" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "YOUR_SESSION_ID",
    "status": "🚀 Available 24/7 on WhatsApp"
  }'

POST & DEL /api/messages/profile/picture Requires Token

1. Update Profile Picture (`POST /api/messages/profile/picture`)

Provide an image URL to download, scale, and update as the WhatsApp DP.

curl -X POST "https://socket.wamax.in/api/messages/profile/picture" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "YOUR_SESSION_ID",
    "url": "https://wamax.in/assets/images/logo-square.png"
  }'

2. Remove Profile Picture (`DELETE /api/messages/profile/picture`)

Completely remove the active profile picture.

curl -X DELETE "https://socket.wamax.in/api/messages/profile/picture" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "YOUR_SESSION_ID"
  }'

POST /api/messages/profile/update-business Requires Token

Update WhatsApp Business metadata including business description, official address, email, website links, and industry category.

cURL Example

curl -X POST "https://socket.wamax.in/api/messages/profile/update-business" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "YOUR_SESSION_ID",
    "description": "Leading WhatsApp API provider in India & Middle East.",
    "address": "Infopark Campus, Kakkanad, Kochi, Kerala",
    "email": "contact@wamax.in",
    "websites": ["https://wamax.in", "https://docs.wamax.in"],
    "category": "PROFESSIONAL_SERVICES"
  }'

Native WhatsApp Events, Location & Media Types

Deliver rich interactive content beyond plain text: native WhatsApp Calendar Event invitations, interactive Google Map location pins, Push-to-Talk (.ogg Opus / ptt: true) voice notes vs standard MP3 audio, and vCard business cards.

POST /api/messages/send (type: "event") Requires Token

Send a native WhatsApp Calendar Event card. Recipients see an event banner with RSVP buttons ("Going", "Maybe", "Can't go"), start/end times, and location details.

Request Body (JSON)

Parameter	Type	Requirement	Description
sessionId	string	Required	Session key.
to	string	Required	Recipient phone number or group JID.
type	string	Required	Must be `"event"`.
event.name	string	Required	Title of the event or meeting.
event.description	string	Optional	Full description or agenda.
event.startTime	number	Required	Event start UNIX timestamp (in seconds).
event.endTime	number	Optional	Event end UNIX timestamp (in seconds).
event.location	string	Optional	Physical address or meeting link URL (e.g. Zoom/Meet).
event.callType	string	Optional	`"audio"` or `"video"` for WhatsApp call events.

cURL Example

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": "event",
    "event": {
      "name": "WaMax Enterprise Launch Webinar",
      "description": "Live walkthrough of automated WhatsApp multi-session APIs.",
      "startTime": 1735689600,
      "endTime": 1735693200,
      "location": "https://meet.google.com/abc-defg-hij",
      "callType": "video"
    }
  }'

POST /api/messages/send (type: "location") Requires Token

Send an interactive WhatsApp Location pin with coordinates, venue name, and address.

cURL Example

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": "location",
    "latitude": 9.9312,
    "longitude": 76.2673,
    "name": "WaMax Technologies HQ",
    "address": "Infopark Phase 2, Kochi, Kerala, India"
  }'

POST PTT Voice Notes vs Standard Audio Files Requires Token

WhatsApp displays audio messages in two distinctly different UI styles:

Push-to-Talk (PTT) Voice Note (type: "voice"): Rendered as an interactive waveform player with the green microphone badge. Encoded in audio/ogg; codecs=opus.
Standard Audio Attachment (type: "audio"): Rendered as a downloadable audio file (e.g. MP3 music or recorded podcast).

1. Send Push-to-Talk Voice Note (Waveform)

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": "voice",
    "url": "https://wamax.in/assets/audio/voice-memo.ogg",
    "ptt": true
  }'

2. Send Standard MP3 Audio File

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": "audio",
    "url": "https://wamax.in/assets/audio/podcast-episode.mp3"
  }'

POST /api/messages/send (type: "contact") Requires Token

Send a native vCard contact card so the recipient can tap "Add to Contacts" directly from WhatsApp.

cURL Example

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": "contact",
    "contact": {
      "displayName": "Sheffin",
      "vcard": "BEGIN:VCARD\nVERSION:3.0\nFN:Sheffin\nORG:WaMax Corp;\nTEL;type=CELL;type=VOICE;waid=918281885620:+91 82818 85620\nEMAIL:support@wamax.in\nEND:VCARD"
    }
  }'

AI Chatbot, Intent Engine & Knowledge Base

Complete step-by-step documentation for building, managing, and synchronizing multi-tenant WhatsApp AI chatbots with local intent engines, product masters, custom paths, and remote cloud configurations.

GUIDE Step-by-Step: How to Build & Deploy a WaMax Chatbot

1. Select Tenant Profile & Identity

Open chatbot.html in your browser. Choose your tenant profile (clinic, appliances, ecommerce, salon, or custom session key). Define the Bot Display Name, Legal Company Name, and Primary WhatsApp Number in Section 1.

2. Configure Product / Service Masters

In Section 11, configure catalog services or products:

Appliance Repair Master (Section 11B): Set base repair charges, technician visit fees (e.g. ₹250), default warranty period (e.g. 12 months), and serial number/invoice verification rules.
E-Commerce Stock & Offer Master (Section 11C): Configure products with regular price, discounted offer rate, promo codes (e.g. FESTIVE20), live stock counts (Stock In/Out), low-stock alert thresholds, and auto-hide logic for out-of-stock items.

3. Setup Intent Engine (intents.json) to Save AI Costs

Instead of passing every simple question to LLMs (Gemini / OpenRouter), define rule-based and semantic intents in Category 9 (Intent Engine & Workflows):

Add English (en) and Malayalam (ml) training phrases (e.g., "book doctor", "അപ്പോയിന്റ്മെന്റ്", "price list", "stock status").
Configure confidence policy: rule_match_no_ai: 0.90, semantic_match_no_ai: 0.84, skip_llm_simple_template: true.

4. Attach Custom Path or Remote Cloud URLs

Remote Cloud Config (Section 1C): Toggle dynamic cloud fetch ON and enter custom HTTPS/HTTP URLs for brain.json, prompt.json, and intents.json. The server automatically syncs and caches them.
REST API Sync: Submit custom configurations directly via POST /api/chatbot/brain, POST /api/chatbot/prompt, and POST /api/chatbot/intents.

5. Save & Download Files

Click Save & Apply to write to server disk and update live bot memory.
Click Download All 3 JSONs to save offline local backups of brain.json, prompt.json, and intents.json.

GET /api/chatbot/brain Optional Token

Fetch tenant or session brain configuration JSON (includes identity, rules, services, doctors, appliance warranty, e-commerce stock, and remote cloud config).

Query Parameters

Parameter	Type	Requirement	Description
sessionId	string	Optional	Session key (e.g. `"clinic"` or `"918304064190"`).
tenant	string	Optional	Tenant profile (`"clinic"`, `"appliances"`, `"ecommerce"`, `"salon"`).

cURL Example

curl -X GET "https://socket.wamax.in/api/chatbot/brain?tenant=appliances"

POST /api/chatbot/brain Requires Token

Save and sync updated brain JSON configuration to the server database/filesystem.

Request Body (JSON)

Field	Type	Requirement	Description
sessionId	string	Required	Target session key or tenant profile ID.
tenant	string	Optional	Tenant folder identifier (e.g., `"appliances"` or `"ecommerce"`).
brain	object	Required	Full brain configuration object.

POST /api/chatbot/intents Requires Token

Save tenant-specific intents.json rule definitions, confidence thresholds, and multilingual training phrases.

cURL Example

curl -X POST "https://socket.wamax.in/api/chatbot/intents" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant": "ecommerce",
    "intents": {
      "meta": { "industry": "E-Commerce" },
      "runtime_policy": { "confidence_policy": { "rule_match_no_ai": 0.90 } },
      "intents": [
        { "id": "CHECK_OFFERS", "enabled": true, "category": "GENERAL", "action": "FETCH_PROMO_CODES", "training_phrases": { "en": ["any offers", "discount code"], "ml": ["ഓഫറുകൾ ഉണ്ടോ"] } }
      ]
    }
  }'

⚡ 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

Active Sessions

API Documentation

Getting Started

Multi-Tenant & Live Stream API

Sessions API

Usage & Leads API

AI Telemetry & Chatbot API

Messages & History API

Presence & Human States (v2.2)

WhatsApp Groups Suite (v2.2)

Stories & Status API (v2.2)

Profile & Catalog Management (v2.2)

Events, Location & Media (v2.2)

Authentication

🔑 Your API Token

Response (200 OK)

Live Incoming Messages Extraction API

Query Parameters

Example URL Request

Response (200 OK)

Real-Time SSE Stream (Pure Extractor)

Connection Headers

Real-Time Event Stream Payload (JSON)

JavaScript Connection Example

Enriched Live Messages Feed (REST)

Query Parameters

Example URL Request

Pure Message Extractor Mode (Disable AI Replies)

Request Body (JSON)

Response (200 OK)

Dynamic UPI Payment Deep-Link & QR

Request Body (JSON)

Response (200 OK)

Rumik AI Multilingual Malayalam TTS

Request Body (JSON)

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)

Multi-Engine AI Architecture & Multimodal Processing

Key Rotation Engine

Puter.js Integration

Deepgram Speech Engine

OpenRouter Fallback

AI Telemetry & Usage Analytics API

Response (200 OK)

Response (200 OK)

AI Chatbot & Dynamic Brain Engine API

Architecture & Execution Lifecycle

Request Body (JSON)

Response Example

Fetch Active Brain (GET)

Upload Direct JSON Payload (POST)

Synchronize from Public URL (POST)

Fetch Active Persona (GET)

Direct Persona Instructions (POST)

Synchronize Persona from Remote URL (POST)

Fetch Active Rules (GET)

Create New Rule (POST)

Create Rule cURL Example

Delete Rule cURL Example

Toggle Session AI Structured Data Extraction

Request Parameters

cURL Example

1. Update Subject (`POST /api/messages/groups/subject`)