CONVOZA DEVELOPER PLATFORM • REST API & WEBHOOKS V1

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.

Base Endpoint URL
https://convoza.emperorsmartsolutions.com/api/v1

RESTful Endpoint Specifications

All requests accept standard JSON payloads with Bearer Token authentication.

POST/api/v1/auth/login
Public Endpoint

1. 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.

Request (CURL)
curl -X POST https://convoza.emperorsmartsolutions.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@emperorsmartsolutions.com",
    "password": "YourSecurePassword!"
  }'
JSON Response200 OK • 28ms
{
  "success": true,
  "data": {
    "tokens": {
      "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.ey...",
      "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.rf..."
    },
    "user": {
      "id": "usr_99f2e18",
      "email": "admin@emperorsmartsolutions.com",
      "organization": "Emperor Smart Solutions"
    }
  }
}
POST/api/v1/messages/send
x-api-key or Bearer JWT

2. 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.

Request (CURL)
# 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"
    }
  }'
JSON Response202 ACCEPTED • 41ms
{
  "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"
}
IN-BROWSER API TEST CONSOLE

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.

Choose Test Endpoint:
Active Request PayloadContent-Type: application/json
{
  "phoneNumberId": "102938475610293",
  "recipientPhone": "+919876540001",
  "type": "TEMPLATE",
  "templateId": "order_confirmation_v2",
  "templateParameters": {
    "1": "Sarah",
    "2": "ESS-4912",
    "3": "₹2,499"
  }
}
Simulation Response
Click "Test Endpoint Simulator" above to trigger a live execution cycle.
EVENT TELEMETRY & WEBHOOKS

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.

Sample Inbound Message EventPOST /your-webhook
{
  "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
    }
  }
}
HMAC-SHA256 Signature Verificationx-convoza-signature
// 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');
});
STATUS REFERENCE & CODES

HTTP Response Codes & Error Standards

Predictable error payloads with human-readable error messages and resolution suggestions.

Status Code
Status Title
Description & Resolution Action
200 OK
Synchronous Success
The request was executed immediately and returned expected data.
202 ACCEPTED
Queued in Outbox
Message entered the rate-limited dispatch worker queue for delivery to Meta Graph API.
400 BAD_REQUEST
Validation Failure
Missing required parameters or phone number missing E.164 country code format (+91).
401 UNAUTHORIZED
Invalid Token
Missing or expired JWT Bearer Token in Authorization header. Call /auth/login to refresh.
429 RATE_LIMITED
Throttle Triggered
Outbox capacity reached. Check Retry-After header and throttle client requests.
TEST THE FULL API SUITE

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.