Official REST APIs &
Real-Time WhatsApp Webhooks
Build bespoke automations, connect internal ERPs & CRMs, and dispatch high-throughput transactional WhatsApp messages through official Meta Cloud infrastructure.
RESTful Endpoint Specifications
All requests accept standard JSON payloads with Bearer Token authentication.
/api/v1/auth/login1. User & Service Account Authentication
Exchange your registered CONVOZA credentials for a signed JWT Bearer Token (Authorization: Bearer <TOKEN>), or pass an organization API key directly via x-api-key: cvz_live_... for server-to-server ERPs and CRMs.
curl -X POST https://convoza.emperorsmartsolutions.com/api/v1/auth/login \
-H "Content-Type: application/json" \
-d '{
"email": "admin@emperorsmartsolutions.com",
"password": "YourSecurePassword!"
}'{
"success": true,
"data": {
"tokens": {
"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.ey...",
"refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.rf..."
},
"user": {
"id": "usr_99f2e18",
"email": "admin@emperorsmartsolutions.com",
"organization": "Emperor Smart Solutions"
}
}
}/api/v1/messages/send2. Dispatch Meta Cloud Template & Dynamic Broadcast
Dispatch an approved Meta Cloud message template with variable replacement ({{1}}, {{2}}). Message is validated, rate-limited via token-bucket outbox worker, and submitted to Meta Cloud Graph API within milliseconds.
# Authenticate with x-api-key: cvz_live_... OR Authorization: Bearer <JWT>
curl -X POST https://convoza.emperorsmartsolutions.com/api/v1/messages/send \
-H "x-api-key: cvz_live_9f8a7b6c5d4e3f2a1b0c" \
-H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
"phoneNumberId": "102938475610293",
"recipientPhone": "+919876540001",
"type": "TEMPLATE",
"templateId": "tpl_order_confirmation",
"templateParameters": {
"1": "Sarah",
"2": "ESS-4912",
"3": "₹2,499"
}
}'{
"success": true,
"messageId": "msg_wamid_HBgLMOTE5ODc2NTQwMDAxFAARABgUM0ExMjU2",
"outboxQueueId": "obx_7f9a2e8c1b",
"status": "QUEUED_FOR_DISPATCH",
"recipient": "+919876540001",
"template": "tpl_order_confirmation",
"metaQualityRating": "GREEN",
"dispatchRate": "50 msg/sec",
"timestamp": "2026-11-16T14:30:00Z"
}Simulate Live API Dispatch in Real-Time
Select an endpoint, inspect the request payload, and run a test simulation to preview response headers and sub-50ms dispatch latency.
{
"phoneNumberId": "102938475610293",
"recipientPhone": "+919876540001",
"type": "TEMPLATE",
"templateId": "order_confirmation_v2",
"templateParameters": {
"1": "Sarah",
"2": "ESS-4912",
"3": "₹2,499"
}
}Real-Time Delivery Receipts & Inbound Inquiries
Subscribe your backend server to CONVOZA webhooks to listen for delivery events (delivered, read), customer replies, and quick button clicks.
{
"event": "message.received",
"timestamp": "2026-11-16T14:32:00Z",
"data": {
"messageId": "wamid.HBgLMOTE5ODc2NTQwMDAx",
"senderPhone": "+919876540001",
"senderName": "Sarah",
"type": "TEXT",
"text": "Can I get an update on delivery date?",
"conversation": {
"id": "cnv_48a912e",
"windowExpiresAt": "2026-11-17T14:32:00Z",
"isWindowOpen": true
}
}
}// Node.js Express Webhook Signature Verification
import crypto from 'crypto';
app.post('/webhook', (req, res) => {
const signature = req.headers['x-convoza-signature'];
const hmac = crypto
.createHmac('sha256', process.env.CONVOZA_WEBHOOK_SECRET)
.update(JSON.stringify(req.body))
.digest('hex');
if (signature !== hmac) {
return res.status(401).send('Invalid signature');
}
const { event, data } = req.body;
console.log(`Received ${event} for ${data.recipientPhone}`);
res.status(200).send('OK');
});HTTP Response Codes & Error Standards
Predictable error payloads with human-readable error messages and resolution suggestions.
/auth/login to refresh.Retry-After header and throttle client requests.Ready to Explore All 35+ Endpoints in Swagger?
Launch our interactive OpenAPI documentation directly against your local or staging CONVOZA cluster. Execute live requests, inspect schemas, and download models.