WhatsApp Automation Platform
LIVE API — v1.0

WhatsApp API Documentation

Send messages, manage sessions, and receive webhooks using your access token. All endpoints are authenticated with your api_key.

Base URL
http://sow.theheronschool.co.ke/api/v1/whatsapp
Auth Method
?api_key=YOUR_TOKEN
Format
JSON
AI-Friendly Spec
OpenAPI JSON

AI Integration

Quick start for AI systems and automation

Quick Start for AI

AI systems can integrate with this API in 3 simple steps:

  1. Get the OpenAPI spec: Fetch /api-spec for complete API definition
  2. Authenticate: Include your api_key as a query parameter
  3. Make requests: Send JSON payloads to endpoints and handle responses

Example: Python 

import requests

# Configuration
BASE_URL = "http://sow.theheronschool.co.ke/api/v1/whatsapp"
API_KEY = "YOUR_ACCESS_TOKEN"

# Send a message
response = requests.post(
    f"{BASE_URL}/send",
    params={"api_key": API_KEY},
    json={
        "to": "254712345678",
        "message": "Hello from AI!",
        "type": "text"
    }
)

# Check response
if response.status_code == 200:
    print(response.json())

Example: JavaScript (Node.js) 

const axios = require('axios');

// Configuration
const BASE_URL = 'http://sow.theheronschool.co.ke/api/v1/whatsapp';
const API_KEY = 'YOUR_ACCESS_TOKEN';

// Send a message
async function sendMessage(phone, message) {
  try {
    const response = await axios.post(`${BASE_URL}/send`, {
      to: phone,
      message: message,
      type: 'text'
    }, {
      params: { api_key: API_KEY }
    });
    return response.data;
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
  }
}

// Usage
sendMessage('254712345678', 'Hello from AI!');

AI Best Practices

  • Error Handling: Always check the success field in responses
  • Rate Limiting: Implement exponential backoff for failed requests
  • Phone Format: Use international format without + prefix (e.g., 254712345678)
  • Session Status: Check /status before sending messages
  • Broadcast: Use /broadcast for bulk sends (max 500 recipients)
  • Webhooks: Register webhooks to receive real-time message events

Anti-Ban Protection

This API includes built-in anti-ban measures to protect your WhatsApp account from being banned by WhatsApp:

  • Rate Limiting: Automatic hourly (20) and daily (120) message limits for unpaid users (paid plans have higher limits)
  • Warm-up Period: New numbers start with reduced limits (10→120 messages over 7 days) to build trust
  • Dynamic Delays: Random delays (3-10 seconds) between messages to appear more natural
  • Automatic Throttling: System automatically pauses if limits are exceeded
  • Usage Tracking: Real-time monitoring of message frequency and patterns
Rate Limit Response (HTTP 429)
{
  "success": false,
  "message": "Daily limit of 120 messages exceeded",
  "error": "daily_limit_exceeded",
  "retry_after": 28654
}

OpenAPI Specification

Download the complete OpenAPI 3.0.0 specification for your AI system:

Authentication

How to authenticate all API requests

Every API request requires your access token (also called api_key). You can find your token on the Linked Numbers page next to each instance.

# Pass as query parameter
GET /api/v1/whatsapp/status?api_key=YOUR_ACCESS_TOKEN
GET /status Get Instance Status

Session Management

Start, stop, and sync your WhatsApp session

POST /start Start Session
POST /sync Sync Session State
GET /qr Get QR Code

Send Messages

Send text and media messages to any WhatsApp number

Phone numbers must be in international format without the + prefix. Example: 254712345678
POST /send Send Text Message
POST /send Send Media Message

Profile Info

Retrieve WhatsApp profile data for your linked number

GET /status Get Profile Data

Webhooks

Receive real-time events on your server

Register a URL to receive POST requests whenever an event occurs on your instance (new message, connection status change, etc.).

Webhook Payload Structure
{
  "event": "message",
  "instance_id": "YOUR_ENGINE_ID",
  "timestamp": 1719230400,
  "data": {
    "from": "254712345678@s.whatsapp.net",
    "body": "Hello!",
    "id": "3EB0C767D97B42B1B6C5",
    "timestamp": 1719230400
  }
}
GET /webhooks List Webhooks
POST /webhooks Register Webhook
DELETE /webhooks/{id} Delete Webhook

Message Logs

Retrieve sent and received message history

GET /messages Get Message Logs

Broadcast — Bulk Send

Send one message to many parents at once. Track delivery per recipient.

School use-case: Send fee reminders, exam results, event notices, or report card alerts to all parents in one API call. Use {'{name}'} in your message to personalise with each parent's name automatically.
POST /broadcast Send Broadcast Message
GET /broadcast List Broadcasts & Stats
GET /broadcast/{id} Get Broadcast Result

Error Responses

401 Unauthorized Invalid or missing api_key
400 Bad Request Missing required parameters
404 Not Found Instance or resource not found
503 Service Unavailable WhatsApp engine is unreachable
500 Server Error Unexpected internal error