WhatsApp API Documentation

Complete REST API for WhatsApp Web automation. Send messages, media, manage contacts, and receive real-time webhooks. Test endpoints directly from this page!

INFO Authentication How to authenticate API requests

All API requests require authentication using your API key in the header.

Header	Description	Required
`X-API-Key`	Your unique API key	Required
`X-Session-ID`	Session ID (1, 2, SESSION_1, or full format)	Optional
`Content-Type`	application/json (for JSON requests)	Required for POST

⚠️

Content-Type Header

Make sure to set Content-Type: application/json without quotes around the value.

Status & Connection

GET /api/status Get connection status

Returns the current connection status of the WhatsApp session.

cURL

curl -X GET "http://localhost:3000/api/status" \
  -H "X-API-Key: your-api-key" \
  -H "X-Session-ID: 1"

Python

# Python - requests library
import requests

response = requests.get(
    "http://localhost:3000/api/status",
    headers={
        "X-API-Key": "your-api-key",
        "X-Session-ID": "1"
    }
)
print(response.json())

JavaScript

// JavaScript - fetch API
const response = await fetch("http://localhost:3000/api/status", {
    headers: {
        "X-API-Key": "your-api-key",
        "X-Session-ID": "1"
    }
});
const data = await response.json();
console.log(data);

Ruby

# Ruby - net/http
require 'net/http'
require 'json'

uri = URI("http://localhost:3000/api/status")
http = Net::HTTP.new(uri.host, uri.port)
request = Net::HTTP::Get.new(uri)
request["X-API-Key"] = "your-api-key"
request["X-Session-ID"] = "1"

response = http.request(request)
puts JSON.parse(response.body)

Response

{
  "success": true,
  "sessionId": "admin-key-session-1",
  "status": "ready",
  "info": {
    "pushname": "John Doe",
    "phone": "919876543210",
    "platform": "android"
  }
}

Messages

POST /api/message/send Send a text message

Send a text message to a phone number or group.

Parameter	Type	Description
`to`	string	Phone number (e.g., 919876543210) Required
`message`	string	Message text Required

Phone Number

Message

cURL

curl -X POST "http://localhost:3000/api/message/send" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -H "X-Session-ID: 1" \
  -d '{"to": "919876543210", "message": "Hello!"}'

Python

import requests

response = requests.post(
    "http://localhost:3000/api/message/send",
    headers={
        "X-API-Key": "your-api-key",
        "X-Session-ID": "1",
        "Content-Type": "application/json"
    },
    json={"to": "919876543210", "message": "Hello!"}
)
print(response.json())

JavaScript

const response = await fetch("http://localhost:3000/api/message/send", {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        "X-API-Key": "your-api-key",
        "X-Session-ID": "1"
    },
    body: JSON.stringify({
        to: "919876543210",
        message: "Hello!"
    })
});
console.log(await response.json());

Ruby

require 'net/http'
require 'json'

uri = URI("http://localhost:3000/api/message/send")
http = Net::HTTP.new(uri.host, uri.port)
request = Net::HTTP::Post.new(uri)
request["Content-Type"] = "application/json"
request["X-API-Key"] = "your-api-key"
request["X-Session-ID"] = "1"
request.body = {to: "919876543210", message: "Hello!"}.to_json

response = http.request(request)
puts JSON.parse(response.body)

Response

{
  "success": true,
  "messageId": "true_919876543210@c.us_XXXXX",
  "to": "919876543210@c.us",
  "toNumber": "919876543210",
  "timestamp": 1704067200
}

POST /api/message/send-bulk Send message to multiple recipients

Send a message to multiple phone numbers at once.

Parameter	Type	Description
`recipients`	array	Array of phone numbers Required
`message`	string	Message text Required

Recipients (comma-separated)

Message

Python

import requests

response = requests.post(
    "http://localhost:3000/api/message/send-bulk",
    headers={"X-API-Key": "your-api-key", "X-Session-ID": "1", "Content-Type": "application/json"},
    json={"recipients": ["919876543210", "919876543211"], "message": "Hello!"}
)
print(response.json())

JavaScript

const response = await fetch("http://localhost:3000/api/message/send-bulk", {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        "X-API-Key": "your-api-key",
        "X-Session-ID": "1"
    },
    body: JSON.stringify({
        recipients: ["919876543210", "919876543211"],
        message: "Hello!"
    })
});
console.log(await response.json());

cURL

curl -X POST "http://localhost:3000/api/message/send-bulk" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -H "X-Session-ID: 1" \
  -d '{"recipients": ["919876543210", "919876543211"], "message": "Hello!"}'

