You are viewing public documentation. The code samples below show placeholder credentials. Log in or register to see your real API key pre-filled in every example.

API Documentation

Complete guide to integrating SMESS WhatsApp API into your application

Queue-Based Delivery Auto-Retry Logic Real-time Processing

API Key YOUR_API_KEY_HERE

Quick Navigation

Quick Start Guide

Get Your API Key

YOUR_API_KEY_HERE

Make Your First Request

Send messages via POST to the API endpoint.

Check Queue Status

Monitor message delivery and track queue status.

Handle Responses

Process success and error responses accordingly.

Authentication

All API requests require your API key. Include it in every request:

$curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_URL => 'https://smess.io/api/send',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => http_build_query([
        'apikey' => 'YOUR_API_KEY_HERE',
        'recipient' => '+233244123456',
        'text' => 'Hello World!'
    ])
]);
$response = curl_exec($curl);
curl_close($curl);

Security Tip: Keep your API key secure and never expose it in client-side code. Always make API calls from a server.

Send Text Message

POST https://smess.io/api/send

Parameters

Name	Type	Required	Description
apikey	string	Yes	Your API authentication key. Not `api_key`.
recipient	string	Yes	Phone number with country code (e.g., +233244123456). Not `phone`.
text	string	Yes	Message content to send. Not `message`.

Example Request

$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL => 'https://smess.io/api/send',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => http_build_query([
        'apikey' => 'YOUR_API_KEY_HERE',
        'recipient' => '+233244123456',
        'text' => 'Hello from SMESS!'
    ])
]);
$response = curl_exec($ch);
$data = json_decode($response, true);
curl_close($ch);

Response

Success Response

{
    "success": true,
    "message": "Message queued successfully",
    "queue_id": "q_abc123def456",
    "estimated_delivery": "2-3 seconds"
}

Send Media Message

POST https://smess.io/api/send

Documents, images, and all media are sent through the same endpoint. Use the appropriate parameters to specify the media type.

Parameters

Name	Type	Required	Description
apikey	string	Yes	Your API authentication key
recipient	string	Yes	Phone number with country code (e.g., +233244123456)
document	string	Yes	Public URL to the document (PDF, DOC, etc.)
text	string	No	Optional caption for the document
filename	string	No	Display filename (e.g., Invoice-2024.pdf)

Example Request

$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL => 'https://smess.io/api/send',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => http_build_query([
        'apikey' => 'YOUR_API_KEY_HERE',
        'recipient' => '+233244123456',
        'document' => 'https://example.com/invoice.pdf',
        'text' => 'Here is your document',
        'filename' => 'Invoice-2024.pdf'
    ])
]);
$response = curl_exec($ch);
curl_close($ch);

Check Queue Status

GET https://smess.io/api/queue-status?apikey={API_KEY}&queue_id={QUEUE_ID}

Example Response

{
    "success": true,
    "queue_id": "q_abc123def456",
    "status": "delivered",
    "attempts": 1,
    "created_at": "2024-01-15T10:30:00Z",
    "delivered_at": "2024-01-15T10:30:02Z"
}

Error Handling

The API returns appropriate HTTP status codes and JSON error responses:

400	Bad Request - Missing or invalid parameters
401	Unauthorized - Invalid API key
403	Forbidden - Account suspended or rate limited
429	Too Many Requests - Rate limit exceeded
503	Service Unavailable - WhatsApp service down

Error Response Example

{
    "success": false,
    "error": "Invalid API key",
    "code": "AUTH_INVALID"
}

Rate Limits

To ensure fair usage and system stability, the following rate limits apply:

Per Second

10 requests

Per Hour

1000 requests

Pro Tip: Use queuing for bulk messages. The system automatically spaces out deliveries to prevent rate limiting.

Troubleshooting

Common mistakes that cause API errors:

HTTP 401 — "API key is required"

This error means the server did not receive your API key. Most common cause: wrong parameter name.

❌ Wrong (will fail)	✅ Correct
`api_key` (with underscore)	`apikey`
`Authorization: Bearer` header	`apikey` as POST form field
`key` or `token`	`apikey`
JSON body (`Content-Type: application/json`)	`application/x-www-form-urlencoded`

HTTP 400 — Missing Parameters

❌ Wrong (will fail)	✅ Correct
`phone`, `number`, `to`	`recipient`
`message`, `msg`, `body`	`text`

✅ Correct Example

curl -X POST https://smess.io/api/send \
  -d "apikey=YOUR_API_KEY_HERE" \
  -d "recipient=+233244123456" \
  -d "text=Hello, this works!"

❌ Incorrect Example (will return 401)

# WRONG - these parameter names are NOT accepted
curl -X POST https://smess.io/api/send \
  -d "api_key=YOUR_API_KEY_HERE" \
  -d "phone=+233244123456" \
  -d "message=This will fail with 401"