API Documentation

Integrate the WhatsApp Session Manager into your own applications using HTTP REST APIs

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

Live Incoming Messages Extraction API

Realtime endpoint to view and extract live incoming WhatsApp messages. Authenticates via Bearer Token header or query parameter ?key=YOUR_KEY.

GET /view/messages/v1 Query Key or Bearer Token

Extract live incoming or outbound messages filtered by Phone Number, Session ID, or Message Type.

Query Parameters

ParameterTypePresenceDescription
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.

Example URL Request

https://api.whatsapp.wywk.in/view/messages/v1?key=deb884555a0fcb9659a707794f27a4ed366e1fe61538e5892f93eff2&phone=8304064190&type=inbound&limit=50

Response (200 OK)

{
  "success": true,
  "timestamp": "2026-08-27T06:25:00.000Z",
  "filter": {
    "sessionId": "all",
    "phone": "8304064190",
    "jid": "918304064190@s.whatsapp.net",
    "type": "inbound"
  },
  "count": 1,
  "messages": [
    {
      "id": "WAMID_1029301923",
      "from": "918304064190@s.whatsapp.net",
      "senderName": "Rahul",
      "text": "Hello, I am testing live incoming messages via webhook API!",
      "timestamp": 1787756400,
      "fromMe": false,
      "direction": "inbound"
    }
  ]
}

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.

Token vs Master Key: Clients using their private portalToken (e.g. prt_8458cea4...) do NOT need the master API key! For sending messages, clients use their regular sessionId and apiKey.
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:

  1. Rule Engine Check: Evaluates active static rules for matching exact, contains, or regex triggers. If matched, responds instantly without consuming AI credits.
  2. AI Fallback Gate: If no rule matches and the session chatbot is enabled, routes the query to the AI engine.
  3. 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).
  4. 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.
  5. 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)

FieldTypeRequirementDescription
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!

Realtime Webhook & Multimodal AI Payload

When an incoming message or media is received on any session, WaMax automatically dispatches a POST request to your configured webhook URL enriched with AI analysis data (OCR, document summaries, video descriptions, and audio transcriptions).

POST YOUR_WEBHOOK_URL Inbound Webhook

Enriched AI Webhook Payload Schema

{
  "event": "message.inbound",
  "session_id": "qr_1781332832910_5eab537f",
  "mobid": "918281885620",
  "sender": "+91 82818 85620",
  "recipient": "+91 70127 29389",
  "message_id": "WAMID_9583495834",
  "timestamp": 1787756400,
  "content": {
    "text": "Please analyze this attached document and receipt image.",
    "media_url": "https://api.whatsapp.wywk.in/mediauploads/media_1787756.jpg",
    "mimetype": "image/jpeg",
    "image_description": "Receipt from TechStore Inc showing 2 items purchased totaling $120.00.",
    "ocr_text": "TECHSTORE INC\nDATE: 2026-08-26\nITEM 1: USB-C Cable - $20.00\nITEM 2: Wireless Mouse - $100.00\nTOTAL: $120.00",
    "document_explanation": null,
    "video_description": null,
    "transcription": null,
    "confidence": null
  }
}
POST /api/webhook/config Requires Token

Webhook & Approved Domains Configuration

Configure your webhook forwarding URL, security secret token, and whitelist allowed target domains for outbound webhooks.

Request Body Parameters

ParameterTypePresenceDescription
webhookUrl string Optional Target URL where incoming WhatsApp message events will be posted (e.g. "https://api.whatsapp.wywk.in/api/webhook/receiver").
secretToken string Optional Security token sent in the X-WaMax-Secret header with every webhook payload.
approvedDomains array | string Optional Whitelisted domains (e.g. ["api.whatsapp.wywk.in", "wamax.in", "wywk.in"] or comma-separated string). Webhooks to non-approved domains will be blocked for security. Use "*" to allow all domains. Can also be defined via WEBHOOK_APPROVED_DOMAINS in .env.
enabled boolean Optional Enable (true) or disable (false) automatic webhook forwarding.

cURL Example

curl -X POST "https://api.whatsapp.wywk.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", "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

FieldTypeRequirementDescription
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

FieldTypeRequirementDescription
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 ParamTypeRequirementDescription
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 ParamTypeRequirementDescription
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 FieldTypeRequirementDescription
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
Available Route Aliases: POST /api/send-message, POST /api/messages/send, POST /api/send-media, POST /api/send-button, POST /api/send-template

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

Base URL → https://api-wamax.whatyouwantkerala.in
• Endpoint: POST /api/send-message
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!"
  }'

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:

IdentifierTypeExampleDescription
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).
Resolution Order → mobidmobile_numbersession_id

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

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

ParameterTypeRequirementDescription
sessionIdstringOptionalSession key (e.g. "clinic" or "918304064190").
tenantstringOptionalTenant 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)

FieldTypeRequirementDescription
sessionIdstringRequiredTarget session key or tenant profile ID.
tenantstringOptionalTenant folder identifier (e.g., "appliances" or "ecommerce").
brainobjectRequiredFull 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!

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