POST /api/message/send-location Send location

Send a location to a phone number.

Phone Number

Latitude

Longitude

cURL

curl -X POST "http://localhost:3000/api/message/send-location" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -H "X-Session-ID: 1" \
  -d '{"to": "919876543210", "latitude": 40.7128, "longitude": -74.0060}'

Python

import requests

response = requests.post(
    "http://localhost:3000/api/message/send-location",
    headers={"X-API-Key": "your-api-key", "X-Session-ID": "1", "Content-Type": "application/json"},
    json={"to": "919876543210", "latitude": 40.7128, "longitude": -74.0060}
)
print(response.json())

JavaScript

const response = await fetch("http://localhost:3000/api/message/send-location", {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        "X-API-Key": "your-api-key",
        "X-Session-ID": "1"
    },
    body: JSON.stringify({
        to: "919876543210",
        latitude: 40.7128,
        longitude: -74.0060
    })
});
console.log(await response.json());

Ruby

require 'net/http'
require 'json'

uri = URI("http://localhost:3000/api/message/send-location")
http = Net::HTTP.new(uri.host, uri.port)
request = Net::HTTP::Post.new(uri)
request["Content-Type"] = "application/json"
request["X-API-Key"] = "your-api-key"
request["X-Session-ID"] = "1"
request.body = {to: "919876543210", latitude: 40.7128, longitude: -74.0060}.to_json
response = http.request(request)
puts JSON.parse(response.body)

POST /api/message/send-contact Send contact card

Send a contact card to a phone number.

Contact ID

cURL

curl -X POST "http://localhost:3000/api/message/send-contact" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -H "X-Session-ID: 1" \
  -d '{"to": "919876543210", "contactId": "919876543211"}'

Python

import requests

response = requests.post(
    "http://localhost:3000/api/message/send-contact",
    headers={"X-API-Key": "your-api-key", "X-Session-ID": "1", "Content-Type": "application/json"},
    json={"to": "919876543210", "contactId": "919876543211"}
)
print(response.json())

JavaScript

const response = await fetch("http://localhost:3000/api/message/send-contact", {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        "X-API-Key": "your-api-key",
        "X-Session-ID": "1"
    },
    body: JSON.stringify({
        to: "919876543210",
        contactId: "919876543211"
    })
});
console.log(await response.json());

Ruby

require 'net/http'
require 'json'

uri = URI("http://localhost:3000/api/message/send-contact")
http = Net::HTTP.new(uri.host, uri.port)
request = Net::HTTP::Post.new(uri)
request["Content-Type"] = "application/json"
request["X-API-Key"] = "your-api-key"
request["X-Session-ID"] = "1"
request.body = {to: "919876543210", contactId: "919876543211"}.to_json
response = http.request(request)
puts JSON.parse(response.body)

Chats & Contacts

GET /api/message/chats Get all chats

Retrieve all chats from the connected WhatsApp account.

cURL

curl -X GET "http://localhost:3000/api/message/chats" \
  -H "X-API-Key: your-api-key" \
  -H "X-Session-ID: 1"

Python

import requests

response = requests.get(
    "http://localhost:3000/api/message/chats",
    headers={"X-API-Key": "your-api-key", "X-Session-ID": "1"}
)
print(response.json())

JavaScript

const response = await fetch("http://localhost:3000/api/message/chats", {
    headers: {
        "X-API-Key": "your-api-key",
        "X-Session-ID": "1"
    }
});
const data = await response.json();
console.log(data);

Ruby

require 'net/http'
require 'json'

uri = URI("http://localhost:3000/api/message/chats")
http = Net::HTTP.new(uri.host, uri.port)
request = Net::HTTP::Get.new(uri)
request["X-API-Key"] = "your-api-key"
request["X-Session-ID"] = "1"
response = http.request(request)
puts JSON.parse(response.body)

Media

GET /m/:messageId Download media from received message

Fetch media (images, videos, documents) from received WhatsApp messages. The messageId is provided in the webhook payload when you receive a media message.

🔒

Zero Storage

Media is fetched directly from WhatsApp on-demand. Nothing is stored on the server. The image remains accessible as long as it exists on WhatsApp.

📋

Parameters

messageId	Required. The message ID from the webhook (e.g., `true_919876543210@c.us_3EB0ABC123`)
X-API-Key	Required. Your API key (header or `?apiKey=` query param)
X-Session-ID	Optional. Session number if you have multiple sessions (e.g., `1`, `2`)

