API Documentation

Complete guide to integrate WhatsApp messaging into your applications

Butuh API key?

Getting Started

All requests use a single base URL and require an API key header.

Base URL

All API requests require authentication. Include your API key in the X-API-Key header.

GET https://your-domain.com/api/sessions

Authentication

Include your API key in every request using the X-API-Key header.

Required Header

X-API-Key: YOUR_API_KEY

Security Requirements
All API requests must use HTTPS/SSL encryption. Never expose your API key in client-side code or public repositories. Store API keys securely in environment variables.

Get Sessions

Get session counts for your account.

GET /api/sessions

Request

curl -X GET https://your-domain.com/api/sessions \
  -H "X-API-Key: YOUR_API_KEY"

const response = await fetch('https://your-domain.com/api/sessions', {
  headers: { 'X-API-Key': 'YOUR_API_KEY' }
});
const data = await response.json();

import requests

response = requests.get(
    'https://your-domain.com/api/sessions',
    headers={'X-API-Key': 'YOUR_API_KEY'}
)
print(response.json())

Response

200 OK

{
  "success": true,
  "counts": {
    "total": 5,
    "connected": 3,
    "connecting": 1,
    "qr": 1,
    "disconnected": 0
  }
}

Possible errors: 401 403 500

Create Session

Create a new WhatsApp session.

POST /api/sessions

Request

curl -X POST https://your-domain.com/api/sessions \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"sessionName": "My Business Account"}'

const response = await fetch('https://your-domain.com/api/sessions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({ sessionName: 'My Business Account' })
});
const data = await response.json();

import requests

response = requests.post(
    'https://your-domain.com/api/sessions',
    headers={'Content-Type': 'application/json', 'X-API-Key': 'YOUR_API_KEY'},
    json={'sessionName': 'My Business Account'}
)
print(response.json())

Response

201 Created

{
  "success": true,
  "sessionId": "abc-123-def-456",
  "message": "Session created successfully"
}

Possible errors: 400 401 403 500

Session Status

Get detailed status of a specific session.

GET /api/sessions/:sessionId

Request

curl -X GET https://your-domain.com/api/sessions/abc-123-def-456 \
  -H "X-API-Key: YOUR_API_KEY"

const sessionId = 'abc-123-def-456';
const response = await fetch(`https://your-domain.com/api/sessions/${sessionId}`, {
  headers: { 'X-API-Key': 'YOUR_API_KEY' }
});
const data = await response.json();

import requests

session_id = 'abc-123-def-456'
response = requests.get(
    f'https://your-domain.com/api/sessions/{session_id}',
    headers={'X-API-Key': 'YOUR_API_KEY'}
)
print(response.json())

Response

200 OK

{
  "success": true,
  "session": {
    "id": "abc-123-def-456",
    "name": "My Business Account",
    "status": "connected",
    "phone_number": "1234567890",
    "created_at": "2024-01-01T00:00:00.000Z",
    "isConnected": true
  }
}

Status values: connecting qr connected disconnected

Possible errors: 401 403 404 500

QR Code

Get QR code for session authentication. Returns a base64-encoded PNG.

GET /api/sessions/:sessionId/qr

Request

curl -X GET https://your-domain.com/api/sessions/abc-123-def-456/qr \
  -H "X-API-Key: YOUR_API_KEY"

const sessionId = 'abc-123-def-456';
const response = await fetch(`https://your-domain.com/api/sessions/${sessionId}/qr`, {
  headers: { 'X-API-Key': 'YOUR_API_KEY' }
});
const data = await response.json();
// Use data.qrCode as img src:

import requests

session_id = 'abc-123-def-456'
response = requests.get(
    f'https://your-domain.com/api/sessions/{session_id}/qr',
    headers={'X-API-Key': 'YOUR_API_KEY'}
)
data = response.json()
# data['qrCode'] is a base64 PNG string

Response

200 OK

{
  "success": true,
  "qrCode": "data:image/png;base64,iVBORw0KGgo..."
}

Possible errors: 401 403 404 500

Reconnect Session

Reconnect a session — clears old credentials and generates a new QR code.

POST /api/sessions/:sessionId/reconnect

Request

curl -X POST https://your-domain.com/api/sessions/abc-123-def-456/reconnect \
  -H "X-API-Key: YOUR_API_KEY"

const sessionId = 'abc-123-def-456';
const response = await fetch(`https://your-domain.com/api/sessions/${sessionId}/reconnect`, {
  method: 'POST',
  headers: { 'X-API-Key': 'YOUR_API_KEY' }
});
const data = await response.json();

import requests

session_id = 'abc-123-def-456'
response = requests.post(
    f'https://your-domain.com/api/sessions/{session_id}/reconnect',
    headers={'X-API-Key': 'YOUR_API_KEY'}
)
print(response.json())

This will clear old credentials and require re-scanning the QR code.

Response

200 OK

{
  "success": true,
  "message": "Session reconnection initiated"
}

Possible errors: 401 403 404 500

Delete Session

