Connect Voxio Chat to your CRM, helpdesk, automation platform, or custom application. Build customer experiences across WhatsApp, Instagram, and Messenger using one secure API.
The modern API uses portable communication primitives—channels, contacts, conversations, messages, templates, CSV Blast, and webhooks—so an external CRM or automation system can keep its own ticketing, routing, assignment, and UI.
Use OAuth 2.0 for new connected applications. Voxio uses a workspace-owner consent screen, PKCE S256, scoped access tokens, refresh tokens, and runtime entitlement checks.
1Authorize/oauth/authorize
2User consentWorkspace owner approves scopes
3Exchange codePOST /oauth/token
4Call APIAuthorization: Bearer …
Token lifecycle
Access tokens expire after 1 hour. Refresh tokens expire after 60 days. Refresh token rotation does not grant additional scopes; request new authorization when additional permissions are needed.
Request only the permissions your integration needs. Runtime subscription and feature entitlement are still checked even after a scope has been granted.
Scope
Access
profile:read
Workspace profile and API capability information.
channels:read
Connected WhatsApp, Instagram, and Messenger channels.
contacts:read / contacts:write
Read, create, and update customer contacts.
conversations:read / conversations:write
Read conversations and update portable conversation state.
messages:read / messages:send
Read message history/media and send supported messages.
templates:read
Read approved WhatsApp templates.
csv_blast:read / csv_blast:write
Read and create CSV Blast campaigns.
webhooks:read / webhooks:write
Read and manage omnichannel webhook subscriptions. Requires current Inbound Relay entitlement.
connection:read / connection:revoke
Read OAuth connection metadata or revoke the current connected application.
RELIABILITY
Errors, trace IDs & rate limits
API v1 uses standard HTTP status codes and JSON error responses. Keep the returned trace ID when contacting support.
401Missing or invalid authentication
403Scope, entitlement, or policy denied
404Resource not found or not visible to this tenant
409State or idempotency conflict
422Validation or business-rule rejection
429Rate limit exceeded
JSON
{
"remark": "not_found",
"status": "error",
"message": ["The requested resource was not found."],
"data": {
"trace_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
}
PLATFORM API
Workspace / Me
Confirm the connected workspace, active API capability, Inbound Relay capability, and granted OAuth scopes.
GET/me
profile:readTenant-bound OAuth profile endpoint.
PLATFORM API
Channels
List connected tenant channels using canonical IDs such as whatsapp:29, instagram:61, and messenger:59. Operational/platform WhatsApp numbers are not exposed as tenant outbound channels.
Read, create, and update portable contact records without exposing internal lead-scoring or profile-sync metadata. Creating a contact does not create a conversation.
Method
Endpoint
Scope
GET
/contacts
contacts:read
GET
/contacts/{id}
contacts:read
POST
/contacts
contacts:write
PATCH
/contacts/{id}
contacts:write
Identity safetyInstagram and Messenger managed identities cannot be arbitrarily changed through the API. Cross-workspace resources are not visible.
PLATFORM API
Conversations
A lean conversation contract for external CRMs and helpdesks. Voxio exposes communication state without duplicating assignment, SLA, routing, agent-presence, or Inbox-specific workflow.
Method
Endpoint
Scope
GET
/conversations
conversations:read
GET
/conversations/{id}
conversations:read
PATCH
/conversations/{id}
conversations:write
Portable status values are open and closed. List filters include channel, channel ID, contact ID, status, and incremental updated_since.
PLATFORM API
Messages
Read message history and delivery state, or send direct session messages through an existing conversation. Text, image, video, audio, and document remain conversation-scoped. For business-initiated WhatsApp template delivery to a phone number, use the Templates resource instead of requiring a pre-existing conversation.
Method
Endpoint
Scope
GET
/conversations/{conversation}/messages
messages:read
POST
/conversations/{conversation}/messages
messages:send
GET
/messages/{message}
messages:read
GET
/messages/{message}/media
messages:read
Idempotent send
cURL
curl -X POST 'https://voxio.chat/external-api/v1/conversations/CONVERSATION_ID/messages' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: UNIQUE_REQUEST_KEY' \
--data '{"type":"text","text":"Hello from my integration"}'
WHATSAPP
Templates
Read approved WhatsApp templates or send one approved template directly to a phone number. A direct template send resolves or creates the Voxio contact and conversation for the selected WhatsApp channel, then queues delivery through the same Voxio template billing and provider pipeline used by Inbox.
Method
Endpoint
Scope
GET
/templates
templates:read
GET
/templates/{template}
templates:read
POST
/template-messages
messages:send
COMPAT
/conversations/{conversation}/messages with type=template
Recipient-first deliveryThe recipient does not need to have an existing conversation. Voxio normalizes the phone number, reuses or creates the workspace contact, reuses or creates the conversation for the selected WhatsApp account, queues the template, and returns contact_id, conversation_id, and message_id. The generated message remains visible in Voxio conversation history.
Legacy compatibilityThe existing legacy /inbox/send-template-message endpoint remains available with Client ID + Client Secret + IP whitelist and continues to target mobile_code + mobile. OAuth integrations should use /v1/template-messages.
BULK MESSAGING
CSV Blast
Upload a CSV file and queue a WhatsApp template blast without pre-saving every recipient as a contact. Delivery status can be read per campaign and recipient.
Method
Endpoint
Scope
GET
/csv-blasts
csv_blast:read
POST
/csv-blasts
csv_blast:write
GET
/csv-blasts/{blast}
csv_blast:read
GET
/csv-blasts/{blast}/recipients
csv_blast:read
IdempotencySupply Idempotency-Key when creating a blast. Replaying the same request returns the existing blast; reusing the same key for a different request returns HTTP 409.
WEBHOOKS
Omnichannel webhooks
Manage the workspace Inbound Relay subscription through OAuth. One subscription can select WhatsApp, Instagram, and Messenger channels and events such as incoming messages, message status updates, and WhatsApp Flow completion.
Method
Endpoint
Scope
GET
/webhooks / /webhooks/{webhook}
webhooks:read
POST
/webhooks
webhooks:write
PATCH
/webhooks/{webhook}
webhooks:write
DELETE
/webhooks/{webhook}
webhooks:write
POST
/webhooks/{webhook}/rotate-secret
webhooks:write
POST
/webhooks/{webhook}/test
webhooks:write
Automatic provisioning with OAuthOAuth applications granted webhooks:write can register or update the workspace webhook subscription programmatically after authorization. The user does not need to configure Inbound Relay manually. The application should supply its HTTPS callback URL, requested events, and selected Voxio channel IDs, then enable the subscription through this API. The workspace must still have an active Inbound Relay entitlement; OAuth scopes never bypass feature entitlement.
URL policyWebhook destinations must use HTTPS and resolve to a public IP address. Private, reserved, or unresolved destinations are rejected.
SECURITY
OAuth connection lifecycle
Connected applications can inspect the current connection metadata or revoke the application's access for the workspace.
Method
Endpoint
Scope
GET
/oauth/connection
connection:read
DELETE
/oauth/connection
connection:revoke
Revocation invalidates the application's access and refresh tokens for the workspace/client connection.
SECURITY
Webhook signatures
Verify webhook delivery using the relay signing secret. New receivers should use the timestamp-bound signature and deduplicate retry deliveries by delivery ID.
Header
Purpose
X-Voxio-Webhook-Signature
HMAC SHA-256 of timestamp + "." + exact_raw_body.
X-Voxio-Signature-V2
Compatibility alias for the same timestamp-bound HMAC.
X-Voxio-Timestamp
Unix timestamp included in the signed content.
X-Voxio-Delivery-Id
Stable delivery identifier for receiver-side deduplication.
Use a unique Idempotency-Key when creating side effects such as message sends and CSV Blast campaigns. Retrying the same request can safely return the original resource instead of creating duplicates.
LOCALIZATION
Tenant timezones
Timestamp output follows the workspace timezone configured by each Voxio tenant. Integrations should parse the ISO-8601 offset instead of assuming UTC or a fixed +07:00 offset.
MIGRATION
Legacy API → OAuth 2.0
Existing Client ID/Secret integrations can continue running. For new integrations, migrate to OAuth incrementally: register an OAuth client, request only required scopes, switch calls to /external-api/v1, then retire legacy credentials after your integration is fully verified.
1Create/register OAuth client + callback
2Implement PKCE + state validation
3Map legacy calls to v1 resources
4Verify production behavior and revoke old access when ready
EXISTING INTEGRATIONS
Legacy API reference
These endpoints remain available for existing Client ID + Client Secret integrations protected by the workspace IP whitelist. New third-party applications should prefer OAuth 2.0 + PKCE and the /external-api/v1 resources above.
Legacy authenticationSend client-id and client-secret headers from a whitelisted public IP address. Do not place credentials in browser-side JavaScript.
This endpoint allows you to add a new contact to your Voxio Chat account.
Provide the necessary contact details, and upon successful request, the API returns
the created contact’s information in JSON format for easy integration.
Note: For multi-number accounts, send whatsapp_account_id or
from_number so the contact is linked to the correct sender scope and appears in
/inbox/conversation-list.
POST
/contact/store
Required Fields
The following fields are required to create a new contact in the system.
This endpoint updates an existing contact by ID. Send all required fields (firstname, lastname, mobile_code, mobile) plus any optional fields you want to update.
Note: For multi-number accounts, include whatsapp_account_id or
from_number to bind/update the contact scope so it appears in
/inbox/conversation-list filters.
POST
/contact/update/{id}
Required Fields
The following fields are required to update a contact in the system.
Retrieve a paginated list of conversations for the authenticated user, including contact info and conversation status.
GET
/inbox/conversation-list
Query Parameters
Name
Description
Default
status
Filter conversations by status. Use below value for the filter conversation via status. Done = 1;
Pending = 2;
Important = 3;
Unread = 4;
Reset/All = 0;
All
whatsapp_account_id
Filter conversations by specific sender account ID.
Send WhatsApp messages to a mobile number. This endpoint supports text, media, location, interactive lists, CTA URLs, and e-commerce messages. If no existing contact or conversation is found for the provided phone number, a new contact and conversation will be created automatically.
POST
/inbox/send-message
Request Body
Field
Type
Required
Description
mobile_code
string
yes
Mobile country code. Must be a valid numeric country code without the plus (+) sign.
mobile
string
yes
A valid mobile phone number associated with the provided country code.
from_number
string
conditional
Optional sender number. Must match one of your connected WhatsApp numbers. Use this when your account has more than one number.
whatsapp_account_id
integer
Conditional
Optional sender account ID. If both whatsapp_account_id and from_number are provided, whatsapp_account_id is prioritized.
message
string
Conditional
Text message body. Required if no media, location, or interactive data is provided
Send an approved WhatsApp template message using destination mobile number and sender account context. If no existing conversation is found, the system creates it automatically.
POST
/inbox/send-template-message
Request Body
Field
Type
Required
Description
mobile_code
string
yes
Mobile country code. Must be a valid numeric country code without the plus (+) sign.
mobile
string
yes
A valid mobile phone number associated with the provided country code.
from_number
string
conditional
Optional sender number. Must match one of your connected WhatsApp numbers. Use this when your account has more than one number.
whatsapp_account_id
integer
conditional
Optional sender account ID. If both whatsapp_account_id and from_number are provided, whatsapp_account_id is prioritized.
template_id
integer
Yes
Approved WhatsApp template ID
header_variables
array<string>
conditional
Ordered text values for template header placeholders. Supply the values in the same order as the approved template variables.
body_variables
array<string>
conditional
Ordered text values for template body placeholders. Supply the values in the same order as the approved template variables.
Notes
Only approved WhatsApp templates can be sent. When the template contains text placeholders, pass header_variables and/or body_variables in placeholder order.
Template ID must belong to the selected sender number/account.
Template messages are typically used for business-initiated conversations.
This endpoint allows you to fetch all WhatsApp templates associated with your account.
GET
/inbox/template-list
Query Parameters
Name
Description
Required
whatsapp_account_id
Filter templates by a specific sender account ID.
No
from_number
Filter templates by a specific sender number.
No
conversation_id
Filter templates using the sender account from a conversation. Used when sending template from chat context.
No
Notes
For multi-number accounts, use one of the filter parameters above to avoid mixed template lists.
php
$payload = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_VOXIO_TIMESTAMP'] ?? '';
$signature = $_SERVER['HTTP_X_VOXIO_SIGNATURE_V2'] ?? '';
$deliveryId = $_SERVER['HTTP_X_VOXIO_DELIVERY_ID'] ?? '';
// Relay Secret is configured in Voxio Inbound Relay settings and is never sent.
$relaySecret = 'YOUR_RELAY_SECRET';
if (!ctype_digit($timestamp) || abs(time() - (int) $timestamp) > 300) {
http_response_code(401);
exit('Invalid or stale timestamp');
}
$expected = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $payload, $relaySecret);
if (!hash_equals($expected, $signature)) {
http_response_code(401);
exit('Invalid signature');
}
// Persist deliveryId if you need receiver-side idempotency across retries.
$event = $_SERVER['HTTP_X_VOXIO_EVENT'] ?? 'unknown';
$data = json_decode($payload, true);
http_response_code(200);
echo json_encode(['ok' => true, 'event' => $event]);
Omnichannel Inbound Relay
Inbound Relay forwards selected WhatsApp, Instagram, and Messenger events from Voxio to your own application endpoint. This outbound webhook delivery uses one shared destination per workspace with per-channel account selection, and requires the Inbound Relay entitlement plus API Access. External API Client ID/Secret and IP whitelist remain relevant to legacy inbound API calls, but they do not gate signed relay delivery.
WEBHOOK
Your configured Relay URL
Activation Requirements
Requirement
Description
Plan / Add-on
Your pricing plan or PAYG add-on must support Inbound Relay.
API Access
API Access must be enabled for your account.
Client ID / Secret
Optional for relay delivery. These credentials continue to authenticate calls made by your server to the legacy External API.
IP Whitelist
Optional for relay delivery. IP whitelist continues to protect calls made by your server to the legacy External API.
Relay URL
Your endpoint must be publicly reachable over HTTPS and should return HTTP 2xx quickly.
Relay Secret
Required when enabling Inbound Relay. This secret is configured in Voxio and used as the HMAC signing key for X-Voxio-Signature-V2. It is never sent as a request header.
Relay Secret vs API Client Secret
Secret
Purpose
Sent in Header?
Relay Secret
Used by Voxio to generate X-Voxio-Signature-V2 and by your server to verify the exact raw payload. This should be unique per relay endpoint.
No
Client Secret
Authenticates calls from your server to the legacy External API. It is not the webhook trust boundary. A legacy relay header may be sent temporarily for backward compatibility and can be disabled by the platform operator.
Deprecated compatibility only
Headers Sent by Voxio
Header
Description
X-Voxio-Event
Event name, for example incoming_message or message_status depending on your selected relay events.
X-Voxio-Timestamp
Unix timestamp in seconds used by Signature-V2. Reject timestamps outside a short window (for example 5 minutes) to reduce replay risk.
X-Voxio-Timestamp-Iso8601
Informational ISO-8601 timestamp provided for compatibility and logs. Signature-V2 uses X-Voxio-Timestamp, not this header.
X-Voxio-Signature-V2
Recommended HMAC SHA-256 signature over Unix timestamp + dot + exact raw body. Format: sha256=<hash>.
X-Voxio-Delivery-Id
Stable unique delivery ID. The same value is reused when Voxio retries the same queued delivery, so receivers can deduplicate safely.
X-Voxio-Signature
Legacy body-only HMAC signature kept temporarily for backward compatibility. New integrations should use Signature-V2.
X-Voxio-Client-Id
Optional legacy API credential identifier when one exists. Do not use it instead of HMAC verification.
X-Voxio-Client-Secret
Deprecated compatibility header. New receivers must not depend on it; use Relay Secret HMAC verification instead.
Signature Formula
To verify payload integrity, compute Signature-V2 on your server with the Relay Secret configured in Voxio, then compare it using a timing-safe comparison. Validate the timestamp before processing and optionally deduplicate by X-Voxio-Delivery-Id. Do not use the External API Client Secret as the HMAC key.
Return HTTP 2xx as soon as the payload has been accepted. Process slow tasks asynchronously in your own system. Voxio treats non-2xx responses or timeouts as failed delivery attempts.
Always verify Signature-V2 against the exact raw body and reject stale timestamps before trusting the payload. Keep the Relay Secret private. X-Voxio-Delivery-Id can be stored to deduplicate retries.