🔄

Multi-Session Support

If you have multiple WhatsApp sessions, the API automatically searches all your connected sessions to find the message. You can optionally specify X-Session-ID to target a specific session.

cURL

# Download image using message ID from webhook
curl -H "X-API-Key: your-api-key" \
  "http://localhost:3000/m/true_919876543210%40c.us_3EB0ABC123" \
  --output image.jpg

# With specific session (for multi-session users)
curl -H "X-API-Key: your-api-key" \
  -H "X-Session-ID: 1" \
  "http://localhost:3000/m/true_919876543210%40c.us_3EB0ABC123" \
  --output image.jpg

# Using query parameter instead of header
curl "http://localhost:3000/m/true_919876543210%40c.us_3EB0ABC123?apiKey=your-api-key" \
  --output image.jpg

Python

import requests
from urllib.parse import quote

# Message ID from webhook
message_id = "true_919876543210@c.us_3EB0ABC123"

# Download media
response = requests.get(
    f"http://localhost:3000/m/{quote(message_id, safe='')}",
    headers={"X-API-Key": "your-api-key"}
)

if response.status_code == 200:
    # Save the image
    with open("image.jpg", "wb") as f:
        f.write(response.content)
    print(f"Downloaded {len(response.content)} bytes")
else:
    print(f"Error: {response.json()}")

# Get as base64 (for storage/processing)
import base64
base64_data = base64.b64encode(response.content).decode('utf-8')
print(f"Base64 length: {len(base64_data)}")

JavaScript

// Message ID from webhook
const messageId = "true_919876543210@c.us_3EB0ABC123";

// Fetch media
const response = await fetch(
    `http://localhost:3000/m/${encodeURIComponent(messageId)}`,
    { headers: { "X-API-Key": "your-api-key" } }
);

if (response.ok) {
    // Get as blob (for download/display)
    const blob = await response.blob();
    console.log(`Downloaded ${blob.size} bytes`);

    // Display in browser
    const img = document.createElement('img');
    img.src = URL.createObjectURL(blob);
    document.body.appendChild(img);

    // Or convert to base64 for storage
    const buffer = await blob.arrayBuffer();
    const base64 = btoa(String.fromCharCode(...new Uint8Array(buffer)));
    console.log(`Base64 length: ${base64.length}`);
} else {
    console.error(await response.json());
}

n8n Workflow

// In n8n, use HTTP Request node after receiving webhook:

// 1. Webhook node receives message with mediaUrl
// 2. HTTP Request node to download:
{
  "method": "GET",
  "url": "={{ $json.data.mediaUrl }}",
  "headers": {
    "X-API-Key": "your-api-key"
  },
  "responseFormat": "file"
}

// The response will be binary data you can:
// - Save to disk (Write Binary File node)
// - Upload to cloud storage (S3, Google Drive, etc.)
// - Process with other nodes

// To get base64 in Code node:
const imageBuffer = await this.helpers.getBinaryDataBuffer(0, 'data');
const base64 = imageBuffer.toString('base64');
return { base64, mimetype: $binary.data.mimeType };

📤

Response

Returns the raw binary image/media file with appropriate Content-Type header. On error, returns JSON with error and message fields.

⚠️

Media Availability

Media is available as long as: (1) The message exists on WhatsApp, (2) Your session is connected. If the message is deleted from WhatsApp, the media cannot be retrieved.

💾

Permanent Storage - Base64 Decoding

If you need to store images permanently, download the image and save the bytes. Here's how to decode and save in different languages:

Python

# Download and save
import requests
r = requests.get(media_url, headers={"X-API-Key": key})
with open("image.jpg", "wb") as f:
    f.write(r.content)

# Or get as base64
import base64
b64 = base64.b64encode(r.content).decode()

Node.js

const fs = require('fs');

// Download and save
const response = await fetch(mediaUrl, {
  headers: { 'X-API-Key': key }
});
const buffer = Buffer.from(await response.arrayBuffer());
fs.writeFileSync('image.jpg', buffer);

// Get as base64
const base64 = buffer.toString('base64');

Browser JavaScript

// Display image directly
const img = document.createElement('img');
img.src = mediaUrl + '?apiKey=' + key;
document.body.appendChild(img);

// Or download as file
const a = document.createElement('a');
a.href = mediaUrl + '?apiKey=' + key;
a.download = 'image.jpg';
a.click();

POST /api/media/send Send media file

Upload and send a media file (image, video, document).

💡

File Upload

