WaMax API Usage Guide | WhatYouWantKerala (wywk.in)

Complete Platform Feature Summary Matrix

All WhatsApp features supported by the WaMax engine on wywk.in

Feature Category	Supported Capabilities	Endpoint / Usage	Status
Session Engine	QR & 8-Digit Pairing Code Login, Custom Naming (`WAMAX-PAIRCODE-...`), Auto Reconnect	`POST /api/sessions`	Active
Lead Scrapper	Extract unique customer contacts by Session Name, Mobile Number, or MobID	`GET /api/contacts/scrape`	Active
Excel Export	Export scraped customer leads directly to downloadable Excel files	`POST /api/contacts/export`	Active
Standard Messaging	Text, High-Res Image (with Caption), Video, Audio (Voice Note/PTT), PDF Documents	`POST /api/messages/send`	Active
Interactive Buttons	Quick Reply & Call-To-Action buttons with custom IDs	`type: "buttons"`	Active
Sectioned List Menus	Dropdown options categorized into title sections with row descriptions	`type: "list"`	Active
Native WhatsApp Polls	Interactive multi-choice voting polls with customizable selection limits	`type: "poll"`	Active
Contact Cards (vCard)	Send rich business cards with contact name, phone, & organization	`type: "vcard"`	Active
Location Pin Map	Send precise GPS map coordinates with venue name & address	`type: "location"`	Active
Emoji Reactions	React to any previously sent or received message ID with emoji symbols	`type: "reaction"`	Active
Quoted Threading	Reply in context to specific message IDs using `quotedMessageId`	`quotedMessageId: "..."`	Active
Message Templates	Save and reuse pre-configured message templates for quick sending	`GET/POST /api/templates`	Active
Bulk CSV Broadcast	High-volume mass broadcast engine with variable insertion & rate-limiting	`POST /api/messages/bulk`	Active
Webhooks & Realtime SSE	Instant inbound message forwarding, delivery ACKs, and live EventSource stream	`POST /api/webhook/config`	Active

1. Authentication & Base URL

Security specs & authentication headers for wywk.in

All API requests must be transmitted over HTTPS to https://wywk.in (or https://socket.wywk.in). Requests require the Authorization header carrying your 201-character Bearer token.

Request Authorization Header

Authorization: Bearer YOUR_MASTER_AUTH_TOKEN

Header Key	Type	Description
Authorization	String *Required	Bearer token provided in portal / environment configuration.
Content-Type	String *Required	Must be `application/json` for all POST / PUT requests.

2. Session Management & ID Format

Create and manage sessions with custom naming rules

WaMax supports multi-device WhatsApp connection sessions. Sessions are created with standardized custom names:

Standard Session ID Format

QR Connection:       WAMAX-QR-YYYYMMDDHHMMSS-XXX
Pairing Code Conn:  WAMAX-PAIRCODE-YYYYMMDDHHMMSS-XXX

Example: WAMAX-PAIRCODE-20260815193000-800

POST /api/sessions - Connect New Number

Create a new WhatsApp socket session using QR code or 8-digit Pairing Code.

cURL Example - Create Session

curl -X POST "https://wywk.in/api/sessions" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "WAMAX-PAIRCODE-20261002120000-101",
    "name": "Support Line",
    "phoneNumber": "919876543210",
    "method": "phone"
  }'

GET /api/sessions/:id/pairing-code - Get 8-Digit Pairing Code

Retrieve the 8-character pairing code to link directly on WhatsApp (Settings > Linked Devices > Link with Phone Number).

curl -X GET "https://wywk.in/api/sessions/WAMAX-PAIRCODE-20261002120000-101/pairing-code" \
  -H "Authorization: Bearer YOUR_TOKEN"

GET /api/sessions/:id/qr - Get QR Code

Retrieve the base64 QR code or raw image for QR scan login.

curl -X GET "https://wywk.in/api/sessions/WAMAX-QR-20261002120000-102/qr" \
  -H "Authorization: Bearer YOUR_TOKEN"