Permanently delete a session and all its configurations.

DELETE /api/sessions/:sessionId

Request

curl -X DELETE https://your-domain.com/api/sessions/abc-123-def-456 \
  -H "X-API-Key: YOUR_API_KEY"

const sessionId = 'abc-123-def-456';
const response = await fetch(`https://your-domain.com/api/sessions/${sessionId}`, {
  method: 'DELETE',
  headers: { 'X-API-Key': 'YOUR_API_KEY' }
});
const data = await response.json();

import requests

session_id = 'abc-123-def-456'
response = requests.delete(
    f'https://your-domain.com/api/sessions/{session_id}',
    headers={'X-API-Key': 'YOUR_API_KEY'}
)
print(response.json())

Warning: This action cannot be undone. All auto-replies and AI configurations will be deleted.

Response

200 OK

{
  "success": true,
  "message": "Session deleted successfully"
}

Possible errors: 401 403 404 500

Send Message

Send a text message via WhatsApp. Validates the recipient number by default.

POST /api/sessions/:sessionId/send

Parameters

Param	Type	Required	Description
`to`	string	Required	Phone number with country code (without +)
`message`	string	Required	Message text (max 4096 characters)
`skipValidation`	boolean	Optional	Skip WhatsApp number validation (default: false)

Request

curl -X POST https://your-domain.com/api/sessions/abc-123/send \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "to": "6281234567890",
    "message": "Hello from WhatsApp API!"
  }'

const sessionId = 'abc-123';
const response = await fetch(`https://your-domain.com/api/sessions/${sessionId}/send`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    to: '6281234567890',
    message: 'Hello from WhatsApp API!'
  })
});
const data = await response.json();

import requests

session_id = 'abc-123'
response = requests.post(
    f'https://your-domain.com/api/sessions/{session_id}/send',
    headers={'Content-Type': 'application/json', 'X-API-Key': 'YOUR_API_KEY'},
    json={'to': '6281234567890', 'message': 'Hello from WhatsApp API!'}
)
print(response.json())

Smart Validation: By default, the API validates that the phone number is registered on WhatsApp before sending. Set skipValidation: true to bypass this check.

Response

200 OK

{
  "success": true,
  "messageId": "3EB0C767D71D8D6E2CD5",
  "message": "Message sent successfully"
}

Show error response (400 — invalid number)

{
  "success": false,
  "error": "Invalid WhatsApp Number",
  "message": "The phone number is not registered on WhatsApp.",
  "phoneNumber": "6281234567890"
}

Possible errors: 400 401 403 404 429 500

Send Media

Send media files (images, videos, audio, documents) via multipart/form-data.

POST /api/sessions/:sessionId/send-media

Parameters (multipart/form-data)

Param	Type	Required	Description
`to`	string	Required	Phone number with country code
`media`	file	Required	File to send (max 50 MB)
`message`	string	Optional	Caption for the media

Images

.jpg .jpeg .png .gif .webp

Videos

.mp4 .avi .mov .mkv .webm

Audio

.mp3 .wav .ogg .m4a .aac

Documents

.pdf .doc .docx .xls .xlsx

Request

curl -X POST https://your-domain.com/api/sessions/abc-123/send-media \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "to=6281234567890" \
  -F "message=Check this out!" \
  -F "media=@/path/to/image.jpg"

import { readFileSync } from 'fs';

const sessionId = 'abc-123';
const form = new FormData();
form.append('to', '6281234567890');
form.append('message', 'Check this out!');
form.append('media', new Blob([readFileSync('/path/to/image.jpg')]), 'image.jpg');

const response = await fetch(`https://your-domain.com/api/sessions/${sessionId}/send-media`, {
  method: 'POST',
  headers: { 'X-API-Key': 'YOUR_API_KEY' },
  body: form
});
const data = await response.json();

import requests

session_id = 'abc-123'
with open('/path/to/image.jpg', 'rb') as f:
    response = requests.post(
        f'https://your-domain.com/api/sessions/{session_id}/send-media',
        headers={'X-API-Key': 'YOUR_API_KEY'},
        data={'to': '6281234567890', 'message': 'Check this out!'},
        files={'media': f}
    )
print(response.json())

Response

200 OK

{
  "success": true,
  "messageId": "3EB0C767D71D8D6E2CD5",
  "message": "Media sent successfully"
}

Possible errors: 400 401 403 404 429 500

Check Numbers

Validate if phone numbers are registered on WhatsApp. Up to 100 numbers per request.

POST /api/number-checker

Parameters

Param	Type	Required	Description
`sessionId`	string	Required	Session ID to use for checking
`phoneNumbers`	array	Required	Array of phone numbers with country code (max 100)

Request

curl -X POST https://your-domain.com/api/number-checker \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "sessionId": "abc-123-def-456",
    "phoneNumbers": ["6281234567890", "6289876543210"]
  }'

