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

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

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

cURL Example — Create Pairing Code Session

curl -X POST "https://wywk.in/api/sessions" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customSessionName": "WAMAX-PAIRCODE-20260815193000-800",
    "phoneNumber": "919800000000",
    "method": "pairingCode"
  }'

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.

7. 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"]
    ]
);
?>

8. 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 API Engine

WaMax Enterprise Messaging API Guide

API Navigation