POST /api/sessions/:id/relogin - Reconnect Existing Number

Trigger reconnection or session reboot for an existing disconnected or logged-out WhatsApp session without re-registering.

cURL Example - Reconnect Session

curl -X POST "https://wywk.in/api/sessions/WAMAX-PAIRCODE-20261002120000-101/relogin" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "method": "phone" }'

GET /api/sessions/usage/:identifier - Fetch API Credits & Usage Quota

Fetch remaining credits, total allowed limit, and current message usage by Phone Number, MobID, or Session ID.

cURL Example - Fetch Credits by Phone Number

curl -X GET "https://wywk.in/api/sessions/usage/919876543210" \
  -H "Authorization: Bearer YOUR_TOKEN"

Sample JSON Response

{
  "success": true,
  "sessionId": "WAMAX-PAIRCODE-20261002120000-101",
  "mobid": "981273918237192",
  "mobile_number": "919876543210",
  "usage": 24,
  "limit": 1000,
  "remaining": 976,
  "status": "READY"
}

POST /api/sessions/:id/toggles - Automation & Inbound Feature Toggles (Default: All OFF)

Configure operational toggles per session. All toggles strictly default to OFF (false).

Toggle Field	Default	Behavior
incoming_messages_enabled	false (OFF)	When false, incoming customer messages are completely ignored. When true, messages are tracked and sent to webhooks.
chatbot_enabled	false (OFF)	When false, incoming messages do not trigger chatbot auto-replies. When true, AI/keyword chatbot responds.
voice_reply_enabled	false (OFF)	When false, chatbot sends text only. When true, chatbot also sends native WhatsApp Voice Note (PTT) audio.

cURL Example - Toggle Automation Settings

curl -X POST "https://wywk.in/api/sessions/WAMAX-PAIRCODE-20261002120000-101/toggles" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "incoming_messages_enabled": true,
    "chatbot_enabled": true,
    "voice_reply_enabled": false
  }'

GET /api/sessions

Fetch status of all connected and registered WhatsApp sessions.

3. Lead Scrapper & Contact Export APIs

Extract customer phone numbers from incoming chat histories

If client accounts receive messages from multiple customers, you can extract unique customer leads by Session Name, Mobile Number, or MobID.

GET /api/contacts/scrape

cURL Example - Scrape Customer Leads

curl -X GET "https://wywk.in/api/contacts/scrape?session=WAMAX-PAIRCODE-20260815193000-800" \
  -H "Authorization: Bearer YOUR_TOKEN"

POST /api/contacts/export

cURL Example - Export Scraped Leads to Excel

curl -X POST "https://wywk.in/api/contacts/export" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "WAMAX-PAIRCODE-20260815193000-800",
    "format": "excel"
  }'

4. Complete Messaging APIs (All Message Types)

Transmit Text, Images, Videos, Audio, Voice Notes, and Documents

POST /api/messages/send

cURL Example - Send Text Message

curl -X POST "https://wywk.in/api/messages/send" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "WAMAX-PAIRCODE-20260815193000-800",
    "to": "919876543210",
    "type": "text",
    "text": "Hello from WhatYouWantKerala platform!"
  }'

cURL Example - Send Image with Caption

curl -X POST "https://wywk.in/api/messages/send" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "WAMAX-PAIRCODE-20260815193000-800",
    "to": "919876543210",
    "type": "image",
    "url": "https://wywk.in/assets/banner.png",
    "caption": "Check out our latest product catalog!"
  }'

cURL Example - Send Video Message

curl -X POST "https://wywk.in/api/messages/send" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "WAMAX-PAIRCODE-20260815193000-800",
    "to": "919876543210",
    "type": "video",
    "url": "https://wywk.in/assets/demo.mp4",
    "caption": "WaMax Product Demonstration"
  }'

cURL Example - Send WhatsApp Voice Note (PTT)

