WAMessenger API Documentation
Welcome to the WAMessenger API! Use our REST API to integrate WhatsApp messaging into your applications. Send messages, manage multiple WhatsApp sessions, and automate your communication workflows.
Simple REST API with JSON responses. Get started in minutes.
Manage multiple WhatsApp sessions from a single account.
Track message delivery, read receipts, and failed messages.
JWT authentication, rate limiting, and encrypted connections.
Base URL
Full API access is available on Business and Enterprise plans. Check the Plans & Features section for details.
๐ Authentication
WAMessenger uses JWT (JSON Web Tokens) for authentication. Include your token in the Authorization header of all API requests.
Getting Your API Token
- Register for an account at wamessenger.alintro.com/register
- Log in via the API or dashboard to receive your JWT token
- Include the token in all authenticated requests
Request Header
curl -X GET "https://wamessenger.alintro.com/api/sessions" \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "Content-Type: application/json"
const response = await fetch('https://wamessenger.alintro.com/api/sessions', {
method: 'GET',
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json'
}
});
const data = await response.json();
import requests
headers = {
'Authorization': f'Bearer {token}',
'Content-Type': 'application/json'
}
response = requests.get(
'https://wamessenger.alintro.com/api/sessions',
headers=headers
)
data = response.json()
Never expose your JWT token in client-side code or public repositories. Store it securely as an environment variable.
โ ๏ธ Rate Limits
To ensure fair usage and service stability, API requests are rate-limited based on your plan.
| Endpoint Type | Limit | Window |
|---|---|---|
| General API | 100 requests | 15 minutes |
| Authentication | 5 requests | 15 minutes |
| Message Sending | Varies by plan | Per day |
Rate Limit Headers
Rate limit information is included in response headers:
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1699876543
When rate limited, you'll receive a 429 Too Many Requests response. Wait for the reset time before retrying.
??? Error Handling
The API uses conventional HTTP response codes to indicate success or failure. Error responses include a JSON body with details.
Error Response Format
{
"error": "Session not found",
"message": "The requested session does not exist or has been deleted",
"code": "SESSION_NOT_FOUND"
}
HTTP Status Codes
Request succeeded
Resource created successfully
Invalid request parameters
Missing or invalid authentication token
Feature not available on your plan
Resource not found
Rate limit exceeded
Something went wrong on our end
POST Register Account
Create a new WAMessenger account.
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
| string | Required | Valid email address | |
| password | string | Required | Minimum 8 characters |
| username | string | Optional | Display name (defaults to email prefix) |
curl -X POST "https://wamessenger.alintro.com/api/register" \
-H "Content-Type: application/json" \
-d '{
"email": "user@example.com",
"password": "securepassword123",
"username": "johndoe"
}'
const response = await fetch('https://wamessenger.alintro.com/api/register', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify({
email: 'user@example.com',
password: 'securepassword123',
username: 'johndoe'
})
});
const data = await response.json();
console.log(data.token); // Save this token!
import requests
response = requests.post(
'https://wamessenger.alintro.com/api/register',
json={
'email': 'user@example.com',
'password': 'securepassword123',
'username': 'johndoe'
}
)
data = response.json()
token = data['token'] # Save this token!
{
"message": "User registered successfully",
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"user": {
"userId": "550e8400-e29b-41d4-a716-446655440000",
"email": "user@example.com",
"username": "johndoe"
}
}
POST Login
Authenticate and receive a JWT token.
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
| string | Required | Your registered email | |
| password | string | Required | Your password |
curl -X POST "https://wamessenger.alintro.com/api/login" \
-H "Content-Type: application/json" \
-d '{
"email": "user@example.com",
"password": "securepassword123"
}'
const response = await fetch('https://wamessenger.alintro.com/api/login', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify({
email: 'user@example.com',
password: 'securepassword123'
})
});
const { token } = await response.json();
// Store token for subsequent requests
import requests
response = requests.post(
'https://wamessenger.alintro.com/api/login',
json={
'email': 'user@example.com',
'password': 'securepassword123'
}
)
token = response.json()['token']
# Store token for subsequent requests
{
"message": "Login successful",
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"user": {
"userId": "550e8400-e29b-41d4-a716-446655440000",
"email": "user@example.com",
"username": "johndoe"
}
}
๐งช Try It
POST Create Session
Create a new WhatsApp session. After creation, you'll need to scan the QR code to authenticate.
This endpoint requires a valid JWT token in the Authorization header.
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
| name | string | Optional | Display name for the session |
| description | string | Optional | Description of what this session is used for |
curl -X POST "https://wamessenger.alintro.com/api/sessions" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Support Bot",
"description": "Customer support automation"
}'
const response = await fetch('https://wamessenger.alintro.com/api/sessions', {
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
name: 'Support Bot',
description: 'Customer support automation'
})
});
const { sessionId, status } = await response.json();
// Now get the QR code to scan
import requests
response = requests.post(
'https://wamessenger.alintro.com/api/sessions',
headers={'Authorization': f'Bearer {token}'},
json={
'name': 'Support Bot',
'description': 'Customer support automation'
}
)
data = response.json()
session_id = data['sessionId']
# Now get the QR code to scan
{
"success": true,
"sessionId": "550e8400-e29b-41d4-a716-446655440000",
"name": "Support Bot",
"status": "connecting",
"message": "Session created. Generating QR code..."
}
GET List Sessions
Retrieve all WhatsApp sessions for your account.
curl -X GET "https://wamessenger.alintro.com/api/sessions" \
-H "Authorization: Bearer YOUR_TOKEN"
const response = await fetch('https://wamessenger.alintro.com/api/sessions', {
headers: {
'Authorization': `Bearer ${token}`
}
});
const { sessions, total } = await response.json();
import requests
response = requests.get(
'https://wamessenger.alintro.com/api/sessions',
headers={'Authorization': f'Bearer {token}'}
)
data = response.json()
sessions = data['sessions']
{
"sessions": [
{
"sessionId": "550e8400-e29b-41d4-a716-446655440000",
"name": "Support Bot",
"description": "Customer support automation",
"phone": "919876543210",
"status": "connected",
"hasQR": false,
"messagesSent": 1234,
"messagesReceived": 567,
"createdAt": "2024-01-15T10:30:00.000Z"
}
],
"total": 1
}
GET Get Session Details
Get detailed information about a specific session.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| sessionId | string | UUID of the session |
POST Connect Session
Reconnect a disconnected session. This generates a new QR code if needed.
{
"success": true,
"sessionId": "550e8400-e29b-41d4-a716-446655440000",
"status": "connecting",
"message": "Connecting session. QR code will be generated..."
}
GET Get QR Code
Retrieve the QR code for session authentication. Scan this with WhatsApp to link the session.
curl -X GET "https://wamessenger.alintro.com/api/sessions/{sessionId}/qr" \
-H "Authorization: Bearer YOUR_TOKEN"
const response = await fetch(
`https://wamessenger.alintro.com/api/sessions/${sessionId}/qr`,
{
headers: { 'Authorization': `Bearer ${token}` }
}
);
const { qrCode, status } = await response.json();
// qrCode is a base64 data URL - display it as an image
import requests
import base64
response = requests.get(
f'https://wamessenger.alintro.com/api/sessions/{session_id}/qr',
headers={'Authorization': f'Bearer {token}'}
)
data = response.json()
qr_code = data.get('qrCode')
# qr_code is a base64 data URL - display it as an image
{
"qrCode": "data:image/png;base64,iVBORw0KGgo...",
"status": "pending",
"expiresAt": "2024-01-15T10:31:00.000Z"
}
QR codes expire after approximately 60 seconds. Poll this endpoint to get a fresh QR code if the user hasn't scanned it in time.
GET Get Session Status
Check the current connection status of a session.
Session Status Values
| Status | Description |
|---|---|
connecting |
Session is initializing |
pending |
Waiting for QR code scan |
connected |
WhatsApp is authenticated and ready |
reconnecting |
Attempting to reconnect |
disconnected |
Session is offline |
error |
An error occurred |
POST Send Message
Send a WhatsApp message through a connected session. This is the core messaging endpoint.
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
| to | string | Required | Recipient phone number (with country code, e.g., 919876543210) |
| message | string | Required | Text message to send |
curl -X POST "https://wamessenger.alintro.com/api/sessions/{sessionId}/send" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"to": "919876543210",
"message": "Hello from WAMessenger API! ๐"
}'
async function sendMessage(sessionId, to, message) {
const response = await fetch(
`https://wamessenger.alintro.com/api/sessions/${sessionId}/send`,
{
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({ to, message })
}
);
return response.json();
}
// Usage
const result = await sendMessage(
'session-uuid',
'919876543210',
'Hello from WAMessenger API! ๐'
);
console.log(result.success ? 'Message sent!' : 'Failed');
import requests
def send_message(session_id, to, message):
response = requests.post(
f'https://wamessenger.alintro.com/api/sessions/{session_id}/send',
headers={'Authorization': f'Bearer {token}'},
json={'to': to, 'message': message}
)
return response.json()
# Usage
result = send_message(
'session-uuid',
'919876543210',
'Hello from WAMessenger API! ๐'
)
print('Sent!' if result['success'] else 'Failed')
{
"success": true,
"message": "Message sent successfully"
}
Always include the country code without the + sign. For example, use 919876543210 for an Indian number, not +919876543210 or 9876543210.
DELETE Delete Session
Delete a WhatsApp session. This disconnects the session and removes all associated data.
Deleting a session is permanent. You'll need to create a new session and scan the QR code again to reconnect.
curl -X DELETE "https://wamessenger.alintro.com/api/sessions/{sessionId}" \
-H "Authorization: Bearer YOUR_TOKEN"
const response = await fetch(
`https://wamessenger.alintro.com/api/sessions/${sessionId}`,
{
method: 'DELETE',
headers: { 'Authorization': `Bearer ${token}` }
}
);
const result = await response.json();
import requests
response = requests.delete(
f'https://wamessenger.alintro.com/api/sessions/{session_id}',
headers={'Authorization': f'Bearer {token}'}
)
result = response.json()
POST Initialize WhatsApp (Legacy)
Quick initialization endpoint for single-session use. Creates a default session automatically.
This is a backwards-compatible endpoint. For new integrations, use the Sessions API instead.
curl -X POST "https://wamessenger.alintro.com/api/whatsapp/init"
const response = await fetch('https://wamessenger.alintro.com/api/whatsapp/init', {
method: 'POST'
});
const data = await response.json();
// Now check /api/whatsapp/qr for QR code
POST Send Message (Legacy)
Send a message using the default session.
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
| number | string | Required | Recipient phone number with country code |
| message | string | Required | Text message to send |
curl -X POST "https://wamessenger.alintro.com/api/whatsapp/send" \
-H "Content-Type: application/json" \
-d '{
"number": "919876543210",
"message": "Hello from WAMessenger!"
}'
const response = await fetch('https://wamessenger.alintro.com/api/whatsapp/send', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
number: '919876543210',
message: 'Hello from WAMessenger!'
})
});
POST Bulk Send Messages
Send the same message to multiple recipients. Perfect for notifications and announcements.
Growth Plan RequiredRequest Body
| Parameter | Type | Required | Description |
|---|---|---|---|
| contacts | array | Required | Array of phone numbers or objects with number property |
| message | string | Required | Message to send to all contacts |
| delay | number | Optional | Delay between messages in ms (default: 2000) |
curl -X POST "https://wamessenger.alintro.com/api/whatsapp/bulk-send" \
-H "Content-Type: application/json" \
-d '{
"contacts": [
"919876543210",
"919876543211",
"919876543212"
],
"message": "๐ Special offer just for you!",
"delay": 3000
}'
const contacts = [
'919876543210',
'919876543211',
'919876543212'
];
const response = await fetch('https://wamessenger.alintro.com/api/whatsapp/bulk-send', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
contacts,
message: '๐ Special offer just for you!',
delay: 3000
})
});
const { total, sent, failed, results } = await response.json();
console.log(`Sent: ${sent}/${total}, Failed: ${failed}`);
import requests
contacts = [
'919876543210',
'919876543211',
'919876543212'
]
response = requests.post(
'https://wamessenger.alintro.com/api/whatsapp/bulk-send',
json={
'contacts': contacts,
'message': '๐ Special offer just for you!',
'delay': 3000
}
)
data = response.json()
print(f"Sent: {data['sent']}/{data['total']}, Failed: {data['failed']}")
{
"total": 3,
"sent": 2,
"failed": 1,
"results": [
{ "contact": "919876543210", "success": true, "status": "Sent" },
{ "contact": "919876543211", "success": true, "status": "Sent" },
{ "contact": "919876543212", "success": false, "status": "Failed", "error": "Number not on WhatsApp" }
]
}
Use the delay parameter to avoid WhatsApp rate limits. We recommend at least 2-3 seconds between messages.
GET Message Statistics
Get aggregated message statistics for analytics and reporting.
This endpoint requires a valid JWT token in the Authorization header.
{
"success": true,
"totals": {
"sent": 1234,
"delivered": 1100,
"read": 890,
"failed": 45,
"total": 1279
},
"chart": {
"labels": ["Mon, Jan 8", "Tue, Jan 9", "Wed, Jan 10", ...],
"sent": [45, 62, 38, 71, 55, 42, 50],
"delivered": [42, 58, 35, 68, 52, 40, 48],
"read": [35, 50, 30, 60, 45, 35, 42],
"failed": [3, 4, 3, 3, 3, 2, 2]
}
}
GET Failed Messages
Get a list of recently failed messages for debugging and retry purposes.
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
| limit | number | 5 | Number of failed messages to return |
{
"success": true,
"count": 3,
"messages": [
{
"id": "1705312200000",
"recipient": "919876543210",
"error": "Number not registered on WhatsApp",
"timestamp": "2024-01-15T10:30:00.000Z",
"message": "Hello, this is a test mess..."
}
]
}
๐ Webhooks
Receive real-time notifications when messages are sent, delivered, read, or when you receive incoming messages.
Starter Plan & AboveWebhook configuration will be available in the dashboard. Contact support for early access.
Real-time Events via Socket.IO
Currently, you can receive real-time events using Socket.IO. Connect to the WebSocket server and listen for these events:
| Event | Description | Payload |
|---|---|---|
| qr | QR code generated for scanning | { sessionId, qrCode } |
| connected | Session successfully connected | { sessionId, phone } |
| disconnected | Session disconnected | { sessionId, reason } |
| reconnecting | Attempting to reconnect | { sessionId } |
const io = require('socket.io-client');
const socket = io('https://wamessenger.alintro.com', {
transports: ['websocket']
});
socket.on('connect', () => {
console.log('Connected to WAMessenger');
});
socket.on('qr', (data) => {
console.log('QR Code received for session:', data.sessionId);
// Display data.qrCode (base64 image)
});
socket.on('connected', (data) => {
console.log(`Session ${data.sessionId} connected!`);
console.log(`Phone: ${data.phone}`);
});
socket.on('disconnected', (data) => {
console.log(`Session ${data.sessionId} disconnected:`, data.reason);
});
<script src="https://cdn.socket.io/4.7.2/socket.io.min.js"></script>
<script>
const socket = io('https://wamessenger.alintro.com');
socket.on('qr', (data) => {
// Display QR code image
document.getElementById('qr-image').src = data.qrCode;
});
socket.on('connected', (data) => {
alert('WhatsApp connected! Phone: ' + data.phone);
});
</script>
๐ Plans & Features
Choose the plan that fits your needs. All plans include basic messaging capabilities.
Free
??? 1 Session
??? Basic Messaging
??? Dashboard Access
???499/mo
??? 1 Session
??? All Notifications
??? Webhooks
???999/mo
??? 3 Sessions
??? Bulk Messaging
??? Webhooks
???1,999/mo
??? 6 Sessions
??? Full API Access
??? Priority Support
???3,999/mo
??? 15 Sessions
??? Custom Integrations
??? Dedicated Support
Feature Availability
| Feature | Trial | Starter | Growth | Business | Enterprise |
|---|---|---|---|---|---|
| Basic Messaging | ??? | ??? | ??? | ??? | ??? |
| All Notifications | ??? | ??? | ??? | ??? | ??? |
| Webhooks | ??? | ??? | ??? | ??? | ??? |
| Bulk Messaging | ??? | ??? | ??? | ??? | ??? |
| API Access | ??? | ??? | ??? | ??? | ??? |
| Priority Support | ??? | ??? | ??? | ??? | ??? |
| Custom Integrations | ??? | ??? | ??? | ??? | ??? |
๐ Complete Code Examples
Copy-paste these examples to get started quickly.
Node.js - Complete Integration
const BASE_URL = 'https://wamessenger.alintro.com/api';
class WAMessenger {
constructor() {
this.token = null;
this.sessionId = null;
}
async login(email, password) {
const response = await fetch(`${BASE_URL}/login`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ email, password })
});
const data = await response.json();
this.token = data.token;
return data;
}
async createSession(name = 'My Session') {
const response = await fetch(`${BASE_URL}/sessions`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${this.token}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({ name })
});
const data = await response.json();
this.sessionId = data.sessionId;
return data;
}
async getQRCode() {
const response = await fetch(`${BASE_URL}/sessions/${this.sessionId}/qr`, {
headers: { 'Authorization': `Bearer ${this.token}` }
});
return response.json();
}
async waitForConnection(maxAttempts = 60, interval = 2000) {
for (let i = 0; i < maxAttempts; i++) {
const response = await fetch(`${BASE_URL}/sessions/${this.sessionId}/status`, {
headers: { 'Authorization': `Bearer ${this.token}` }
});
const data = await response.json();
if (data.status === 'connected') {
return true;
}
await new Promise(resolve => setTimeout(resolve, interval));
}
throw new Error('Connection timeout');
}
async sendMessage(to, message) {
const response = await fetch(`${BASE_URL}/sessions/${this.sessionId}/send`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${this.token}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({ to, message })
});
return response.json();
}
}
// Usage
async function main() {
const wa = new WAMessenger();
// Login
await wa.login('your@email.com', 'password');
// Create session
await wa.createSession('My Bot');
// Get QR code and display it
const { qrCode } = await wa.getQRCode();
console.log('Scan this QR code with WhatsApp:', qrCode);
// Wait for connection
await wa.waitForConnection();
console.log('Connected!');
// Send a message
const result = await wa.sendMessage('919876543210', 'Hello from my bot!');
console.log(result.success ? 'Message sent!' : 'Failed to send');
}
main().catch(console.error);
Python - Complete Integration
import requests
import time
class WAMessenger:
BASE_URL = 'https://wamessenger.alintro.com/api'
def __init__(self):
self.token = None
self.session_id = None
def _headers(self):
return {
'Authorization': f'Bearer {self.token}',
'Content-Type': 'application/json'
}
def login(self, email, password):
response = requests.post(
f'{self.BASE_URL}/login',
json={'email': email, 'password': password}
)
data = response.json()
self.token = data['token']
return data
def create_session(self, name='My Session'):
response = requests.post(
f'{self.BASE_URL}/sessions',
headers=self._headers(),
json={'name': name}
)
data = response.json()
self.session_id = data['sessionId']
return data
def get_qr_code(self):
response = requests.get(
f'{self.BASE_URL}/sessions/{self.session_id}/qr',
headers=self._headers()
)
return response.json()
def wait_for_connection(self, max_attempts=60, interval=2):
for _ in range(max_attempts):
response = requests.get(
f'{self.BASE_URL}/sessions/{self.session_id}/status',
headers=self._headers()
)
data = response.json()
if data['status'] == 'connected':
return True
time.sleep(interval)
raise TimeoutError('Connection timeout')
def send_message(self, to, message):
response = requests.post(
f'{self.BASE_URL}/sessions/{self.session_id}/send',
headers=self._headers(),
json={'to': to, 'message': message}
)
return response.json()
# Usage
if __name__ == '__main__':
wa = WAMessenger()
# Login
wa.login('your@email.com', 'password')
# Create session
wa.create_session('My Bot')
# Get and display QR code
qr_data = wa.get_qr_code()
print('Scan QR code:', qr_data.get('qrCode', 'Not available yet'))
# Wait for connection
wa.wait_for_connection()
print('Connected!')
# Send a message
result = wa.send_message('919876543210', 'Hello from my Python bot!')
print('Sent!' if result['success'] else 'Failed')
cURL - Quick Test Script
#!/bin/bash
# WAMessenger Quick Test Script
BASE_URL="https://wamessenger.alintro.com/api"
EMAIL="your@email.com"
PASSWORD="password"
# Login
echo "Logging in..."
TOKEN=$(curl -s -X POST "$BASE_URL/login" \
-H "Content-Type: application/json" \
-d "{\"email\":\"$EMAIL\",\"password\":\"$PASSWORD\"}" \
| jq -r '.token')
echo "Token: ${TOKEN:0:20}..."
# Create session
echo "Creating session..."
SESSION_ID=$(curl -s -X POST "$BASE_URL/sessions" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"Test Session"}' \
| jq -r '.sessionId')
echo "Session ID: $SESSION_ID"
# Get QR code
echo "Getting QR code..."
curl -s "$BASE_URL/sessions/$SESSION_ID/qr" \
-H "Authorization: Bearer $TOKEN" | jq
# Wait for user to scan, then send message
read -p "Press Enter after scanning QR code..."
# Send message
curl -X POST "$BASE_URL/sessions/$SESSION_ID/send" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"to":"919876543210","message":"Hello from script!"}'