API Reference: Overview

Voxvaani provides REST APIs for integrating communication features into your own applications.

Quick Reference

Property	Value
Base URL	`https://voxvaani.com/api/v1`
Auth Header	`x-api-key: YOUR_API_KEY`
Content-Type	`application/json`
Response Format	JSON with `success` / `error` envelope
File Uploads	`multipart/form-data`

ℹ️ Sandbox Environment

If your instance provides a sandbox or staging environment, your administrator will share the sandbox URL separately. Sandbox keys and production keys are environment-specific — never mix them. Test integrations against sandbox before pointing at production.

Supported HTTP Methods

Method	Usage
GET	Retrieve resources (balance, campaign status, templates)
POST	Create resources, send messages, trigger actions
PUT	Update resources (webhook endpoints, templates)
DELETE	Remove resources (webhook endpoints, templates)

Available APIs

API	Description
WhatsApp API	Send WhatsApp messages, templates, bulk sends, media, and manage webhooks
Email API	Send emails programmatically
Voice API	Initiate voice calls and query call logs
Balance API	Check resource balances

Authentication

All API requests require an API Key passed in the request header. Keys can be sent via any of these methods:

Recommended: x-api-key: YOUR_API_KEY
Alternative: Authorization: Bearer YOUR_API_KEY
Also supported: Authorization: ApiKey YOUR_API_KEY

See the Authentication guide for full details, including permission scopes and multi-key strategy.

Common Response Patterns

Success Response


{
  "success": true,
  "message": "Human-readable description",
  "...additional endpoint-specific fields..."
}

Endpoint-specific fields vary. For example, a message send response includes metaMessageId and cost, while a balance check includes whatsappBalance, voiceMins, etc.

Error Response


{
  "error": "Human-readable error description"
}

Every error response uses this single-field shape, with one exception: POST /whatsapp/send returns {"success": false, "error": "...", "screenshot": ...} with a 500 status when the browser-based dispatch fails.

HTTP Status Codes

Code	Meaning	When to Expect It
200	Success	Standard read and write operations, including asynchronous jobs such as bulk send
201	Created	Resource created (e.g., new webhook)
400	Bad Request	Invalid or missing parameters
401	Unauthorized	Missing or invalid API key
402	Payment Required	Insufficient resource balance
403	Forbidden	API key lacks the required permission scope
404	Not Found	Endpoint or resource does not exist
500	Internal Server Error	Unexpected server-side failure

Rate Limiting

Currently, the Voxvaani API does not enforce hard rate limits on API keys. However:

Bulk endpoints (/whatsapp/bulk-send) are designed for high throughput and process asynchronously.
Excessive usage that threatens platform stability may trigger administrative safeguards.
Third-party limits apply — Meta may throttle template message delivery if your WABA is new or has a low quality rating.

Best practice: For bulk operations, use the dedicated bulk-send endpoint rather than sending individual messages in a tight loop. Bulk-send accepts up to 10,000 recipients in a single request and processes them asynchronously.

API Versioning Policy

The current API version is v1, reflected in the base URL path /api/v1/. Versioning policy:

Backward-compatible additions (new endpoints, new optional fields) may be added to v1 without notice.
Breaking changes (removed fields, changed field types, changed required/optional) will be released under a new version (v2).
Deprecation notices for v1 features will be communicated at least 90 days before removal.
Version in URL: Always specify the version in your API calls (/api/v1/...). Omitting the version may route to an unexpected API version.

SDK Availability

Voxvaani does not currently offer official SDKs. You interact with the API directly over HTTPS:

Use curl for testing and scripting.
Use your language’s HTTP client library (fetch, axios, requests, okhttp) for production integrations.
Reference the code examples in each endpoint’s documentation for curl, Python, and JavaScript implementations.