Overview

This document provides detailed, developer-focused instructions for using the WhatsApp API. For interactive testing, we recommend using the API Control Center on the Admin Dashboard.

Making API Requests

Base URLs

💡

Important: The base URL format depends on your deployment environment:

Environment V1 API Base URL Legacy API Base URL
Local Development http://localhost:3000/api/v1 http://localhost:3000/api/v1/legacy
cPanel (HTTP) http://yourdomain.com/api/v1 http://yourdomain.com/api/v1/legacy
cPanel (HTTPS) https://yourdomain.com/api/v1 https://yourdomain.com/api/v1/legacy
Custom Port http://yourdomain.com:8080/api/v1 http://yourdomain.com:8080/api/v1/legacy
⚠ī¸

Note for cPanel users: Most cPanel deployments use standard HTTP/HTTPS ports (80/443), so you don't need to specify a port in your API calls. Just use your domain name directly.

Content-Type

For most endpoints, you will be sending data in JSON format. Ensure your requests include the Content-Type: application/json header. For file uploads, the API expects multipart/form-data.

Authentication

ℹī¸

All API requests to the /api/v1/* endpoints must be authenticated using a Bearer Token, with these exceptions:

  • POST /api/v1/sessions - Requires Master API Key OR admin authentication

The token is unique per session and is returned when you create a session. You can also view tokens in the Admin Dashboard.

Header Format

Authorization: Bearer <your_api_token>
⚠ī¸

Legacy endpoints have moved to /api/v1/legacy/* and now require Bearer token authentication.

cURL Example

curl ... -H "Authorization: Bearer your_api_token"

V1 API Endpoints

The V1 API provides comprehensive functionality for managing WhatsApp sessions, sending messages, and handling media.

📌

About the Examples: Most examples in this documentation use localhost:3000 for local development. If you're using cPanel or a production deployment:

  • Replace http://localhost:3000 with https://yourdomain.com
  • No port number is needed for standard HTTP/HTTPS deployments
  • Use HTTPS for production environments for better security

Session Management

POST /sessions

Create Session

Creates a new WhatsApp session with a unique ID. Requires Master API Key OR admin dashboard authentication.

Authentication:
  • Via API: Include X-Master-Key header with your master API key
  • Via Dashboard: Automatic when logged in as admin
Request Body (JSON):
JSON { "sessionId": "mySession" }
Success Response (JSON):
JSON { "status": "success", "message": "Session mySession created.", "token": "your-bearer-token-for-this-session" }
💡

Note: Save the returned token - it's required for all other API calls for this session.

cURL Examples:

Local Development:

curl -X POST 'http://localhost:3000/api/v1/sessions' \ -H 'X-Master-Key: your-master-api-key-from-env' \ -H 'Content-Type: application/json' \ -d '{ "sessionId": "mySession" }'

cPanel Deployment:

curl -X POST 'https://yourdomain.com/api/v1/sessions' \ -H 'X-Master-Key: your-master-api-key-from-env' \ -H 'Content-Type: application/json' \ -d '{ "sessionId": "mySession" }'
GET /sessions

List Sessions

Retrieves all sessions with their current status. Requires authentication.

Success Response (JSON):
JSON [ { "sessionId": "mySession", "status": "CONNECTED", "detail": "Connected as John Doe", "qr": null, "token": "session-token-here" }, { "sessionId": "anotherSession", "status": "DISCONNECTED", "detail": "Connection closed.", "qr": null, "token": "another-token-here" } ]
cURL Examples:

Local Development:

curl -X GET 'http://localhost:3000/api/v1/sessions'

cPanel Deployment:

curl -X GET 'https://yourdomain.com/api/v1/sessions'
DELETE /sessions/:sessionId

Delete Session

Deletes a specific session and all its data. Requires authentication.

cURL Example:
curl -X DELETE 'http://localhost:3000/api/v1/sessions/mySession' \ -H 'Authorization: Bearer your_api_token'
GET /sessions/:sessionId/qr

Get Session QR Code

Returns the current pairing QR code for a session that is waiting to be linked. Requires authentication.

cURL Example:
curl -X GET 'http://localhost:3000/api/v1/sessions/mySession/qr' \ -H 'Authorization: Bearer your_api_token'
GET /sessions/:id/groups

List Session Groups

Lists the WhatsApp groups the session is a member of. Requires authentication.

cURL Example:
curl -X GET 'http://localhost:3000/api/v1/sessions/mySession/groups' \ -H 'Authorization: Bearer your_api_token'

Webhook Management

POST /webhook

Set Webhook URL

Configures or updates the URL where the server will send event notifications for a specific session.

Request Body (JSON):
JSON { "sessionId": "mySession", "url": "https://your-webhook-receiver.com/events" }
cURL Example:
curl -X POST 'http://localhost:3000/api/v1/webhook' \ -H 'Authorization: Bearer your_api_token' \ -H 'Content-Type: application/json' \ -d '{ "sessionId": "mySession", "url": "https://your-webhook-receiver.com/events" }'
GET /webhook?sessionId=<your_session_id>

Get Webhook URL

Retrieves the configured webhook URL for a specific session.

Success Response (JSON):
JSON { "status": "success", "sessionId": "mySession", "url": "https://your-webhook-receiver.com/events" }
cURL Example:
curl -X GET 'http://localhost:3000/api/v1/webhook?sessionId=mySession' \ -H 'Authorization: Bearer your_api_token'
DELETE /webhook

Delete Webhook

Removes the webhook URL for a specific session. No events will be sent until a new webhook is set.

Request Body (JSON):
JSON { "sessionId": "mySession" }
cURL Example:
curl -X DELETE 'http://localhost:3000/api/v1/webhook' \ -H 'Authorization: Bearer your_api_token' \ -H 'Content-Type: application/json' \ -d '{ "sessionId": "mySession" }'
GET Webhook Events (inbound to your URL)

Webhook Event Payloads

When a webhook URL is configured for a session, the server sends JSON events to it. Each event has this envelope:

JSON { "event": "session.update | message.received", "sessionId": "mySession", "data": { ... }, "timestamp": "2024-12-20T10:00:00.000Z" }
session.update — data:
JSON { "status": "CONNECTED", "detail": "Connected as John Doe" }
message.received — data:
JSON { "from": "6281234567890@s.whatsapp.net", "text": "Hello!", "type": "conversation" }
💡

Deliveries are retried up to 3 times with exponential backoff. Webhook URLs must be HTTPS and may not point at private/local addresses (SSRF-guarded).

Media Management

POST /media

Upload Media

Uploads an image or document to the server's media directory. The server returns a mediaId which can be used to send the file in a subsequent API call.

⚠ī¸
File Restrictions:
  • Allowed types: JPEG, PNG, GIF, WebP, PDF, Word, Excel only
  • Maximum size: 25MB
  • MIME types: image/jpeg, image/png, image/gif, image/webp, application/pdf, application/msword, application/vnd.openxmlformats-officedocument.wordprocessingml.document, application/vnd.ms-excel, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
Request Body (form-data):
  • file: The media file to upload (must be JPEG, PNG, GIF, WebP, PDF, Word, or Excel; max 25MB).
Success Response (JSON):
JSON { "status": "success", "message": "File uploaded successfully.", "mediaId": "f7e3e7a0-5e7a-4b0f-8b9a-9e7d6e6e2c3d.jpg", "url": "/media/f7e3e7a0-5e7a-4b0f-8b9a-9e7d6e6e2c3d.jpg" }
Error Response (JSON):
JSON { "status": "error", "message": "Invalid file type. Only JPEG, PNG, GIF, WebP, PDF, Word, and Excel allowed." }
cURL Example:
# Replace /path/to/your/file.jpg with the actual file path curl -X POST 'http://localhost:3000/api/v1/media' \ -H 'Authorization: Bearer your_api_token' \ -F 'file=@/path/to/your/file.jpg'

Message Management

POST /messages?sessionId=<your_session_id>

Send Messages

A powerful and flexible endpoint to send various types of messages. You must specify the sessionId as a query parameter. You can send a single message (as a JSON object) or multiple messages in a batch (as a JSON array).

Common Body Fields (JSON):
Field Type Required Description
recipient_type string Yes individual or group
to string Yes Phone number (e.g., 628123...) or group ID
type string Yes text, image, or document
Type-Specific Fields:
Text Message:
JSON { "text": { "body": "Your message content here" } }
Image Message:
JSON { "image": { "link": "https://example.com/image.jpg", // OR "id": "mediaId-from-upload", "caption": "Optional caption" } }
Document Message:
JSON { "document": { "link": "https://example.com/document.pdf", // OR "id": "mediaId-from-upload", "mimetype": "application/pdf", "filename": "Optional_filename.pdf" } }
cURL Example (Single Text Message):
curl -X POST 'http://localhost:3000/api/v1/messages?sessionId=mySession' \ -H 'Authorization: Bearer your_api_token' \ -H 'Content-Type: application/json' \ -d '{ "recipient_type": "individual", "to": "6281234567890", "type": "text", "text": { "body": "Hello from the API!" } }'
cURL Example (Bulk Mixed Messages):
curl -X POST 'http://localhost:3000/api/v1/messages?sessionId=mySession' \ -H 'Authorization: Bearer your_api_token' \ -H 'Content-Type: application/json' \ -d '[ { "recipient_type": "individual", "to": "6281234567890", "type": "text", "text": { "body": "First message" } }, { "recipient_type": "individual", "to": "6289876543210", "type": "image", "image": { "link": "https://picsum.photos/200", "caption": "This is a test image." } } ]'
DELETE /message

Delete Message

Deletes a message that you have previously sent. You must provide the session ID, the recipient's JID, and the ID of the message to be deleted.

Request Body (JSON):
JSON { "sessionId": "mySession", "remoteJid": "6281234567890@s.whatsapp.net", "messageId": "3EB0D8E8D8F9A7B6" }
cURL Example:
curl -X DELETE 'http://localhost:3000/api/v1/message' \ -H 'Authorization: Bearer your_api_token' \ -H 'Content-Type: application/json' \ -d '{ "sessionId": "mySession", "remoteJid": "6281234567890@s.whatsapp.net", "messageId": "3EB0D8E8D8F9A7B6" }'

Campaign Management

Create and manage bulk WhatsApp messaging campaigns with scheduling, real-time progress tracking, and recipient list integration.

POST /campaigns

Create Campaign

Creates a new campaign with recipients and message content. Supports scheduling and various message types.

Request Body (JSON):
JSON { "name": "Product Launch Campaign", "sessionId": "mySession", "scheduledAt": "2024-12-20T10:00:00.000Z", // Optional "message": { "type": "text", // "text", "image", "document" "content": "Hello {{Name}}, check out our new product at {{Company}}!" }, "recipients": [ { "number": "6281234567890", "name": "John Doe", "companyName": "Tech Corp" } ], "settings": { "delayBetweenMessages": 3000, // milliseconds "maxRetries": 3 } }
cURL Example:
curl -X POST 'http://localhost:3000/api/v1/campaigns' \ -H 'Authorization: Bearer your_api_token' \ -H 'Content-Type: application/json' \ -d '{ "name": "Test Campaign", "sessionId": "mySession", "message": { "type": "text", "content": "Hello {{Name}}!" }, "recipients": [ {"number": "6281234567890", "name": "John"} ] }'
GET /campaigns

List Campaigns

Retrieves all campaigns created by the authenticated user (or all campaigns for admin users).

Success Response (JSON):
JSON [ { "id": "campaign_1234567890_abc123", "name": "Product Launch Campaign", "status": "completed", "createdAt": "2024-12-20T09:00:00.000Z", "scheduledAt": "2024-12-20T10:00:00.000Z", "recipientCount": 100, "statistics": { "total": 100, "sent": 95, "failed": 5, "pending": 0 } } ]
cURL Example:
curl -X GET 'http://localhost:3000/api/v1/campaigns' \ -H 'Authorization: Bearer your_api_token'
GET /campaigns/:campaignId

Get Campaign Details

Retrieves detailed information about a specific campaign, including full recipient list and delivery status.

cURL Example:
curl -X GET 'http://localhost:3000/api/v1/campaigns/campaign_1234567890_abc123' \ -H 'Authorization: Bearer your_api_token'
POST /campaigns/:campaignId/send

Start Campaign

Manually starts a campaign immediately, regardless of its scheduled time.

cURL Example:
curl -X POST 'http://localhost:3000/api/v1/campaigns/campaign_1234567890_abc123/send' \ -H 'Authorization: Bearer your_api_token'
POST /campaigns/:campaignId/pause

Pause Campaign

Pauses an active campaign. Can be resumed later.

cURL Example:
curl -X POST 'http://localhost:3000/api/v1/campaigns/campaign_1234567890_abc123/pause' \ -H 'Authorization: Bearer your_api_token'
POST /campaigns/:campaignId/resume

Resume Campaign

Resumes a paused campaign from where it left off.

cURL Example:
curl -X POST 'http://localhost:3000/api/v1/campaigns/campaign_1234567890_abc123/resume' \ -H 'Authorization: Bearer your_api_token'
DELETE /campaigns/:campaignId

Delete Campaign

Permanently deletes a campaign and all its data.

cURL Example:
curl -X DELETE 'http://localhost:3000/api/v1/campaigns/campaign_1234567890_abc123' \ -H 'Authorization: Bearer your_api_token'
GET /campaigns/:campaignId/export

Export Campaign Results (CSV)

Downloads the campaign's recipient delivery results as a CSV file. Cell values are formula-injection safe.

cURL Example:
curl -X GET 'http://localhost:3000/api/v1/campaigns/campaign_1234567890_abc123/export' \ -H 'Authorization: Bearer your_api_token'
GET /campaigns/:campaignId/status

Get Campaign Status

Returns the campaign's live status, progress and recipient statistics.

cURL Example:
curl -X GET 'http://localhost:3000/api/v1/campaigns/campaign_1234567890_abc123/status' \ -H 'Authorization: Bearer your_api_token'
POST /campaigns/:campaignId/retry

Retry Failed Recipients

Re-queues recipients whose delivery failed so the campaign can attempt them again.

cURL Example:
curl -X POST 'http://localhost:3000/api/v1/campaigns/campaign_1234567890_abc123/retry' \ -H 'Authorization: Bearer your_api_token'
GET /campaigns/csv-template

Download CSV Template

Downloads a template CSV for bulk recipient import.

POST /campaigns/preview-csv

Preview CSV Upload

Uploads a CSV (form-data field file) and returns parsed recipients with validation errors, without creating a campaign.

GET /campaigns/check-scheduled

Check Scheduled Campaigns

Returns campaigns whose scheduled time has passed and are ready to start.

GET /campaigns/overdue

Overdue Campaigns

Lists campaigns that missed their scheduled start.

Recipient Lists

Manage reusable recipient lists for campaigns. Create named lists that can be used across multiple campaigns.

POST /recipient-lists

Create Recipient List

Creates a new named recipient list that can be reused in multiple campaigns.

Request Body (JSON):
JSON { "name": "VIP Customers", "description": "High-value customers for exclusive offers", "tags": ["VIP", "Premium"], "recipients": [ { "number": "6281234567890", "name": "John Doe", "jobTitle": "CEO", "companyName": "Tech Corp" }, { "number": "6289876543210", "name": "Jane Smith", "jobTitle": "Marketing Director", "companyName": "Digital Agency" } ] }
cURL Example:
curl -X POST 'http://localhost:3000/api/v1/recipient-lists' \ -H 'Authorization: Bearer your_api_token' \ -H 'Content-Type: application/json' \ -d '{ "name": "Test List", "recipients": [ {"number": "6281234567890", "name": "John Doe"} ] }'
GET /recipient-lists

List Recipient Lists

Retrieves all recipient lists created by the authenticated user.

Query Parameters:
Parameter Type Description
search string Search lists by name or description
tag string Filter lists by tag
Success Response (JSON):
JSON [ { "id": "list_1234567890_abc123", "name": "VIP Customers", "description": "High-value customers", "tags": ["VIP", "Premium"], "recipientCount": 50, "createdAt": "2024-12-20T09:00:00.000Z", "lastUsed": "2024-12-20T10:30:00.000Z", "usageCount": 5 } ]
cURL Example:
curl -X GET 'http://localhost:3000/api/v1/recipient-lists?search=VIP' \ -H 'Authorization: Bearer your_api_token'
GET /recipient-lists/:listId

Get Recipient List Details

Retrieves detailed information about a specific recipient list, including all recipients.

cURL Example:
curl -X GET 'http://localhost:3000/api/v1/recipient-lists/list_1234567890_abc123' \ -H 'Authorization: Bearer your_api_token'
PUT /recipient-lists/:listId

Update Recipient List

Updates an existing recipient list. Can modify name, description, tags, and recipients.

Request Body (JSON):
JSON { "name": "Updated VIP Customers", "description": "Updated description", "tags": ["VIP", "Premium", "Updated"], "recipients": [ { "number": "6281234567890", "name": "John Doe Updated", "jobTitle": "Senior CEO", "companyName": "Tech Corp Ltd" } ] }
cURL Example:
curl -X PUT 'http://localhost:3000/api/v1/recipient-lists/list_1234567890_abc123' \ -H 'Authorization: Bearer your_api_token' \ -H 'Content-Type: application/json' \ -d '{ "name": "Updated List Name" }'
DELETE /recipient-lists/:listId

Delete Recipient List

Permanently deletes a recipient list. This action cannot be undone.

cURL Example:
curl -X DELETE 'http://localhost:3000/api/v1/recipient-lists/list_1234567890_abc123' \ -H 'Authorization: Bearer your_api_token'
POST /recipient-lists/:listId/clone

Clone Recipient List

Creates a copy of an existing recipient list with a new name.

Request Body (JSON):
JSON { "newName": "VIP Customers Copy" }
cURL Example:
curl -X POST 'http://localhost:3000/api/v1/recipient-lists/list_1234567890_abc123/clone' \ -H 'Authorization: Bearer your_api_token' \ -H 'Content-Type: application/json' \ -d '{ "newName": "VIP Customers Copy" }'
GET /recipient-lists/search/:query

Search Recipients

Searches all accessible lists for recipients matching a number, name, company or job title.

GET /recipient-lists-stats

Recipient List Statistics

Returns aggregate statistics: total lists, total recipients, total usage and average list size.

POST /recipient-lists/:listId/mark-used

Mark List as Used

Records usage of a list (increments usageCount, updates lastUsed).

POST /recipient-lists/:listId/recipients

Add Recipient

Adds a single recipient to a list.

JSON { "number": "6281234567890", "name": "John Doe", "jobTitle": "CEO", "companyName": "Tech Corp" }
PUT /recipient-lists/:listId/recipients/:number

Update Recipient

Updates the name, job title, company or custom fields of a specific recipient.

DELETE /recipient-lists/:listId/recipients/:number

Remove Recipient

Removes a specific recipient from a list.

Chats (Live Inbox)

Message history and reply endpoints used by the Live Inbox dashboard. Mounted at /api/v1/chats.

GET /chats?sessionId=<session_id>

List Conversations

Returns recent conversations for a session with unread counts.

GET /chats/:remoteJid/messages?sessionId=<session_id>

Chat History

Returns the message history with a specific contact (JID).

POST /chats/:remoteJid/send

Send Reply

Sends a reply message to a contact from the inbox.

JSON { "sessionId": "mySession", "message": "Hello!", "type": "text" }

Auto Replies

Keyword-triggered auto-response rules. Mounted at /api/v1/auto-replies.

GET /auto-replies

List Rules

POST /auto-replies

Create Rule

JSON { "sessionId": "mySession", "keyword": "PROMO", "matchType": "contains", "responseType": "text", "responsePayload": "Get 50% off today!" }
PUT /auto-replies/:id

Update Rule

DELETE /auto-replies/:id

Delete Rule

Analytics

Dashboard statistics. Mounted at /api/v1/analytics.

GET /analytics/summary

Summary

Total sessions, campaigns, auto-replies, recipient lists and chat messages.

GET /analytics/trends

Trends

Activity trends over time.

AI Chatbot

Configuration and sandbox testing for the AI auto-reply assistant.

GET /ai-config

Get AI Settings

Returns the current AI configuration (API key excluded).

POST /ai-config

Update AI Settings

JSON { "isEnabled": true, "provider": "openai", "model": "gpt-4o-mini", "apiKey": "sk-...", "systemPrompt": "You are a helpful assistant", "temperature": 0.7, "maxTokens": 500, "autoReplyUnmatched": true }
POST /ai-chatbot/test

Test Playground

Generates an AI response with the given settings without saving them.

JSON { "userPrompt": "Hello", "systemPrompt": "You are a helpful assistant", "model": "gpt-4o-mini", "apiKey": "sk-...", "apiBaseUrl": "https://api.openai.com/v1", "temperature": 0.7 }

User Management

Manage dashboard users. Requires Admin Session Authentication (these endpoints are primarily for the Dashboard).

GET /users

List Users

Retrieves a list of all users (Admin) or the current user (Non-Admin).

POST /users

Create User

Creates a new user. Admin only.

Request Body (JSON):
JSON { "email": "newuser@example.com", "password": "securepassword", "role": "user" }
PUT /users/:email

Update User

Updates a user's role, is_active or password. Admin only.

JSON { "role": "admin", "is_active": true }

Activity Logs

View system activity history. Requires Admin Session Authentication.

GET /activities

List Activities

Retrieves recent system activities.

GET /activities/summary

Activity Summary

Aggregated totals and per-action/per-user breakdown for the dashboard.

Legacy API Endpoints

⚠ī¸

Updated: Legacy endpoints now require Bearer token authentication and have moved to /api/v1/legacy/*. They are simpler but less flexible than the main API.

Base URL Examples:

Environment Base URL
Local Development http://localhost:3000/api/v1/legacy
cPanel (HTTPS) https://yourdomain.com/api/v1/legacy
POST /legacy/send-message

Send Text (JSON)

Simple endpoint to send a text message. Requires authentication.

Request Body (JSON):
JSON { "sessionId": "mySession", "number": "6281234567890", "message": "This is a legacy message." }
cURL Example:
curl -X POST 'http://localhost:3000/api/v1/legacy/send-message' \ -H 'Authorization: Bearer your_api_token' \ -H 'Content-Type: application/json' \ -d '{ "sessionId": "mySession", "number": "6281234567890", "message": "This is a legacy message." }'
POST /legacy/message

Send Text (Form Data)

Simple endpoint to send a text message using form data. Requires authentication.

Request Body (form-data):
  • phone: The recipient's phone number (8-15 digits).
  • message: The text message content (max 4096 chars).
  • sessionId (optional): The session to use. Defaults to putra.
cURL Example:
curl -X POST 'http://localhost:3000/api/v1/legacy/message' \ -H 'Authorization: Bearer your_api_token' \ -F 'phone=6281234567890' \ -F 'message=Hello from a form' \ -F 'sessionId=mySession'
💡

Rate Limiting: Legacy endpoints are limited to 10 requests per minute per IP address.