WhatsApp API Documentation

Powerful REST API for WhatsApp messaging integration with comprehensive examples and SDKs

REST API v1.0
Real-time messaging & delivery tracking

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

POST /api/auth/login - User Login

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
}
POST /api/auth/register - User Registration

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

POST /api/messages/send-message - Send Single Message

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"
}
POST /api/messages/send-bulk-message - Send Bulk Messages

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"]
}
GET /api/messages/message-status/{queue_id} - Check Message Status

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"
}
GET /api/messages/messages - Get Message History

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 /api/users/user/credits - Get User Credits

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 /api/users/user/profile - Get User Profile

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:

Python SDK

Official Python library for easy integration.

Download
Node.js SDK

JavaScript/TypeScript library for Node.js applications.

Download
PHP SDK

PHP library for seamless WhatsApp integration.

Download
Java SDK

Java library for enterprise applications.

Download
C# SDK

.NET library for Windows applications.

Download
Postman Collection

Ready-to-use API collection for testing.

Download

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