Use multipart/form-data with a file field named media.

cURL

curl -X POST "http://localhost:3000/api/media/send" \
  -H "X-API-Key: your-api-key" \
  -H "X-Session-ID: 1" \
  -F "to=919876543210" \
  -F "media=@/path/to/file.jpg" \
  -F "caption=Optional caption"

Python

import requests

files = {'media': open('/path/to/file.jpg', 'rb')}
data = {
    'to': '919876543210',
    'caption': 'Optional caption'
}
response = requests.post(
    "http://localhost:3000/api/media/send",
    headers={"X-API-Key": "your-api-key", "X-Session-ID": "1"},
    files=files,
    data=data
)
print(response.json())

JavaScript

const formData = new FormData();
formData.append('to', '919876543210');
formData.append('media', fileInput.files[0]);
formData.append('caption', 'Optional caption');

const response = await fetch("http://localhost:3000/api/media/send", {
    method: "POST",
    headers: {
        "X-API-Key": "your-api-key",
        "X-Session-ID": "1"
    },
    body: formData
});
console.log(await response.json());

POST /api/media/send-url Send media from URL

Send media by providing a URL.

Phone Number

Media URL

Caption (optional)

cURL

curl -X POST "http://localhost:3000/api/media/send-url" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -H "X-Session-ID: 1" \
  -d '{"to": "919876543210", "url": "https://example.com/image.jpg", "caption": "Check this out!"}'

Python

import requests

response = requests.post(
    "http://localhost:3000/api/media/send-url",
    headers={"X-API-Key": "your-api-key", "X-Session-ID": "1", "Content-Type": "application/json"},
    json={"to": "919876543210", "url": "https://example.com/image.jpg", "caption": "Check this out!"}
)
print(response.json())

JavaScript

const response = await fetch("http://localhost:3000/api/media/send-url", {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        "X-API-Key": "your-api-key",
        "X-Session-ID": "1"
    },
    body: JSON.stringify({
        to: "919876543210",
        url: "https://example.com/image.jpg",
        caption: "Check this out!"
    })
});
console.log(await response.json());

Ruby

require 'net/http'
require 'json'

uri = URI("http://localhost:3000/api/media/send-url")
http = Net::HTTP.new(uri.host, uri.port)
request = Net::HTTP::Post.new(uri)
request["Content-Type"] = "application/json"
request["X-API-Key"] = "your-api-key"
request["X-Session-ID"] = "1"
request.body = {to: "919876543210", url: "https://example.com/image.jpg", caption: "Check this out!"}.to_json
response = http.request(request)
puts JSON.parse(response.body)

POST /api/media/send-base64 Send media from base64

Send media using base64 encoded data.

Parameter	Type	Description
`to`	string	Phone number Required
`base64`	string	Base64 encoded media data Required
`mimetype`	string	MIME type (e.g., image/jpeg) Required
`filename`	string	Filename Optional
`caption`	string	Caption Optional

cURL

curl -X POST "http://localhost:3000/api/media/send-base64" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -H "X-Session-ID: 1" \
  -d '{"to": "919876543210", "base64": "BASE64_DATA", "mimetype": "image/jpeg", "filename": "image.jpg", "caption": "My image"}'

Python

import requests
import base64

with open('image.jpg', 'rb') as f:
    base64_data = base64.b64encode(f.read()).decode()

response = requests.post(
    "http://localhost:3000/api/media/send-base64",
    headers={"X-API-Key": "your-api-key", "X-Session-ID": "1", "Content-Type": "application/json"},
    json={
        "to": "919876543210",
        "base64": base64_data,
        "mimetype": "image/jpeg",
        "filename": "image.jpg",
        "caption": "My image"
    }
)
print(response.json())

JavaScript

const fs = require('fs');
const base64Data = fs.readFileSync('image.jpg').toString('base64');

const response = await fetch("http://localhost:3000/api/media/send-base64", {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        "X-API-Key": "your-api-key",
        "X-Session-ID": "1"
    },
    body: JSON.stringify({
        to: "919876543210",
        base64: base64Data,
        mimetype: "image/jpeg",
        filename: "image.jpg",
        caption: "My image"
    })
});
console.log(await response.json());

Ruby

require 'net/http'
require 'json'
require 'base64'

base64_data = Base64.encode64(File.read('image.jpg'))