curl -X POST "https://wywk.in/api/messages/send" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "WAMAX-PAIRCODE-20260815193000-800",
    "to": "919876543210",
    "type": "voice",
    "url": "https://wywk.in/assets/audio.mp3",
    "duration": 12
  }'

cURL Example - Send Document PDF

curl -X POST "https://wywk.in/api/messages/send" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "WAMAX-PAIRCODE-20260815193000-800",
    "to": "919876543210",
    "type": "pdf",
    "url": "https://wywk.in/assets/invoice.pdf",
    "fileName": "Tax_Invoice_8849.pdf"
  }'

5. Interactive Messaging Payloads

Buttons, List Menus, Native Polls, Contacts, Location, & Emoji Reactions

cURL Example - Interactive Buttons

curl -X POST "https://wywk.in/api/messages/send" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "WAMAX-PAIRCODE-20260815193000-800",
    "to": "919876543210",
    "type": "buttons",
    "title": "Welcome to WaMax",
    "text": "Please choose an action below:",
    "footer": "WhatYouWantKerala Support",
    "buttons": [
      { "buttonId": "btn_1", "displayText": "📞 Contact Support", "type": 1 },
      { "buttonId": "btn_2", "displayText": "🌐 Visit wywk.in", "type": 1 }
    ]
  }'

cURL Example - Interactive List Menu

curl -X POST "https://wywk.in/api/messages/send" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "WAMAX-PAIRCODE-20260815193000-800",
    "to": "919876543210",
    "type": "list",
    "title": "Service Options",
    "text": "Select a product category from the menu below:",
    "buttonText": "View Options",
    "sections": [
      {
        "title": "Core Services",
        "rows": [
          { "rowId": "s1", "title": "WhatsApp Socket API", "description": "Multi-session messaging engine" },
          { "rowId": "s2", "title": "Lead Scrapper", "description": "Automated contact extraction" }
        ]
      }
    ]
  }'

cURL Example - Native WhatsApp Poll

curl -X POST "https://wywk.in/api/messages/send" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "WAMAX-PAIRCODE-20260815193000-800",
    "to": "919876543210",
    "type": "poll",
    "title": "Which feature do you use most?",
    "options": ["Interactive Buttons", "Lead Scrapper", "Voice Notes"],
    "selectableCount": 1
  }'

cURL Example - vCard / Contact Card

curl -X POST "https://wywk.in/api/messages/send" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "WAMAX-PAIRCODE-20260815193000-800",
    "to": "919876543210",
    "type": "vcard",
    "name": "Customer Support",
    "phone": "919800000000",
    "organization": "WhatYouWantKerala"
  }'

cURL Example - Location Map Pin

curl -X POST "https://wywk.in/api/messages/send" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "WAMAX-PAIRCODE-20260815193000-800",
    "to": "919876543210",
    "type": "location",
    "latitude": 9.9312,
    "longitude": 76.2673,
    "name": "WhatYouWantKerala HQ",
    "address": "Kochi, Kerala, India"
  }'

cURL Example - Emoji Reaction & Quoted Reply

curl -X POST "https://wywk.in/api/messages/send" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "WAMAX-PAIRCODE-20260815193000-800",
    "to": "919876543210",
    "type": "reaction",
    "text": "❤️",
    "messageId": "WAMAX_MSG_1786817862514"
  }'

6. Message Templates & Bulk Broadcast Engine

Pre-saved templates and mass campaign transmission

POST /api/templates

cURL Example - Save New Message Template

curl -X POST "https://wywk.in/api/templates" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Welcome_Promo",
    "category": "Marketing",
    "type": "text",
    "content": "Hello {{name}}, welcome to WhatYouWantKerala! Use code {{code}} for 10% off."
  }'

POST /api/messages/bulk

cURL Example - Trigger Bulk Campaign Broadcast