const response = await fetch('https://your-domain.com/api/number-checker', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    sessionId: 'abc-123-def-456',
    phoneNumbers: ['6281234567890', '6289876543210']
  })
});
const data = await response.json();
console.log(`Valid: ${data.summary.valid}, Invalid: ${data.summary.invalid}`);

import requests

response = requests.post(
    'https://your-domain.com/api/number-checker',
    headers={'Content-Type': 'application/json', 'X-API-Key': 'YOUR_API_KEY'},
    json={
        'sessionId': 'abc-123-def-456',
        'phoneNumbers': ['6281234567890', '6289876543210']
    }
)
data = response.json()
print(f"Valid: {data['summary']['valid']}, Invalid: {data['summary']['invalid']}")

Rate Limits: Each phone number checked consumes one check from your monthly quota. Check your plan details for your monthly limit.

Response

200 OK

{
  "success": true,
  "message": "Number check completed",
  "summary": {
    "total": 2,
    "valid": 1,
    "invalid": 1
  },
  "results": [
    { "phoneNumber": "6281234567890", "isValid": true,  "status": "valid"   },
    { "phoneNumber": "6289876543210", "isValid": false, "status": "invalid" }
  ]
}

Show error response (403 — limit reached)

{
  "success": false,
  "error": "Number check limit reached",
  "limit": 1000,
  "used": 1000,
  "remaining": 0,
  "message": "You have reached your number check limit. Please upgrade your plan."
}

Possible errors: 400 401 403 429 500

Error Codes

Standard HTTP status codes indicate success or failure.

Code	Error	How to fix
401	Unauthorized	API key tidak valid atau tidak disertakan — cek header `X-API-Key`
403	Forbidden	Resource milik user lain — pastikan pakai session milik sendiri
404	Not Found	Session atau resource tidak ditemukan — cek sessionId dan path endpoint
429	Too Many Requests	Rate limit tercapai — backoff dan coba lagi dalam ~1 menit
500	Internal Server Error	Server error — hubungi support jika terjadi berulang

Error Response Format

{
  "success": false,
  "error": "Bad Request",
  "message": "Phone number and message are required"
}

Code Examples

Ready-to-use full integration snippets.

Send Message

curl -X POST https://your-domain.com/api/sessions/YOUR_SESSION_ID/send \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"to": "6281234567890", "message": "Hello from the API!"}'

const API_KEY = 'YOUR_API_KEY';
const BASE_URL = 'https://your-domain.com/api';
const SESSION_ID = 'YOUR_SESSION_ID';

async function sendMessage(to, message) {
  const response = await fetch(`${BASE_URL}/sessions/${SESSION_ID}/send`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': API_KEY
    },
    body: JSON.stringify({ to, message })
  });
  return response.json();
}

sendMessage('6281234567890', 'Hello from JavaScript!')
  .then(data => console.log(data));

import requests

API_KEY = 'YOUR_API_KEY'
BASE_URL = 'https://your-domain.com/api'
SESSION_ID = 'YOUR_SESSION_ID'

def send_message(to, message):
    url = f'{BASE_URL}/sessions/{SESSION_ID}/send'
    headers = {
        'Content-Type': 'application/json',
        'X-API-Key': API_KEY
    }
    response = requests.post(url, json={'to': to, 'message': message}, headers=headers)
    return response.json()

result = send_message('6281234567890', 'Hello from Python!')
print(result)

Check WhatsApp Numbers

curl -X POST https://your-domain.com/api/number-checker \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "sessionId": "YOUR_SESSION_ID",
    "phoneNumbers": ["6281234567890", "6289876543210", "6285551234567"]
  }'

const API_KEY = 'YOUR_API_KEY';
const BASE_URL = 'https://your-domain.com/api';
const SESSION_ID = 'YOUR_SESSION_ID';

async function checkNumbers(phoneNumbers) {
  const response = await fetch(`${BASE_URL}/number-checker`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': API_KEY
    },
    body: JSON.stringify({ sessionId: SESSION_ID, phoneNumbers })
  });
  const data = await response.json();
  console.log(`Valid: ${data.summary.valid}, Invalid: ${data.summary.invalid}`);
  data.results.forEach(r => console.log(`${r.phoneNumber}: ${r.status}`));
  return data;
}

checkNumbers(['6281234567890', '6289876543210', '6285551234567']);

import requests

API_KEY = 'YOUR_API_KEY'
BASE_URL = 'https://your-domain.com/api'
SESSION_ID = 'YOUR_SESSION_ID'

def check_numbers(phone_numbers):
    url = f'{BASE_URL}/number-checker'
    headers = {'Content-Type': 'application/json', 'X-API-Key': API_KEY}
    data = {'sessionId': SESSION_ID, 'phoneNumbers': phone_numbers}
    response = requests.post(url, json=data, headers=headers)
    result = response.json()
    print(f"Valid: {result['summary']['valid']}, Invalid: {result['summary']['invalid']}")
    for r in result['results']:
        print(f"{r['phoneNumber']}: {r['status']}")
    return result

numbers = ['6281234567890', '6289876543210', '6285551234567']
check_numbers(numbers)