uri = URI("http://localhost:3000/api/media/send-base64")
http = Net::HTTP.new(uri.host, uri.port)
request = Net::HTTP::Post.new(uri)
request["Content-Type"] = "application/json"
request["X-API-Key"] = "your-api-key"
request["X-Session-ID"] = "1"
request.body = {
    to: "919876543210",
    base64: base64_data,
    mimetype: "image/jpeg",
    filename: "image.jpg",
    caption: "My image"
}.to_json
response = http.request(request)
puts JSON.parse(response.body)

POST /api/media/send-image Send image file

Upload and send an image file.

cURL

curl -X POST "http://localhost:3000/api/media/send-image" \
  -H "X-API-Key: your-api-key" \
  -H "X-Session-ID: 1" \
  -F "to=919876543210" \
  -F "image=@/path/to/image.jpg" \
  -F "caption=My image"

Python

import requests

files = {'image': open('/path/to/image.jpg', 'rb')}
data = {'to': '919876543210', 'caption': 'My image'}
response = requests.post(
    "http://localhost:3000/api/media/send-image",
    headers={"X-API-Key": "your-api-key", "X-Session-ID": "1"},
    files=files,
    data=data
)
print(response.json())

JavaScript

const formData = new FormData();
formData.append('to', '919876543210');
formData.append('image', fileInput.files[0]);
formData.append('caption', 'My image');

const response = await fetch("http://localhost:3000/api/media/send-image", {
    method: "POST",
    headers: {
        "X-API-Key": "your-api-key",
        "X-Session-ID": "1"
    },
    body: formData
});
console.log(await response.json());

POST /api/media/send-document Send document file

Upload and send a document file (PDF, DOC, etc.).

cURL

curl -X POST "http://localhost:3000/api/media/send-document" \
  -H "X-API-Key: your-api-key" \
  -H "X-Session-ID: 1" \
  -F "to=919876543210" \
  -F "document=@/path/to/file.pdf"

Python

import requests

files = {'document': open('/path/to/file.pdf', 'rb')}
data = {'to': '919876543210'}
response = requests.post(
    "http://localhost:3000/api/media/send-document",
    headers={"X-API-Key": "your-api-key", "X-Session-ID": "1"},
    files=files,
    data=data
)
print(response.json())

JavaScript

const formData = new FormData();
formData.append('to', '919876543210');
formData.append('document', fileInput.files[0]);

const response = await fetch("http://localhost:3000/api/media/send-document", {
    method: "POST",
    headers: {
        "X-API-Key": "your-api-key",
        "X-Session-ID": "1"
    },
    body: formData
});
console.log(await response.json());

POST /api/media/send-audio Send audio/voice message

Send an audio file or voice message.

💡

Voice Messages

Set ptt: true to send as a voice message. Audio will be automatically converted to OGG/Opus format.

cURL

curl -X POST "http://localhost:3000/api/media/send-audio" \
  -H "X-API-Key: your-api-key" \
  -H "X-Session-ID: 1" \
  -F "to=919876543210" \
  -F "audio=@/path/to/audio.mp3" \
  -F "ptt=true"

Python

import requests

files = {'audio': open('/path/to/audio.mp3', 'rb')}
data = {'to': '919876543210', 'ptt': 'true'}
response = requests.post(
    "http://localhost:3000/api/media/send-audio",
    headers={"X-API-Key": "your-api-key", "X-Session-ID": "1"},
    files=files,
    data=data
)
print(response.json())

JavaScript

const formData = new FormData();
formData.append('to', '919876543210');
formData.append('audio', fileInput.files[0]);
formData.append('ptt', 'true');

const response = await fetch("http://localhost:3000/api/media/send-audio", {
    method: "POST",
    headers: {
        "X-API-Key": "your-api-key",
        "X-Session-ID": "1"
    },
    body: formData
});
console.log(await response.json());

POST /api/media/send-video Send video file

Upload and send a video file.

cURL

curl -X POST "http://localhost:3000/api/media/send-video" \
  -H "X-API-Key: your-api-key" \
  -H "X-Session-ID: 1" \
  -F "to=919876543210" \
  -F "video=@/path/to/video.mp4" \
  -F "caption=My video"

Python

import requests

files = {'video': open('/path/to/video.mp4', 'rb')}
data = {'to': '919876543210', 'caption': 'My video'}
response = requests.post(
    "http://localhost:3000/api/media/send-video",
    headers={"X-API-Key": "your-api-key", "X-Session-ID": "1"},
    files=files,
    data=data
)
print(response.json())

JavaScript

const formData = new FormData();
formData.append('to', '919876543210');
formData.append('video', fileInput.files[0]);
formData.append('caption', 'My video');

