WhatsApp API Documentation
Powerful REST API for WhatsApp messaging integration with comprehensive examples and SDKs
Overview
The WhatsApp API allows you to send messages via WhatsApp programmatically. Our service provides a simple REST API interface for integrating WhatsApp messaging into your applications.
Base URL
https://whatsapp.kuijpersconsulting.co.za/api
Content Type
application/json
Key Features
- Send individual messages
- Bulk message sending
- Real-time delivery tracking
- Credit-based pricing
- JWT authentication
- Template messaging
- Message history
- Admin management
- Rate limiting
Authentication
All API requests require authentication using JWT tokens. You can obtain a token by logging in with your credentials.
Getting an Access Token
curl -X POST https://whatsapp.kuijpersconsulting.co.za/api/auth/login \
-H "Content-Type: application/json" \
-d '{
"username": "your_username",
"password": "your_password"
}'
Response:
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
"token_type": "Bearer",
"user_id": 1,
"username": "your_username",
"credits": 1000,
"is_admin": false
}
Using the Token
Include the token in the Authorization header for all subsequent requests:
Authorization: Bearer YOUR_JWT_TOKEN
API Endpoints
Authentication Endpoints
Authenticate user and receive access token.
Parameters:
Parameter | Type | Required | Description |
---|---|---|---|
username |
string | Yes | Your username |
password |
string | Yes | Your password |
Example Request:
curl -X POST https://whatsapp.kuijpersconsulting.co.za/api/auth/login \
-H "Content-Type: application/json" \
-d '{
"username": "demo",
"password": "password123"
}'
Success Response:
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
"token_type": "Bearer",
"user_id": 123,
"username": "demo",
"credits": 1000,
"is_admin": false
}
Register a new user account.
Parameters:
Parameter | Type | Required | Description |
---|---|---|---|
username |
string | Yes | Unique username |
email |
string | No | Email address |
password |
string | Yes | Password |
notification_number |
string | No | Phone number for notifications |
Example Request:
curl -X POST https://whatsapp.kuijpersconsulting.co.za/api/auth/register \
-H "Content-Type: application/json" \
-d '{
"username": "newuser",
"email": "[email protected]",
"password": "securepassword",
"notification_number": "27821234567"
}'
Success Response:
{
"message": "User created successfully",
"user_id": 124
}
Message Endpoints
Send a WhatsApp message to a single recipient. Supports both plain text messages and template-based messages with variable replacement.
Parameters:
Parameter | Type | Required | Description |
---|---|---|---|
number |
string | Yes | Recipient phone number (international format) |
message |
string | No* | Message content (max 4096 characters) - Required if template_id not provided |
template_id |
integer | No* | ID of saved template - Required if message not provided |
variables |
object | No | Variables to replace in template (only used with template_id) |
Example Request (Plain Text):
curl -X POST https://whatsapp.kuijpersconsulting.co.za/api/messages/send-message \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-d '{
"number": "27821234567",
"message": "Hello from WhatsApp API!"
}'
Example Request (With Template):
curl -X POST https://whatsapp.kuijpersconsulting.co.za/api/messages/send-message \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-d '{
"number": "27821234567",
"template_id": 123,
"variables": {
"name": "John Smith",
"company": "Example Corp"
}
}'
Success Response:
{
"message": "Message queued successfully",
"queue_id": "msg_abc123",
"remaining_credits": 99,
"queue_position": 1,
"available_devices": 2,
"total_devices": 3,
"queue_type": "docker"
}
Send the same message to multiple recipients. Supports both plain text and template-based messages.
Parameters:
Parameter | Type | Required | Description |
---|---|---|---|
numbers |
array | Yes | Array of phone numbers (max 200) |
message |
string | No* | Message content - Required if template_id not provided |
template_id |
integer | No* | ID of saved template - Required if message not provided |
Example Request (Plain Text):
curl -X POST https://whatsapp.kuijpersconsulting.co.za/api/messages/send-bulk-message \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-d '{
"numbers": ["27821234567", "27829876543", "27823456789"],
"message": "Bulk message to all recipients!"
}'
Example Request (With Template):
curl -X POST https://whatsapp.kuijpersconsulting.co.za/api/messages/send-bulk-message \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-d '{
"numbers": ["27821234567", "27829876543", "27823456789"],
"template_id": 123
}'
Success Response:
{
"message": "Bulk message queued successfully for 3 numbers",
"messages_created": 3,
"remaining_credits": 97,
"queue_ids": ["msg_abc123", "msg_def456", "msg_ghi789"]
}
Check the delivery status of a specific message.
Parameters:
Parameter | Type | Required | Description |
---|---|---|---|
queue_id |
string | Yes | Message queue ID from send response |
Example Request:
curl -X GET https://whatsapp.kuijpersconsulting.co.za/api/messages/message-status/msg_abc123 \
-H "Authorization: Bearer YOUR_JWT_TOKEN"
Response:
{
"queue_id": "msg_abc123",
"number": "27821234567",
"message": "Hello from WhatsApp API!",
"status": "Sent",
"is_complete": true,
"is_error": false,
"error_message": null,
"created_at": "2025-06-03T10:30:00Z",
"updated_at": "2025-06-03T10:30:15Z"
}
Retrieve message history for the authenticated user with pagination.
Query Parameters:
Parameter | Type | Default | Description |
---|---|---|---|
page |
integer | 1 | Page number |
per_page |
integer | 10 | Messages per page |
Example Request:
curl -X GET "https://whatsapp.kuijpersconsulting.co.za/api/messages/messages?page=1&per_page=20" \
-H "Authorization: Bearer YOUR_JWT_TOKEN"
Response:
{
"messages": [
{
"queue_id": "msg_abc123",
"number": "27821234567",
"message": "Hello from API",
"status": "Sent",
"created_at": "2025-06-03T10:30:00Z"
}
],
"pagination": {
"page": 1,
"per_page": 20,
"total": 1,
"pages": 1
}
}
User Endpoints
Get the current credit balance for the authenticated user.
Example Request:
curl -X GET https://whatsapp.kuijpersconsulting.co.za/api/users/user/credits \
-H "Authorization: Bearer YOUR_JWT_TOKEN"
Response:
{
"credits": 150,
"username": "demo"
}
Get detailed profile information for the authenticated user.
Example Request:
curl -X GET https://whatsapp.kuijpersconsulting.co.za/api/users/user/profile \
-H "Authorization: Bearer YOUR_JWT_TOKEN"
Response:
{
"id": 123,
"username": "demo",
"email": "[email protected]",
"credits": 150,
"is_admin": false,
"created_at": "2025-06-01T10:00:00"
}
Error Codes
HTTP Code | Error Code | Description |
---|---|---|
400 | INVALID_REQUEST |
Missing or invalid parameters |
401 | UNAUTHORIZED |
Invalid or missing authentication token |
403 | INSUFFICIENT_CREDITS |
Not enough credits to send message |
404 | NOT_FOUND |
Resource not found |
429 | RATE_LIMITED |
Too many requests, rate limit exceeded |
500 | INTERNAL_ERROR |
Internal server error |
Error Response Format
{
"error": "INSUFFICIENT_CREDITS",
"message": "Not enough credits to send message. Required: 1, Available: 0",
"code": 403
}
Examples
Python Example
import requests
import json
# API Configuration
BASE_URL = "https://whatsapp.kuijpersconsulting.co.za/api"
USERNAME = "your_username"
PASSWORD = "your_password"
# Step 1: Login and get token
login_response = requests.post(f"{BASE_URL}/auth/login",
json={
"username": USERNAME,
"password": PASSWORD
}
)
token = login_response.json()["access_token"]
headers = {"Authorization": f"Bearer {token}"}
# Step 2: Send a message
message_response = requests.post(f"{BASE_URL}/messages/send-message",
headers=headers,
json={
"number": "27821234567",
"message": "Hello from Python!"
}
)
print("Message sent:", message_response.json())
JavaScript Example
const API_BASE = 'https://whatsapp.kuijpersconsulting.co.za/api';
// Step 1: Login and get token
async function login(username, password) {
const response = await fetch(`${API_BASE}/auth/login`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ username, password })
});
const data = await response.json();
return data.access_token;
}
// Step 2: Send message
async function sendMessage(token, number, message) {
const response = await fetch(`${API_BASE}/messages/send-message`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${token}`
},
body: JSON.stringify({ number, message })
});
return await response.json();
}
// Usage
(async () => {
const token = await login('your_username', 'your_password');
const result = await sendMessage(token, '27821234567', 'Hello from JavaScript!');
console.log('Message sent:', result);
})();
PHP Example
<?php
$baseUrl = 'https://whatsapp.kuijpersconsulting.co.za/api';
$username = 'your_username';
$password = 'your_password';
// Step 1: Login and get token
$loginData = json_encode([
'username' => $username,
'password' => $password
]);
$loginResponse = file_get_contents($baseUrl . '/auth/login', false, stream_context_create([
'http' => [
'method' => 'POST',
'header' => 'Content-Type: application/json',
'content' => $loginData
]
]));
$token = json_decode($loginResponse, true)['access_token'];
// Step 2: Send message
$messageData = json_encode([
'number' => '27821234567',
'message' => 'Hello from PHP!'
]);
$messageResponse = file_get_contents($baseUrl . '/messages/send-message', false, stream_context_create([
'http' => [
'method' => 'POST',
'header' => [
'Content-Type: application/json',
'Authorization: Bearer ' . $token
],
'content' => $messageData
]
]));
echo 'Message sent: ' . $messageResponse;
?>
SDKs & Libraries
We provide official SDKs and libraries to make integration easier:
Rate Limits
Current Rate Limits
- Authentication: 10 requests per minute
- Single Messages: 100 requests per minute
- Bulk Messages: 10 requests per minute
- Status Checks: 1000 requests per minute
Support & Contact
Technical Support
Need help with integration?
Email: [email protected]
Response Time: Within 24 hours
Developer Community
Join our developer community for tips and discussions.
Forum: Coming Soon
Discord: Coming Soon