curl -X POST "https://wywk.in/api/messages/bulk" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "WAMAX-PAIRCODE-20260815193000-800",
    "recipients": [
      { "to": "919876543210", "params": { "name": "Rahul", "code": "SAVE10" } },
      { "to": "919876543211", "params": { "name": "Anu", "code": "SAVE10" } }
    ],
    "templateId": "Welcome_Promo",
    "delayMs": 2000
  }'

7. AI Chatbot Configuration & Extracted Data Sync APIs

Manage tenant brains/prompts & sync AI-extracted booking JSON records (7-Day Retention & Live SSE)

Client applications can read/write tenant chatbot configurations and stream AI-extracted appointment & lead records into their external databases in real time.

GET /api/v1/chatbot/extracted-data

Fetch 7-day retained AI-extracted booking & lead JSON records for a session.

cURL Example - Fetch Extracted JSON Records

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

GET /api/v1/chatbot/extracted-stream (Server-Sent Events)

Live SSE stream for real-time syncing of extracted JSON payloads into client custom UIs/DBs.

JavaScript EventSource Example - Live Stream to Client DB

const eventSource = new EventSource('/api/v1/chatbot/extracted-stream?sessionKey=clinic');

eventSource.onmessage = (event) => {
    const data = JSON.parse(event.data);
    console.log('Live Extracted Data Received:', data);
    if (data.type === 'INIT' || data.records) {
        // Sync to custom client database
        syncToClientDatabase(data.records);
    }
};

GET /api/chatbot/brain

Read current brain.json configuration for a specific tenant session key.

cURL Example - Fetch Brain JSON

curl -X GET "https://wywk.in/api/chatbot/brain?sessionId=clinic"

POST /api/chatbot/brain

Save/Update runtime brain.json configuration payload.

cURL Example - Update Brain JSON

curl -X POST "https://wywk.in/api/chatbot/brain" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "clinic",
    "brain": {
      "businessName": "CarePlus Medical Center",
      "contactPhone": "+91 98460 12345",
      "workingHours": "09:00 AM - 08:00 PM"
    }
  }'

8. Voice Note AI Processing Engine (Deepgram STT & TTS)

Automated Speech-To-Text transcription, Intent Recognition, and Text-To-Speech response audio generation

The platform provides end-to-end voice note capabilities for WhatsApp voice messaging:

Pipeline Stage	Technology / AI Engine	Function
1. Voice STT Transcription	Deepgram Aura STT / Whisper	Converts inbound WhatsApp Voice Notes (ogg/mp3 PTT) into clean transcribed text.
2. Intent Detection	Gemini / OpenRouter / Puter JS	Extracts booking details, patient relationships, services, and user query intents.
3. Voice TTS Response	Deepgram Aura TTS	Converts AI text responses back into natural voice audio for instant WhatsApp PTT reply.

9. Webhooks & Inbound Real-time Event APIs

Receive incoming WhatsApp messages, media, reactions, button clicks, and message delivery status updates

WaMax provides bi-directional communication. When a user sends a message or reacts to one, the gateway delivers a webhook event payload directly to your configured HTTP endpoint, or through a persistent Server-Sent Events (SSE) live stream.

POST /api/webhook/config

Configure or update the webhook callback URL, security token, and subscribed events.

cURL Example - Configure Webhook

curl -X POST "https://wywk.in/api/webhook/config" \
  -H "Authorization: Bearer YOUR_MASTER_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookUrl": "https://your-crm-server.com/api/whatsapp-webhook",
    "secretToken": "YOUR_OPTIONAL_WEBHOOK_SECRET",
    "enabled": true,
    "live_stream_enabled": true,
    "events": ["message.inbound", "message.outbound", "session.status"]
  }'

GET /api/webhook/config

Retrieve current webhook configuration, approved domains, and active status.

cURL Example - Get Webhook Status

curl -X GET "https://wywk.in/api/webhook/config" \
  -H "Authorization: Bearer YOUR_MASTER_AUTH_TOKEN"

Inbound Message Webhook Payload Structure

When an incoming message arrives, the following JSON is dispatched to your webhook URL with header X-WaMax-Secret:

