WhatsApp API Documentation

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`
cPanel (HTTP)	`http://yourdomain.com/api/v1`	`http://yourdomain.com/api`
cPanel (HTTPS)	`https://yourdomain.com/api/v1`	`https://yourdomain.com/api`
Custom Port	`http://yourdomain.com:8080/api/v1`	`http://yourdomain.com:8080/api`

⚠️

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
GET /api/v1/sessions - Lists all sessions (public endpoint)

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 at /api/* do not require 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. No authentication required.

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'

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

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/start

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/start' \
-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'

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

Legacy API Endpoints

ℹ️

These endpoints are provided for backward compatibility. They are simpler but less flexible and do not require token authentication.

Base URL Examples:

Environment	Base URL
Local Development	`http://localhost:3000/api`
cPanel (HTTP)	`http://yourdomain.com/api`
cPanel (HTTPS)	`https://yourdomain.com/api`

POST /send-message

Send Text (JSON)

Request Body (JSON):

                        JSON
{
    "sessionId": "mySession",
    "number": "6281234567890",
    "message": "This is a legacy message."
}
                    

cURL Example:

curl -X POST 'http://localhost:3000/api/send-message' \
-H 'Content-Type: application/json' \
-d '{
    "sessionId": "mySession",
    "number": "6281234567890",
    "message": "This is a legacy message."
}'

POST /message

Send Text (Form Data)

Request Body (form-data):

phone: The recipient's phone number.
message: The text message content.
sessionId (optional): The session to use. Defaults to putra.

cURL Example:

curl -X POST 'http://localhost:3000/api/message' \
-F 'phone=6281234567890' \
-F 'message=Hello from a form' \
-F 'sessionId=mySession'