const response = await fetch("http://localhost:3000/api/media/send-video", {
    method: "POST",
    headers: {
        "X-API-Key": "your-api-key",
        "X-Session-ID": "1"
    },
    body: formData
});
console.log(await response.json());

POST /api/media/send-sticker Send sticker

Send a sticker (images will be converted to WebP format).

cURL

curl -X POST "http://localhost:3000/api/media/send-sticker" \
  -H "X-API-Key: your-api-key" \
  -H "X-Session-ID: 1" \
  -F "to=919876543210" \
  -F "sticker=@/path/to/image.png"

Python

import requests

files = {'sticker': open('/path/to/image.png', 'rb')}
data = {'to': '919876543210'}
response = requests.post(
    "http://localhost:3000/api/media/send-sticker",
    headers={"X-API-Key": "your-api-key", "X-Session-ID": "1"},
    files=files,
    data=data
)
print(response.json())

JavaScript

const formData = new FormData();
formData.append('to', '919876543210');
formData.append('sticker', fileInput.files[0]);

const response = await fetch("http://localhost:3000/api/media/send-sticker", {
    method: "POST",
    headers: {
        "X-API-Key": "your-api-key",
        "X-Session-ID": "1"
    },
    body: formData
});
console.log(await response.json());

GET /api/message/chats/:chatId/messages Get messages from a chat

Retrieve messages from a specific chat by chat ID.

Chat ID

Limit

cURL

curl -X GET "http://localhost:3000/api/message/chats/919876543210@c.us/messages?limit=50" \
  -H "X-API-Key: your-api-key" \
  -H "X-Session-ID: 1"

Python

import requests

chat_id = "919876543210@c.us"
response = requests.get(
    f"http://localhost:3000/api/message/chats/{chat_id}/messages?limit=50",
    headers={"X-API-Key": "your-api-key", "X-Session-ID": "1"}
)
print(response.json())

JavaScript

const chatId = "919876543210@c.us";
const response = await fetch(`http://localhost:3000/api/message/chats/${chatId}/messages?limit=50`, {
    headers: {
        "X-API-Key": "your-api-key",
        "X-Session-ID": "1"
    }
});
const data = await response.json();
console.log(data);

Ruby

require 'net/http'
require 'json'

chat_id = "919876543210@c.us"
uri = URI("http://localhost:3000/api/message/chats/#{chat_id}/messages?limit=50")
http = Net::HTTP.new(uri.host, uri.port)
request = Net::HTTP::Get.new(uri)
request["X-API-Key"] = "your-api-key"
request["X-Session-ID"] = "1"
response = http.request(request)
puts JSON.parse(response.body)

GET /api/message/by-number/:number Get messages by phone number

Get messages from a conversation using phone number.

Phone Number

Limit

cURL

curl -X GET "http://localhost:3000/api/message/by-number/919876543210?limit=50" \
  -H "X-API-Key: your-api-key" \
  -H "X-Session-ID: 1"

Python

import requests

number = "919876543210"
response = requests.get(
    f"http://localhost:3000/api/message/by-number/{number}?limit=50",
    headers={"X-API-Key": "your-api-key", "X-Session-ID": "1"}
)
print(response.json())

JavaScript

const number = "919876543210";
const response = await fetch(`http://localhost:3000/api/message/by-number/${number}?limit=50`, {
    headers: {
        "X-API-Key": "your-api-key",
        "X-Session-ID": "1"
    }
});
const data = await response.json();
console.log(data);

Ruby

require 'net/http'
require 'json'

number = "919876543210"
uri = URI("http://localhost:3000/api/message/by-number/#{number}?limit=50")
http = Net::HTTP.new(uri.host, uri.port)
request = Net::HTTP::Get.new(uri)
request["X-API-Key"] = "your-api-key"
request["X-Session-ID"] = "1"
response = http.request(request)
puts JSON.parse(response.body)

GET /api/message/contacts Get all contacts

Retrieve all contacts from the WhatsApp account.

cURL

curl -X GET "http://localhost:3000/api/message/contacts" \
  -H "X-API-Key: your-api-key" \
  -H "X-Session-ID: 1"

Python

import requests

response = requests.get(
    "http://localhost:3000/api/message/contacts",
    headers={"X-API-Key": "your-api-key", "X-Session-ID": "1"}
)
contacts = response.json()["contacts"]
print(f"Found {len(contacts)} contacts")

JavaScript