Sample JSON - Inbound Message with Ephemeral Media

{
  "event": "message.inbound",
  "sessionId": "WAMAX-PAIRCODE-20260815193000-800",
  "mobid": "919876543210",
  "message_id": "3EB0ABC123DEF456",
  "datetime": "2026-10-01T18:30:00.000Z",
  "direction": "inbound",
  "chat_type": "individual",
  "is_group": false,
  "sender": {
    "phone": "919876543210",
    "jid": "919876543210@s.whatsapp.net",
    "name": "Rahul"
  },
  "message": {
    "type": "image",
    "text": "Please check this photo",
    "media_url": "https://wywk.in/mediauploads/media_1727807400_5432.jpg",
    "mimetype": "image/jpeg",
    "fileName": "media_1727807400_5432.jpg",
    "image_description": "A clear medical invoice with total amount Rs 450",
    "ocr_text": "CarePlus Medical Center Invoice #8849",
    "transcription": null
  }
}

Option B: Zero-Storage Ephemeral Media Note

Incoming media files (image, voice, video, document) are protected under Ephemeral Zero-Storage Mode. The file at media_url remains accessible for a 2-minute grace period so your webhook receiver or CRM can download and persist it to your own storage. After 2 minutes, the server permanently auto-purges the temporary file to protect privacy and save server disk space.

GET /view/messages/stream (Live SSE Stream)

For real-time browser apps, CRM dashboards, or local development without a public webhook URL, use the real-time SSE stream:

JavaScript EventSource Example - Real-Time Message Stream

const stream = new EventSource('https://wywk.in/view/messages/stream?sessionId=WAMAX-PAIRCODE-20260815193000-800');

stream.onmessage = (event) => {
    const payload = JSON.parse(event.data);
    if (payload.event === 'message.inbound') {
        console.log(`New message from ${payload.sender.phone}: ${payload.message.text}`);
    }
};

stream.onerror = (err) => {
    console.error('SSE connection error:', err);
};

10. Official Client SDK Kits & Downloads

Pre-packaged helper libraries for PHP, Node.js, Python, and Postman

Download ready-to-use SDK classes for your development language. Each SDK encapsulates authorization, JSON payload construction, and response handling for instant integration into any website or application.

PHP SDK Helper

Complete PHP cURL wrapper for Laravel, WordPress, and custom PHP apps.

Node.js SDK

Asynchronous Axios/Fetch wrapper for Node.js, Express, and Next.js.

Python SDK

Python Requests wrapper for Django, Flask, and automation scripts.

Postman Collection

Importable Postman collection with all pre-configured API endpoints.

Quick PHP Usage Example

WaMaxClient.php Example

<?php
require_once 'WaMaxClient.php';

$wamax = new WaMaxClient("https://your-domain.com", "YOUR_MASTER_TOKEN");

// Send Text
$wamax->sendText("WAMAX-PAIRCODE-20260815193000-800", "919876543210", "Hello from PHP SDK!");

// Send Interactive Buttons
$wamax->sendButtons(
    "WAMAX-PAIRCODE-20260815193000-800",
    "919876543210",
    "Order Confirmation",
    "Your order #1042 is confirmed!",
    "WhatYouWantKerala",
    [
        ["id" => "btn_track", "text" => "🚚 Track Order"],
        ["id" => "btn_support", "text" => "💬 Contact Support"]
    ]
);
?>

11. System Status & Validation Error Codes

Standardized error responses

HTTP Status	Error Reason	Description / Recommended Action
400 Bad Request	Invalid Payload / Missing Field	Required parameter (e.g. `to`, `type`, `text`, or `url`) is missing.
401 Unauthorized	Invalid Auth Token	The Bearer token in the Authorization header is invalid or missing.
403 Forbidden	Session Inactive / Limit Exceeded	Session is logged out or message limit has been reached for this number.
404 Not Found	Session Not Found	Session ID specified in request body does not exist in database.

WaMax Enterprise Messaging API Guide

API Navigation