API Details
Manage your API credentials and integrate WhatsApp messaging into your applications
API Credentials
Use these credentials to authenticate your API requests
Important: Keep your API key secure. Never share it publicly or commit it to version control. Use environment variables to store sensitive credentials.
Quick Start Guide
All API requests require authentication using your API key in the request header:
X-API-Key: your-api-key-here
Send a WhatsApp message using the simple send endpoint:
curl -X POST http://localhost:3000/api/sessions/send-simple \ -H "Content-Type: application/json" \ -H "X-API-Key: your-api-key" \ -d '{ "phoneNumber": "2348012345678", "message": "Hello from Wappi API!" }'
const axios = require('axios');
const API_ENDPOINT = 'http://localhost:3000';
const API_KEY = 'your-api-key';
async function sendWhatsAppMessage() {
try {
const response = await axios.post(
`${API_ENDPOINT}/api/sessions/send-simple`,
{
phoneNumber: '2348012345678',
message: 'Hello from Wappi API!'
},
{
headers: {
'Content-Type': 'application/json',
'X-API-Key': API_KEY
}
}
);
console.log('Message sent:', response.data);
} catch (error) {
console.error('Error:', error.response?.data || error.message);
}
}
sendWhatsAppMessage();
import requests import json API_ENDPOINT = 'http://localhost:3000' API_KEY = 'your-api-key' def send_whatsapp_message(): url = f"{API_ENDPOINT}/api/sessions/send-simple" headers = { 'Content-Type': 'application/json', 'X-API-Key': API_KEY } payload = { 'phoneNumber': '2348012345678', 'message': 'Hello from Wappi API!' } try: response = requests.post(url, headers=headers, json=payload) response.raise_for_status() print('Message sent:', response.json()) except requests.exceptions.RequestException as error: print('Error:', error) send_whatsapp_message()
<?php $apiEndpoint = 'http://localhost:3000'; $apiKey = 'your-api-key'; $data = [ 'phoneNumber' => '2348012345678', 'message' => 'Hello from Wappi API!' ]; $ch = curl_init($apiEndpoint . '/api/sessions/send-simple'); curl_setopt($ch, CURLOPT_POST, 1); curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data)); curl_setopt($ch, CURLOPT_HTTPHEADER, [ 'Content-Type: application/json', 'X-API-Key: ' . $apiKey ]); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); $response = curl_exec($ch); $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); if ($httpCode === 200) { echo "Message sent: " . $response; } else { echo "Error: " . $response; } ?>
Upload the video file itself as multipart/form-data. The file goes in a field named
video, and the recipient in phoneNumber:
curl -X POST http://localhost:3000/api/sessions/send-video-simple \ -H "X-API-Key: your-api-key" \ -F "phoneNumber=2348012345678" \ -F "caption=Our new product!" \ -F "video=@promo.mp4;type=video/mp4"
The number can be 2348012345678, +2348012345678 or 08012345678 —
all three work. Videos must be 40 MB or less and 60 seconds or shorter.
See Sending Video for captions, GIF playback
and video notes.
Same idea as video: the photo goes in a field named image. Add
hd=true to send the original at full resolution instead of standard quality:
curl -X POST http://localhost:3000/api/sessions/send-image-simple \ -H "X-API-Key: your-api-key" \ -F "phoneNumber=2348012345678" \ -F "caption=Our new product!" \ -F "hd=true" \ -F "image=@product.jpg;type=image/jpeg"
Photos are never re-encoded, so the recipient gets exactly the bytes you upload.
hd=true raises the size limit from 16 MB to 32 MB; the response's
image.hd.deliveredAsHd tells you whether the photo was large enough
(over 1600 px on its longest edge) to show as HD on the recipient's phone.
Accepted formats are JPEG, PNG and WebP.
Available Endpoints
Complete list of API endpoints available in your plan
Sending Video
Upload the video file itself as multipart/form-data — the same way you'd upload any
file. The file goes in a part named video; everything else rides along as ordinary
form fields. We detect the format from the file's own header, so a missing or wrong
Content-Type on the part is fine.
Video limits
• Max file size: 40 MB
• Max duration: 60 seconds
• Formats: mp4, 3gp, mov, webm, mkv — mp4 (H.264 + AAC) plays everywhere, the rest may not
• Cost: 1 credit per video, automatically refunded if delivery fails
video (file) required — the video file, field name must be "video" phoneNumber (text) required — 2348012345678, +2348012345678 or 08012345678 caption (text) optional — text shown under the video gifPlayback (text) optional — "true" sends a silent looping clip asVideoNote (text) optional — "true" sends a round video note (mp4 only, no caption)
curl -X POST http://localhost:3000/api/sessions/send-video-simple \ -H "X-API-Key: your-api-key" \ -F "phoneNumber=2348012345678" \ -F "caption=Our new product!" \ -F "video=@promo.mp4;type=video/mp4"
const axios = require('axios');
const fs = require('fs');
const FormData = require('form-data');
const API_ENDPOINT = 'http://localhost:3000';
const API_KEY = 'your-api-key';
async function sendWhatsAppVideo() {
const form = new FormData();
form.append('phoneNumber', '2348012345678');
form.append('caption', 'Our new product!');
form.append('video', fs.createReadStream('promo.mp4'));
try {
const response = await axios.post(
`${API_ENDPOINT}/api/sessions/send-video-simple`,
form,
{
headers: { ...form.getHeaders(), 'X-API-Key': API_KEY },
maxBodyLength: Infinity,
timeout: 300000 // large uploads take a while
}
);
console.log('Video sent:', response.data);
} catch (error) {
console.error('Error:', error.response?.data || error.message);
}
}
sendWhatsAppVideo();
import requests API_ENDPOINT = 'http://localhost:3000' API_KEY = 'your-api-key' def send_whatsapp_video(): url = f"{API_ENDPOINT}/api/sessions/send-video-simple" headers = {'X-API-Key': API_KEY} # requests sets the multipart Content-Type data = { 'phoneNumber': '2348012345678', 'caption': 'Our new product!' } try: with open('promo.mp4', 'rb') as f: files = {'video': ('promo.mp4', f, 'video/mp4')} response = requests.post(url, headers=headers, data=data, files=files, timeout=300) response.raise_for_status() print('Video sent:', response.json()) except requests.exceptions.RequestException as error: print('Error:', error) send_whatsapp_video()
<?php $apiEndpoint = 'http://localhost:3000'; $apiKey = 'your-api-key'; $data = [ 'phoneNumber' => '2348012345678', 'caption' => 'Our new product!', 'video' => new CURLFile('promo.mp4', 'video/mp4', 'promo.mp4') ]; $ch = curl_init($apiEndpoint . '/api/sessions/send-video-simple'); curl_setopt($ch, CURLOPT_POST, 1); curl_setopt($ch, CURLOPT_POSTFIELDS, $data); // array => multipart/form-data curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: ' . $apiKey]); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_TIMEOUT, 300); $response = curl_exec($ch); $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); if ($httpCode === 200) { echo "Video sent: " . $response; } else { echo "Error: " . $response; } ?>
{
"success": true,
"data": {
"messageId": "3EB0ABCD1234",
"sessionId": "session_abc",
"phoneNumber": "2348012345678",
"caption": "Our new product!",
"video": {
"mimetype": "video/mp4",
"sizeBytes": 8412345,
"durationSeconds": 42.5,
"fileName": "promo.mp4"
},
"creditsDeducted": 1,
"creditsRemaining": 87
}
}
| Status | Meaning |
|---|---|
| 400 | No file attached, wrong field name, missing phone number, unsupported format, or video longer than 60 seconds |
| 402 | Not enough credits |
| 403 | That session belongs to another account |
| 413 | Video is over 40 MB |
| 500 | Delivery failed — your credit is refunded automatically |
Rate Limits & Usage
Current Plan: Free Tier
• 100 messages per day
• 1 WhatsApp device connection
• Rate limit: 10 requests per minute
• Webhook support: Not available
Upgrade to a paid plan for higher limits and advanced features:
Upgrade PlanResponse Format
All API responses follow this standard format:
{
"success": true,
"data": {
"messageId": "msg_123456",
"sessionId": "session_abc",
"phoneNumber": "+2348012345678",
"message": "Hello from Wappi API!",
"sentVia": "+2349087654321"
}
}
{
"success": false,
"error": "No active WhatsApp session found",
"hint": "Open http://localhost:3000/qr-scanner.html and scan QR code to connect"
}
Best Practices
1. Secure Your API Key
Never expose your API key in client-side code. Always make API calls from your backend server.
2. Handle Errors Gracefully
Always check the response status and handle errors appropriately. Implement retry logic with exponential backoff.
3. Respect Rate Limits
Monitor your usage and implement request throttling to avoid hitting rate limits.
4. Phone Number Format
Always use international format with country code (e.g., +2348012345678). Include the + symbol.
5. Session Management
Keep your WhatsApp session connected. If disconnected, you'll need to scan the QR code again to reconnect.