const response = await fetch("http://localhost:3000/api/message/contacts", {
    headers: {
        "X-API-Key": "your-api-key",
        "X-Session-ID": "1"
    }
});
const data = await response.json();
console.log(`Found ${data.contacts.length} contacts`);

Ruby

require 'net/http'
require 'json'

uri = URI("http://localhost:3000/api/message/contacts")
http = Net::HTTP.new(uri.host, uri.port)
request = Net::HTTP::Get.new(uri)
request["X-API-Key"] = "your-api-key"
request["X-Session-ID"] = "1"
response = http.request(request)
data = JSON.parse(response.body)
puts "Found #{data['contacts'].length} contacts"

GET /api/message/check/:number Check if number is on WhatsApp

Check if a phone number is registered on WhatsApp.

Phone Number

Python

import requests

number = "919876543210"
response = requests.get(
    f"http://localhost:3000/api/message/check/{number}",
    headers={"X-API-Key": "your-api-key", "X-Session-ID": "1"}
)
result = response.json()
print(f"Registered: {result['isRegistered']}")

GET /api/message/profile-pic/:number Get profile picture URL

Get the profile picture URL for a phone number.

Phone Number

Python

import requests

number = "919876543210"
response = requests.get(
    f"http://localhost:3000/api/message/profile-pic/{number}",
    headers={"X-API-Key": "your-api-key", "X-Session-ID": "1"}
)
result = response.json()
print(f"Profile Pic: {result.get('profilePicUrl', 'Not available')}")

Calls

POST /api/calls/reject Reject incoming call

Reject an incoming WhatsApp call.

Parameter	Type	Description
`callId`	string	Call ID from incoming_call event Required

Call ID

Python

import requests

response = requests.post(
    "http://localhost:3000/api/calls/reject",
    headers={"X-API-Key": "your-api-key", "X-Session-ID": "1", "Content-Type": "application/json"},
    json={"callId": "call-id-from-event"}
)
print(response.json())

GET /api/calls/logs Get all call logs

Retrieve all call logs from all chats.

Limit (optional)

Python

import requests

response = requests.get(
    "http://localhost:3000/api/calls/logs?limit=100",
    headers={"X-API-Key": "your-api-key", "X-Session-ID": "1"}
)
print(response.json())

GET /api/calls/logs/:number Get call logs by number

Get call logs for a specific phone number.

Phone Number

Limit

Python

import requests

number = "919876543210"
response = requests.get(
    f"http://localhost:3000/api/calls/logs/{number}?limit=50",
    headers={"X-API-Key": "your-api-key", "X-Session-ID": "1"}
)
print(response.json())

Webhooks

GET /api/status/webhook Get webhook configuration

Get the current webhook URL configuration.

cURL

curl -X GET "http://localhost:3000/api/status/webhook" \
  -H "X-API-Key: your-api-key" \
  -H "X-Session-ID: 1"

Python

import requests

response = requests.get(
    "http://localhost:3000/api/status/webhook",
    headers={"X-API-Key": "your-api-key", "X-Session-ID": "1"}
)
print(response.json())

JavaScript

const response = await fetch("http://localhost:3000/api/status/webhook", {
    headers: {
        "X-API-Key": "your-api-key",
        "X-Session-ID": "1"
    }
});
const data = await response.json();
console.log(data);

Ruby

require 'net/http'
require 'json'

uri = URI("http://localhost:3000/api/status/webhook")
http = Net::HTTP.new(uri.host, uri.port)
request = Net::HTTP::Get.new(uri)
request["X-API-Key"] = "your-api-key"
request["X-Session-ID"] = "1"
response = http.request(request)
puts JSON.parse(response.body)

POST /api/status/webhook Set webhook URL

Configure a webhook URL to receive real-time message notifications.

Webhook URL

cURL

curl -X POST "http://localhost:3000/api/status/webhook" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -H "X-Session-ID: 1" \
  -d '{"url": "https://your-server.com/webhook"}'

Python

import requests

response = requests.post(
    "http://localhost:3000/api/status/webhook",
    headers={"X-API-Key": "your-api-key", "X-Session-ID": "1", "Content-Type": "application/json"},
    json={"url": "https://your-server.com/webhook"}
)
print(response.json())

JavaScript

const response = await fetch("http://localhost:3000/api/status/webhook", {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        "X-API-Key": "your-api-key",
        "X-Session-ID": "1"
    },
    body: JSON.stringify({
        url: "https://your-server.com/webhook"
    })
});
console.log(await response.json());

Ruby

require 'net/http'
require 'json'

uri = URI("http://localhost:3000/api/status/webhook")
http = Net::HTTP.new(uri.host, uri.port)
request = Net::HTTP::Post.new(uri)
request["Content-Type"] = "application/json"
request["X-API-Key"] = "your-api-key"
request["X-Session-ID"] = "1"
request.body = {url: "https://your-server.com/webhook"}.to_json
response = http.request(request)
puts JSON.parse(response.body)

When a message is received, your webhook will receive this payload:

Webhook Payload

{
  "event": "message",
  "sessionId": "admin-key-session-1",
  "timestamp": 1704067200000,
  "data": {
    "id": "true_919876543210@c.us_XXXXX",
    "from": "919876543210@c.us",
    "fromNumber": "919876543210",
    "to": "917654321098@c.us",
    "toNumber": "917654321098",
    "body": "Hello!",
    "type": "chat",
    "timestamp": 1704067200,
    "contactName": "John Doe",
    "isGroup": false,
    "hasMedia": false
  }
}

💡

Media Messages

When hasMedia is true, the webhook includes a mediaUrl field with a direct link to download the media. Use GET /m/:messageId with your API key to fetch the image. See Download Media endpoint.

📷

Media Webhook Example

{
  "event": "message",
  "data": {
    "id": "true_919876543210@c.us_3EB0ABC123",
    "hasMedia": true,
    "mediaUrl": "http://localhost:3000/m/true_919876543210%40c.us_3EB0ABC123",
    "mediaType": "image",
    "media": {
      "messageId": "true_919876543210@c.us_3EB0ABC123",
      "url": "http://localhost:3000/m/true_919876543210%40c.us_3EB0ABC123",
      "mimetype": "image/jpeg"
    }
  }
}

DELETE /api/status/webhook Delete/disable webhook

Disable the webhook by deleting it.

cURL

curl -X DELETE "http://localhost:3000/api/status/webhook" \
  -H "X-API-Key: your-api-key" \
  -H "X-Session-ID: 1"

Python

import requests

response = requests.delete(
    "http://localhost:3000/api/status/webhook",
    headers={"X-API-Key": "your-api-key", "X-Session-ID": "1"}
)
print(response.json())

JavaScript

const response = await fetch("http://localhost:3000/api/status/webhook", {
    method: "DELETE",
    headers: {
        "X-API-Key": "your-api-key",
        "X-Session-ID": "1"
    }
});
console.log(await response.json());

Ruby

require 'net/http'
require 'json'

uri = URI("http://localhost:3000/api/status/webhook")
http = Net::HTTP.new(uri.host, uri.port)
request = Net::HTTP::Delete.new(uri)
request["X-API-Key"] = "your-api-key"
request["X-Session-ID"] = "1"
response = http.request(request)
puts JSON.parse(response.body)

POST /api/status/webhook/test Test webhook

Send a test payload to your configured webhook URL.

cURL

curl -X POST "http://localhost:3000/api/status/webhook/test" \
  -H "X-API-Key: your-api-key" \
  -H "X-Session-ID: 1"

Python

import requests

response = requests.post(
    "http://localhost:3000/api/status/webhook/test",
    headers={"X-API-Key": "your-api-key", "X-Session-ID": "1"}
)
print(response.json())

JavaScript

const response = await fetch("http://localhost:3000/api/status/webhook/test", {
    method: "POST",
    headers: {
        "X-API-Key": "your-api-key",
        "X-Session-ID": "1"
    }
});
console.log(await response.json());

Ruby

require 'net/http'
require 'json'

uri = URI("http://localhost:3000/api/status/webhook/test")
http = Net::HTTP.new(uri.host, uri.port)
request = Net::HTTP::Post.new(uri)
request["X-API-Key"] = "your-api-key"
request["X-Session-ID"] = "1"
response = http.request(request)
puts JSON.parse(response.body)

POST /api/status/logout Logout from WhatsApp

Logout from the current WhatsApp session.

Python

import requests

response = requests.post(
    "http://localhost:3000/api/status/logout",
    headers={"X-API-Key": "your-api-key", "X-Session-ID": "1"}
)
print(response.json())

POST /api/status/restart Restart WhatsApp client

Restart the WhatsApp client connection.

Python

import requests

response = requests.post(
    "http://localhost:3000/api/status/restart",
    headers={"X-API-Key": "your-api-key", "X-Session-ID": "1"}
)
print(response.json())

📚

Need More Help?

Check out the Dashboard for a visual interface, or explore all endpoints in the sidebar. Each endpoint supports the "Try It" feature for live testing!