Developer reference
Swift Inbox API
Send WhatsApp messages, dispatch Instant Brand OTP & DLT SMS, manage templates, and embed the Swift Inbox UI inside your CRM. All
endpoints live under
https://www.swiftinbox.in/api/v1
and authenticate with a Sanctum API key (issued from Manage → Integrate → API keys).
https://www.swiftinbox.in/api/v1
- Authorization: Bearer <api-key>
- X-API-Key: <api-key>
AI Integration Assistant
Step of 5 ·
Which AI coding assistant will build this for you?
We will format prompt headers, instructions, and system task wrappers specifically for this tool.
What messaging & OTP features do you want to integrate?
Select all modules that apply. The prompt will configure service methods for each.
What is your project's technology stack?
The AI coding tool will generate idiomatically correct service wrappers, config files, and tests.
Templates & Credentials Setup
Customise your project name and specify which templates you need mapped.
Your AI Integration Prompt is Ready!
Paste this prompt directly into Antigravity or Cursor in your project repository.
Getting started
- Sign in to Swift Inbox and open Manage → Integrate → API keys.
- Create a key with the abilities you need (e.g.
messages:send,templates:read). The plaintext token is shown once — copy it immediately. - Make a sanity call to GET /me to confirm the key + abilities.
- Send your first message with POST /messages/template.
Authentication
Every request must carry an API key in either of these headers (use whichever your HTTP client prefers — they're equivalent):
Authorization: Bearer wabt_xxxxxxxxxxxxxxxxxxxxxxxx
X-API-Key: wabt_xxxxxxxxxxxxxxxxxxxxxxxx
Each key is scoped to a single merchant and a fixed set of abilities (Sanctum
scopes). Calling an endpoint with a key that's missing the required ability returns 403
forbidden. Keys can be revoked at any time from the integration panel; revocation is
immediate.
Response envelope
Every /api/v1/* response is wrapped in a consistent envelope. Branch on
code (numeric, mirrors the HTTP status) or the HTTP status itself — both will always
agree.
{
"code": 200,
"data": { … },
"message": "OK"
}
{
"code": 422,
"data": null,
"error": "validation_failed",
"message": "The body field is required.",
"errors": {
"body": ["The body field is required."]
}
}
On errors, data is always null and a top-level error slug
identifies the failure class. Field-level validation errors are surfaced as a top-level
errors map (Laravel-conventional shape). Subscription-blocked responses additionally
include a pay_now URL.
Error codes
The error slug returned in the envelope identifies the failure cleanly without parsing
the prose message. Common values across endpoints:
| HTTP | Error slug | When |
|---|---|---|
| 400 | bad_request | Malformed request (e.g. invalid JSON body). |
| 401 | unauthenticated | Missing, malformed, or revoked API key. |
| 403 | forbidden | Key is valid but missing the required ability for this endpoint. |
| 404 | not_found | The referenced resource (template id, etc.) does not exist on this merchant. |
| 409 | conflict | The mutation conflicts with current state (e.g. duplicate template name+language). |
| 422 | validation_failed | Request body / query failed validation. Includes errors map.
|
| 422 | invalid_variables | Template variables don't match the template definition. |
| 402 | subscription_blocked | Merchant's annual platform fee is unpaid. Response includes pay_now.
|
| 429 | too_many_requests | Rate limit exceeded; retry with backoff. |
| 500 | server_error | Unhandled exception inside Swift Inbox. Logged with a correlation id; safe to retry. |
A handful of domain-specific errors (SessionWindowClosedException,
WabaNotConnectedException, InsufficientWalletBalanceException) surface
their class basename as error rather than a slug — these are documented inline per
endpoint below.
Outbound Webhooks
Configure real-time webhooks under Settings → Developer & Webhook Settings to receive instant HTTP POST callbacks when inbound messages, platform or mobile outgoing messages, delivery status updates, or button replies occur.
Supported Event Types
| Event | Description |
|---|---|
| msg_received | Fired when an inbound text or media message is received. |
| msg_sent | Fired when a platform outbound message (Live Inbox, API, Campaigns, or Chatbots) is accepted by Meta for delivery. Includes origin: "platform", source, and full message content. |
| msg_outgoing_mobile | Fired when an outbound message is sent directly from the merchant's WhatsApp Business mobile app (coexistence echo). Includes origin: "mobile", source: "whatsapp_business_app", and full message content. |
| msg_delivered | Fired when Meta confirms message delivery to the recipient's phone. |
| msg_read | Fired when the recipient opens and reads the WhatsApp message. |
| msg_failed | Fired when message delivery fails due to invalid recipient or Meta error. |
| msg_skipped | Fired when a message is skipped because the recipient's WhatsApp availability probability score falls below the configured threshold. |
| button_reply | Fired when an inbound quick-reply or button response is received. |
HMAC Signature Verification
When a secret is configured, every HTTP POST request contains the X-AppRinger-Signature header
computed via HMAC SHA-256 over the raw JSON payload:
$signature = hash_hmac('sha256', $rawBody, $webhookSecret);
Sample Payloads by Event
{
"event": "msg_received",
"wa_message_id": "wamid.HBgMOTE4MTQzOTU2NDM5...",
"from": "+919876543210",
"recipient": "+919717146603",
"type": "text",
"text": "Hello, I want to order something",
"body": "Hello, I want to order something",
"media_mime": null,
"raw_payload": { ... },
"timestamp": "2026-08-01T08:52:00+00:00"
}
{
"event": "msg_skipped",
"origin": "platform",
"source": "campaign",
"msg_id": "MSG_CUSTOM_001",
"camp_id": "CAMP_AUGUST_01",
"client_reference": "order-1234",
"wa_message_id": null,
"status": "skipped_low_probability",
"recipient": "+919876543210",
"type": "template",
"template_name": "welcome_alert",
"wa_probability_score": {
"phone": "+919876543210",
"delivery_probability": 15.4,
"read_probability": 8.2,
"risk_level": "high",
"data_points": 142
},
"timestamp": "2026-08-01T08:50:00+00:00"
}
{
"event": "msg_sent",
"origin": "platform",
"source": "api",
"msg_id": "MSG_CUSTOM_001",
"camp_id": "CAMP_AUGUST_01",
"client_reference": "order-1234",
"wa_message_id": "wamid.HBgMOTE4MTQzOTU2NDM4...",
"conversation_id": 42,
"contact_id": 108,
"status": "sent",
"from": "+919717146603",
"sender": "+919717146603",
"recipient": "+919876543210",
"to": "+919876543210",
"type": "template",
"text": "Hi Aman, your order #1042 has been shipped.",
"body": "Hi Aman, your order #1042 has been shipped.",
"media_mime": null,
"media_url": null,
"template_name": "order_shipped",
"is_echo": false,
"sent_by_user_id": null,
"timestamp": "2026-08-01T08:50:00+00:00"
}
{
"event": "msg_outgoing_mobile",
"origin": "mobile",
"source": "whatsapp_business_app",
"msg_id": null,
"camp_id": null,
"client_reference": null,
"wa_message_id": "wamid.HBgMOTE4MTQzOTU2NDM5...",
"conversation_id": 42,
"contact_id": 108,
"status": "sent",
"from": "+919717146603",
"sender": "+919717146603",
"recipient": "+919876543210",
"to": "+919876543210",
"type": "text",
"text": "Hi Aman, sharing your tracking details from phone!",
"body": "Hi Aman, sharing your tracking details from phone!",
"media_mime": null,
"media_url": null,
"template_name": null,
"is_echo": true,
"sent_by_user_id": null,
"raw_payload": { ... },
"timestamp": "2026-08-01T08:52:00+00:00"
}
{
"event": "msg_delivered",
"origin": "platform",
"source": "api",
"msg_id": "MSG_CUSTOM_001",
"camp_id": "CAMP_AUGUST_01",
"client_reference": "order-1234",
"wa_message_id": "wamid.HBgMOTE4MTQzOTU2NDM4...",
"conversation_id": 42,
"contact_id": 108,
"status": "delivered",
"from": "+919717146603",
"sender": "+919717146603",
"recipient": "+919876543210",
"to": "+919876543210",
"type": "template",
"text": "Hi Aman, your order #1042 has been shipped.",
"body": "Hi Aman, your order #1042 has been shipped.",
"template_name": "order_shipped",
"is_echo": false,
"timestamp": "2026-08-01T08:50:02+00:00"
}
{
"event": "msg_read",
"origin": "mobile",
"source": "whatsapp_business_app",
"msg_id": null,
"camp_id": null,
"client_reference": null,
"wa_message_id": "wamid.HBgMOTE4MTQzOTU2NDM9...",
"conversation_id": 42,
"contact_id": 108,
"status": "read",
"from": "+919717146603",
"sender": "+919717146603",
"recipient": "+919876543210",
"to": "+919876543210",
"type": "text",
"text": "Hi Aman, sharing your tracking details from phone!",
"body": "Hi Aman, sharing your tracking details from phone!",
"is_echo": true,
"timestamp": "2026-08-01T08:51:15+00:00"
}
{
"event": "msg_failed",
"origin": "platform",
"source": "api",
"msg_id": "MSG_CUSTOM_001",
"camp_id": "CAMP_AUGUST_01",
"client_reference": "order-1234",
"wa_message_id": "wamid.HBgMOTE4MTQzOTU2NDM4...",
"conversation_id": 42,
"contact_id": 108,
"status": "failed",
"from": "+919717146603",
"sender": "+919717146603",
"recipient": "+919876543210",
"to": "+919876543210",
"type": "template",
"template_name": "order_shipped",
"is_echo": false,
"error": {
"code": "131026",
"title": "Undeliverable",
"message": "Unable to deliver message to recipient number"
},
"timestamp": "2026-08-01T08:50:05+00:00"
}
{
"event": "button_reply",
"wa_message_id": "wamid.HBgMOTE4MTQzOTU2NDM5...",
"from": "+919876543210",
"recipient": "+919717146603",
"body": "Confirm Order",
"button_reply": {
"title": "Confirm Order",
"id": "BTN_CONFIRM_123",
"payload": "BTN_CONFIRM_123"
},
"timestamp": "2026-08-01T08:52:00+00:00"
}
Sanity-check the API key
Returns the owning user, their merchant account and the abilities granted to the token. Hit this first after issuing a key to confirm credentials are wired up correctly.
curl -X GET 'https://www.swiftinbox.in/api/v1/me' \
-H 'X-API-Key: YOUR_API_KEY'
Response · 200
{
"code": 200,
"data": {
"user": {
"id": 1,
"name": "Riya Singh",
"email": "riya@acme.test",
"role": "merchant_admin"
},
"merchant": {
"id": 1,
"name": "Acme Pvt Ltd",
"slug": "acme"
},
"token": {
"name": "crm-prod",
"abilities": [
"messages:send",
"templates:read"
]
}
},
"message": "OK"
}
Errors
| HTTP | Error slug | When |
|---|---|---|
| 401 | unauthenticated | Missing, malformed, or revoked API key. |
Check the prepaid balance
Returns the current wallet balance, the configured low-balance threshold, and the per-message rates this merchant pays. Useful for surfacing a top-up nag inside your own dashboard before a send fails with InsufficientWalletBalanceException.
curl -X GET 'https://www.swiftinbox.in/api/v1/wallet/balance' \
-H 'X-API-Key: YOUR_API_KEY'
Response · 200
{
"code": 200,
"data": {
"merchant": {
"id": 1,
"slug": "acme"
},
"currency": "INR",
"balance": "1000.00",
"low_balance_threshold": "500.00",
"is_low_balance": false,
"rates": {
"session": "0.50",
"utility": "0.60",
"marketing": "1.20",
"authentication": "0.40",
"text": "0.50",
"template": "0.60"
}
},
"message": "OK"
}
Errors
| HTTP | Error slug | When |
|---|---|---|
| 401 | unauthenticated | Missing or invalid API key. |
| 403 | forbidden |
Key is missing the wallet:read ability. |
| 402 | subscription_blocked |
Annual platform fee unpaid. Response includes pay_now URL. |
Send a session (free-form) text message
Sends a plaintext WhatsApp message. Only allowed inside the 24-hour customer service window (i.e. the recipient must have messaged you in the last 24 hours). Use POST /messages/template to re-engage outside the window.
Request body
| Field | Type | Description |
|---|---|---|
|
to
required
|
string
|
E.164 recipient phone, no leading +. Required unless conversation_id is supplied. 5–32 chars. |
|
body
required
|
string
|
Message text. 1–4096 chars. |
|
conversation_id
optional
|
integer
|
Swift Inbox conversation id. When set, the recipient + phone are inferred from the conversation and to can be omitted. |
|
phone_number_id
optional
|
integer
|
Swift Inbox phone-number row id. Send from a specific number when the merchant has multiple connected numbers. Defaults to the merchant's default number. |
|
client_reference
optional
|
string
|
Your idempotency key / order id. Echoed back on the response and on every status webhook. ≤64 chars. |
|
msg_id
optional
|
string
|
Your custom message ID. Echoed back on status responses, status webhooks, and queryable via GET /messages/status/{msgId}. ≤128 chars. |
|
camp_id
optional
|
string
|
Campaign identifier for tracking campaign performance across webhooks. ≤128 chars. |
curl -X POST 'https://www.swiftinbox.in/api/v1/messages/text' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"to": "919876543210",
"body": "Hi, your order #1234 has shipped.",
"client_reference": "order-1234"
}'
Response · 202
{
"code": 202,
"data": {
"id": 42,
"status": "queued",
"client_reference": "order-1234",
"wa_message_id": null,
"billed_amount": "0.5000",
"currency": "INR"
},
"message": "Accepted"
}
status starts at queued and progresses to sent / delivered / read as Meta acknowledges. Occasionally Meta acks within the same request and you'll see sent already in this response. billed_amount is a decimal string (4 d.p.); wa_message_id is filled once Meta returns it (poll id if you need it synchronously).
Errors
| HTTP | Error slug | When |
|---|---|---|
| 401 | unauthenticated | Missing or invalid API key. |
| 403 | forbidden |
Key is missing the messages:send ability. |
| 422 | validation_failed |
Required field missing or malformed. Response includes errors: { field: [messages] }. |
| 422 | SessionWindowClosedException | Recipient has not messaged you in the last 24h. Send a template instead. |
| 402 | InsufficientWalletBalanceException |
Wallet balance is below the cost of this send. Top up at the URL in pay_now. |
| 409 | WabaNotConnectedException |
Merchant has no connected WhatsApp number. Complete the registration wizard in the Swift Inbox dashboard. |
| 402 | subscription_blocked | Annual platform fee unpaid. |
Send an approved template message
Send one of your approved templates. Use this for any first-touch / re-engagement send outside the 24-hour session window — order confirmations, shipping updates, marketing nudges, OTPs. Pass either template_id (preferred — copy it from WhatsApp settings → Templates) or the template_name+language pair.
Authentication (OTP) Templates:
For authentication templates with a Copy Code or One-Tap Autofill button, you must supply the OTP code twice in the API request: once for the message body and once for the button. You can do this easily using the simplified variables and button_variables fields, or via raw components.
Example using variables:
{
"to": "919876543210",
"template_name": "otp_verification",
"language": "en_US",
"variables": {"1": "123456"},
"button_variables": ["123456"]
}
Request body
| Field | Type | Description |
|---|---|---|
|
to
required
|
string
|
E.164 recipient phone, no leading +. Required unless conversation_id is supplied. |
|
template_id
conditional
|
integer
|
Swift Inbox template id. Required unless template_name + language are supplied. Copy it from the API id chip next to each template in the dashboard. |
|
template_name
conditional
|
string
|
Template name as registered with Meta. Required when template_id is omitted. |
|
language
conditional
|
string
|
BCP-47 language tag (e.g. en_US). Required when template_id is omitted. |
|
variables
optional
|
object
|
Positional map for {{1}}, {{2}}… in the body. We build Meta's components for you. Keys can be "1", "2"… or named (when your template defines named params). |
|
header_variables
optional
|
array
|
Values for header placeholders, in order. |
|
button_variables
optional
|
array
|
Values for URL-button or OTP/Authentication button (Copy Code / One-Tap) placeholders, in order. |
|
components
optional
|
array
|
Raw Meta-shape components array. Power-user escape hatch — wins over variables if both are sent. Use this when a header carries a media asset. |
|
conversation_id
optional
|
integer
|
Swift Inbox conversation id. Optional alternative to to. |
|
phone_number_id
optional
|
integer
|
Send from a specific number. Defaults to the merchant's default. |
|
client_reference
optional
|
string
|
Your idempotency key / order id. Echoed back on the response and on every status webhook. |
|
msg_id
optional
|
string
|
Your custom message ID. Echoed back on status responses, status webhooks, and queryable via GET /messages/status/{msgId}. ≤128 chars. |
|
camp_id
optional
|
string
|
Campaign identifier for tracking campaign performance across webhooks. ≤128 chars. |
curl -X POST 'https://www.swiftinbox.in/api/v1/messages/template' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"to": "919876543210",
"template_id": 42,
"variables": {
"1": "Riya",
"2": "A-12"
},
"client_reference": "order-1234"
}'
Response · 202
{
"code": 202,
"data": {
"id": 43,
"status": "sent",
"client_reference": "order-1234",
"wa_message_id": "wamid.HBgMOTE4MTQzOTU2NDM4FQIAERgSMUQ3...",
"billed_amount": "0.6000",
"currency": "INR",
"template_name": "order_confirmation"
},
"message": "Accepted"
}
Identical envelope to /messages/text plus a template_name field for traceability. status is usually queued; if Meta acks before this response returns you may see sent directly. wa_message_id is filled once Meta returns the WAMID.
Errors
| HTTP | Error slug | When |
|---|---|---|
| 401 | unauthenticated | Missing or invalid API key. |
| 403 | forbidden |
Key missing messages:send. |
| 404 | not_found |
Template id / name+language doesn't match any template on this merchant. Run GET /templates to list what's available. |
| 422 | validation_failed | Required field missing or malformed. |
| 422 | invalid_variables |
The variables map doesn't match what the template definition expects. |
| 402 | InsufficientWalletBalanceException | Wallet too low for the per-template rate. |
| 409 | WabaNotConnectedException |
No connected WhatsApp number on this merchant. |
| 402 | subscription_blocked | Annual platform fee unpaid. |
Send a template message in bulk
Send an approved template to multiple recipients in one request. Useful for broadcasts and large campaigns.
Request body
| Field | Type | Description |
|---|---|---|
|
template_id
optional
|
integer
|
Swift Inbox template id. |
|
template_name
optional
|
string
|
Template name as registered with Meta. |
|
language
optional
|
string
|
BCP-47 language tag. |
|
phone_number_id
optional
|
integer
|
Send from a specific number. Defaults to the merchant's default. |
|
recipients
required
|
array
|
List of recipient objects (up to 10000). |
|
recipients[].to
required
|
string
|
E.164 recipient phone. |
|
recipients[].variables
optional
|
object
|
Variables for this recipient. |
curl -X POST 'https://www.swiftinbox.in/api/v1/messages/bulk-template' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"template_id": 42,
"recipients": [
{
"to": "919876543210",
"variables": { "1": "Riya" },
"client_reference": "order-1"
}
]
}'
Response · 202
{
"message": "Bulk message queued successfully.",
"queued_count": 1
}
Errors
| HTTP | Error slug | When |
|---|---|---|
| 401 | unauthenticated | Missing or invalid API key. |
| 403 | forbidden |
Key missing messages:send ability. |
| 422 | validation_failed | Required field missing or malformed. |
Check delivery status by msg_id
Query the current delivery status of a message using your custom msg_id, Meta's wa_message_id, or client_reference. Returns delivery timestamps and error details if the send failed.
curl -X GET 'https://www.swiftinbox.in/api/v1/messages/status/MSG_12345' \
-H 'X-API-Key: YOUR_API_KEY'
Response · 200
{
"code": 200,
"data": {
"id": 42,
"msg_id": "MSG_12345",
"camp_id": "CAMP_6789",
"client_reference": "order-1234",
"wa_message_id": "wamid.HBgMOTE4MTQzOTU2NDM4...",
"recipient": "+919876543210",
"status": "delivered",
"sent_at": "2026-08-01T08:50:00+00:00",
"delivered_at": "2026-08-01T08:50:02+00:00",
"read_at": null,
"failed_at": null,
"error_code": null,
"error_title": null,
"error_message": null,
"billed_amount": "0.5000",
"currency": "INR"
},
"message": "OK"
}
Errors
| HTTP | Error slug | When |
|---|---|---|
| 401 | unauthenticated | Missing or invalid API key. |
| 403 | forbidden |
Key missing messages:send ability. |
| 404 | not_found |
Message with the given msg_id not found. |
List your WhatsApp senders
Discovery endpoint for the phone_number_id you can pass to POST /messages/text and POST /messages/template when routing through a specific sender on a multi-line merchant. Omit phone_number_id on the send endpoints and we'll use the row flagged is_default: true here.
Query parameters
| Field | Type | Description |
|---|---|---|
|
status
optional
|
string
|
Filter by phone state. One of connected (default), pending, disconnected, or all. Only connected rows are valid as phone_number_id on the send endpoints; ?status=all is for auditing why a number disappeared. |
curl -X GET 'https://www.swiftinbox.in/api/v1/phone-numbers' \
-H 'X-API-Key: YOUR_API_KEY'
Response · 200
{
"code": 200,
"data": {
"data": [
{
"id": 7,
"display_phone_number": "+91 80 5555 5555",
"verified_name": "Acme Pvt Ltd",
"status": "connected",
"is_default": true,
"quality_rating": "GREEN"
},
{
"id": 12,
"display_phone_number": "+91 80 5555 7777",
"verified_name": "Acme Support",
"status": "connected",
"is_default": false,
"quality_rating": "GREEN"
}
],
"meta": {
"count": 2,
"status": "connected"
}
},
"message": "OK"
}
Rows are sorted with the default-flagged number first, then by id — same order as the picker on the dashboard. id is the value to pass as phone_number_id on the send endpoints; display_phone_number is for showing in your own UI.
Errors
| HTTP | Error slug | When |
|---|---|---|
| 401 | unauthenticated | Missing or invalid API key. |
| 403 | forbidden |
Key is missing the messages:send ability. |
List your templates
Returns the catalog of templates registered on the merchant. By default a slim summary per row; pass ?detailed=true to also receive the full Meta-shape components + example blobs.
Tip: the API id chip next to each template in WhatsApp settings → Templates is the same id returned here — no need to hit this endpoint just to look up an id.
Query parameters
| Field | Type | Description |
|---|---|---|
|
category
optional
|
string
|
Filter by UTILITY, MARKETING, or AUTHENTICATION. |
|
status
optional
|
string
|
Filter by pending, approved, rejected, paused, disabled, or deleted. |
|
per_page
optional
|
integer
|
Page size, 1–200. Default 50. |
|
detailed
optional
|
boolean
|
Include full components + example blobs. Default false. |
curl -X GET 'https://www.swiftinbox.in/api/v1/templates?status=approved&category=UTILITY' \
-H 'X-API-Key: YOUR_API_KEY'
Response · 200
{
"code": 200,
"data": {
"data": [
{
"id": 3,
"name": "new_lead_collected",
"language": "en",
"category": "UTILITY",
"status": "approved",
"meta_template_id": "867792625617937",
"approved_at": "2026-05-20T08:34:00+00:00",
"body_preview": "🛎 New Lead Collected\nCustomer: *{{1}}*…",
"variables_count": 4,
"buttons_count": 0,
"has_header": false,
"has_footer": false
}
],
"meta": {
"page": 1,
"per_page": 50,
"total": 1,
"total_pages": 1
}
},
"message": "OK"
}
Errors
| HTTP | Error slug | When |
|---|---|---|
| 401 | unauthenticated | Missing or invalid API key. |
| 403 | forbidden |
Key missing templates:read. |
| 422 | validation_failed |
Unknown category or status value, or per_page out of range. |
Register a new template for Meta review
Submits a draft template to Meta for review. Lands locally in pending status; Meta typically returns an approval within minutes and the row auto-flips to approved via webhook. Once approved, send it with POST /messages/template.
Request body
| Field | Type | Description |
|---|---|---|
|
name
required
|
string
|
Snake_case template id, max 128 chars. Must match /^[a-z0-9_]+$/i. Must be unique per language. |
|
language
required
|
string
|
BCP-47 language tag, e.g. en_US, hi, mr. |
|
category
required
|
string
|
One of UTILITY (transactional), MARKETING (promotional), AUTHENTICATION (OTP). |
|
components
required
|
array
|
Meta-shape components array. At minimum a BODY component with text. Use {{1}}, {{2}}… for placeholders. |
|
example
optional
|
object
|
Sample values Meta uses while reviewing. Required for templates with placeholders, e.g. { "body_text": [["Riya", "A-12"]] }. |
curl -X POST 'https://www.swiftinbox.in/api/v1/templates' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"name": "order_confirmation",
"language": "en_US",
"category": "UTILITY",
"components": [
{ "type": "BODY", "text": "Hi {{1}}, your order {{2}} is confirmed." }
],
"example": { "body_text": [["Riya", "A-12"]] }
}'
Response · 201
{
"code": 201,
"data": {
"id": 5,
"name": "order_confirmation",
"language": "en_US",
"category": "UTILITY",
"status": "pending",
"meta_template_id": null,
"approved_at": null,
"components": [
{
"type": "BODY",
"text": "Hi {{1}}, your order {{2}} is confirmed."
}
],
"example": {
"body_text": [
[
"Riya",
"A-12"
]
]
}
},
"message": "Created"
}
Errors
| HTTP | Error slug | When |
|---|---|---|
| 401 | unauthenticated | Missing or invalid API key. |
| 403 | forbidden |
Key missing templates:write. |
| 422 | validation_failed | Malformed components, missing example for a placeholder template, etc. |
| 409 | conflict |
A template with the same name+language already exists on this merchant. |
Retrieve a template and generated integration snippets
Returns full template details (including components, example values, and approval status) along with ready-to-paste Laravel config/whatsapp.php entries and PHP dispatch code generated for this template.
curl -X GET 'https://www.swiftinbox.in/api/v1/templates/5' \
-H 'X-API-Key: YOUR_API_KEY'
Response · 200
{
"code": 200,
"data": {
"id": 5,
"name": "order_confirmation",
"language": "en_US",
"category": "UTILITY",
"status": "approved",
"meta_template_id": "1029384756",
"components": [
{
"type": "BODY",
"text": "Hi {{1}}, your order {{2}} is confirmed."
}
],
"integration": {
"template_name": "order_confirmation",
"category": "UTILITY",
"config_entry": "'order_confirmation' => [ ... ]",
"php_dispatch_snippet": "WhatsApp::sendTemplate(...)"
}
},
"message": "OK"
}
Errors
| HTTP | Error slug | When |
|---|---|---|
| 401 | unauthenticated | Missing or invalid API key. |
| 403 | forbidden |
Key missing templates:read. |
| 404 | not_found | Template not found for this merchant. |
Update an existing template for Meta review
Submits updated body text, header, footer, or buttons to Meta Graph API for review and resets local status to pending. Accepts either flat fields (body, header, buttons) or raw Meta components array.
Request body
| Field | Type | Description |
|---|---|---|
|
body
optional
|
string
|
Updated body text. Use {{1}}, {{2}} for variables. |
|
category
optional
|
string
|
One of UTILITY, MARKETING, AUTHENTICATION. |
|
sample_values
optional
|
array
|
Sample values for placeholders in body text. |
|
header
optional
|
string
|
Header text (or use header_type for media headers). |
|
footer
optional
|
string
|
Optional footer text, max 60 chars. |
|
button_type
optional
|
string
|
One of QUICK_REPLY, URL, NONE. |
|
components
optional
|
array
|
Optional raw Meta component array (overrides flat fields). |
curl -X PUT 'https://www.swiftinbox.in/api/v1/templates/5' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"category": "UTILITY",
"body": "Hi {{1}}, your order {{2}} has been dispatched via {{3}}.",
"sample_values": ["Riya", "A-12", "FedEx Express"],
"footer": "Thank you for shopping with us",
"button_type": "URL",
"button_text": "Track Shipment",
"button_url": "https://track.example.com/{{1}}",
"button_url_sample": "TRK987654"
}'
Response · 200
{
"code": 200,
"data": {
"id": 5,
"name": "order_confirmation",
"language": "en_US",
"category": "UTILITY",
"status": "pending",
"meta_template_id": "1029384756",
"components": [
{
"type": "BODY",
"text": "Hi {{1}}, your order {{2}} has been dispatched via {{3}}."
},
{
"type": "FOOTER",
"text": "Thank you for shopping with us"
}
]
},
"message": "OK"
}
Errors
| HTTP | Error slug | When |
|---|---|---|
| 401 | unauthenticated | Missing or invalid API key. |
| 403 | forbidden |
Key missing templates:write. |
| 404 | not_found | Template not found for this merchant. |
| 422 | meta_error | Meta Graph API rejected the update (e.g. edit rate limit exceeded or invalid format). |
Delete a template
Deletes a template. Note that this only removes the template from Swift Inbox; you must still delete it in the Meta Business Manager.
curl -X DELETE 'https://www.swiftinbox.in/api/v1/templates/42' \
-H 'X-API-Key: YOUR_API_KEY'
Response · 200
{
"message": "Template deleted successfully."
}
Errors
| HTTP | Error slug | When |
|---|---|---|
| 401 | unauthenticated | Missing or invalid API key. |
| 403 | forbidden |
Key missing templates:write. |
| 404 | not_found | Template not found for this merchant. |
Instant Brand OTP (Zero-DLT Service)
Dispatch high-priority brand OTPs with zero telecom onboarding delay. Built for startups and growing businesses who need instant branded OTPs without registering an Entity or waiting weeks for DLT template approval.
The platform routes your OTP through our pre-approved generic DLT template (e.g. 1707174000000000000) and dynamically injects your registered brand_name (whitelisted in SMS Engine settings).
Android 1-Tap Autofill: Pass app_hash (your app's 11-character hash from Android SMS Retriever API) to allow the recipient's phone to read and autofill the OTP instantly without requesting SMS permissions.
Request body
| Field | Type | Description |
|---|---|---|
|
to
required
|
string
|
Destination mobile number with country code (e.g. +919876543210 or 10-digit 9876543210). |
|
otp
required
|
string
|
The OTP / verification PIN code (3–10 digits or characters, e.g. 492018). |
|
brand_name
optional
|
string
|
Your registered brand name (must be whitelisted in SMS Engine settings, max 32 chars). If omitted, uses merchant's primary brand. |
|
purpose
optional
|
string
|
Authentication context (e.g. verification, login, password_reset). Defaults to verification. |
|
validity_minutes
optional
|
integer
|
OTP validity duration in minutes (1–60). Defaults to 10. |
|
app_hash
optional
|
string
|
11-character Android SMS Retriever API hash string (e.g. FA+9qCX9VSu) for zero-permission 1-tap OTP auto-read. |
curl -X POST 'https://www.swiftinbox.in/api/v1/sms/otp' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"to": "+919876543210",
"otp": "492018",
"brand_name": "Acme",
"purpose": "login",
"validity_minutes": 10,
"app_hash": "FA+9qCX9VSu"
}'
Response · 200
{
"code": 200,
"data": {
"id": 1042,
"clientsmsid": "sms_672b1234abcd",
"to": "+919876543210",
"brand_name": "Acme",
"sender_id": "SWFBX",
"body": "Your Acme verification code is 492018. Valid for 10 mins. Do not share this OTP with anyone. FA+9qCX9VSu",
"segments": 1,
"cost": "0.22",
"currency": "INR",
"status": "sent",
"gateway_message_id": "gw_987654321",
"sent_at": "2026-11-09T07:30:00+00:00"
},
"message": "Instant Brand OTP dispatched successfully."
}
Debits from your prepaid SMS wallet balance using the platform Instant Brand OTP rate. status begins as sent or submitted and updates to delivered upon telecom carrier DLR receipt.
Errors
| HTTP | Error slug | When |
|---|---|---|
| 401 | unauthenticated | Missing, malformed, or revoked API key. |
| 402 | insufficient_balance | Prepaid wallet balance is below the cost of this OTP dispatch. |
| 403 | feature_disabled | SMS Engine is not enabled on this merchant account. |
| 403 | forbidden |
Key is missing the sms:send or messages:send ability. |
| 422 | unprocessable | Brand name not whitelisted, brand phishing keyword detected, or invalid phone/OTP length. |
Send an SMS (DLT Transactional & Promotional)
Dispatch a single outbound SMS message. If using your own enterprise telecom DLT registration, provide your registered 6-character Header (sender_id) and DLT Content Template ID (dlt_template_id). If omitted, routes via platform default.
The engine automatically calculates segments based on standard telecom character encodings: GSM 7-bit (160 characters per segment, 153 for concatenated parts) and Unicode / regional languages (70 characters per segment, 67 for concatenated parts).
Request body
| Field | Type | Description |
|---|---|---|
|
to
required
|
string
|
Recipient phone number in E.164 format (e.g. +919876543210 or 9876543210). |
|
message
required
|
string
|
Message text content (1–1000 characters). Automatically segment-calculated. |
|
sender_id
optional
|
string
|
6-character registered DLT Sender ID / Header (e.g. SWFBX). Max 16 chars. |
|
dlt_template_id
optional
|
string
|
19-digit registered DLT Content Template ID approved on the telecom portal. |
|
entity_id
optional
|
string
|
Principal Entity ID (PE ID) registered with your telecom operator. |
curl -X POST 'https://www.swiftinbox.in/api/v1/sms/send' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"to": "+919876543210",
"message": "Your order #1042 has shipped via BlueDart. Track: https://trk.in/1042",
"sender_id": "SWFBX",
"dlt_template_id": "1707161234567890123"
}'
Response · 200
{
"code": 200,
"data": {
"id": 1043,
"clientsmsid": "sms_672b1235bcde",
"to": "+919876543210",
"sender_id": "SWFBX",
"segments": 1,
"is_unicode": false,
"cost": "0.25",
"currency": "INR",
"status": "sent",
"gateway_message_id": "gw_987654322",
"sent_at": "2026-11-09T07:31:00+00:00"
},
"message": "SMS dispatched successfully."
}
cost is computed as segments × per_segment_rate and debited from the merchant prepaid wallet upon dispatch.
Errors
| HTTP | Error slug | When |
|---|---|---|
| 401 | unauthenticated | Missing, malformed, or revoked API key. |
| 402 | insufficient_balance | Wallet balance is below the cost of this SMS dispatch. |
| 403 | feature_disabled | SMS Engine is not enabled on this merchant account. |
| 403 | forbidden |
Key is missing the sms:send or messages:send ability. |
| 422 | unprocessable | Validation failed or carrier rejected message (e.g. DLT template mismatch). |
Dispatch Bulk SMS (up to 500)
Send up to 500 SMS messages in a single atomic batch payload with individual recipient, message text, and DLT routing configuration.
Request body
| Field | Type | Description |
|---|---|---|
|
messages
required
|
array
|
Array of 1 to 500 message items. |
|
messages.*.to
required
|
string
|
Recipient phone number. |
|
messages.*.message
required
|
string
|
SMS message text (1–1000 characters). |
|
messages.*.sender_id
optional
|
string
|
6-character DLT Header / Sender ID. |
|
messages.*.dlt_template_id
optional
|
string
|
DLT Content Template ID. |
|
messages.*.entity_id
optional
|
string
|
DLT Principal Entity ID (PE ID). |
curl -X POST 'https://www.swiftinbox.in/api/v1/sms/bulk' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"messages": [
{
"to": "+919876543210",
"message": "Hi John, flash sale starts now! Get 20% off with code FLASH20",
"sender_id": "SWFBX",
"dlt_template_id": "1707161234567890123"
},
{
"to": "+919876543211",
"message": "Hi Sara, flash sale starts now! Get 20% off with code FLASH20",
"sender_id": "SWFBX",
"dlt_template_id": "1707161234567890123"
}
]
}'
Response · 200
{
"code": 200,
"data": {
"total": 2,
"dispatched": 2,
"failed": 0,
"items": [
{
"id": 1044,
"clientsmsid": "sms_672b1236cdef",
"to": "+919876543210",
"status": "sent",
"segments": 1,
"cost": "0.25",
"error_code": null,
"error_message": null,
"gateway_message_id": "gw_987654323"
},
{
"id": 1045,
"clientsmsid": "sms_672b1237defa",
"to": "+919876543211",
"status": "sent",
"segments": 1,
"cost": "0.25",
"error_code": null,
"error_message": null,
"gateway_message_id": "gw_987654324"
}
]
},
"message": "Processed 2 dispatched, 0 failed."
}
Errors
| HTTP | Error slug | When |
|---|---|---|
| 401 | unauthenticated | Missing, malformed, or revoked API key. |
| 403 | feature_disabled | SMS Engine is not enabled on this merchant account. |
| 403 | forbidden |
Key is missing the sms:send or messages:send ability. |
| 422 | unprocessable | Validation failed (e.g. empty array or exceeds 500 items). |
Get SMS delivery status
Retrieve live delivery status, segment counts, wallet cost, telecom gateway ID, and delivery receipt timestamps for an SMS message.
Pass either the numeric internal id (e.g. 1042) or the client tracking string (e.g. sms_672b1234abcd) in the path.
Query parameters
| Field | Type | Description |
|---|---|---|
|
id
required
|
string
|
Path parameter: Internal SMS ID (1042) or Client UUID (sms_672b1234abcd). |
curl -X GET 'https://www.swiftinbox.in/api/v1/sms/sms_672b1234abcd' \
-H 'X-API-Key: YOUR_API_KEY'
Response · 200
{
"code": 200,
"data": {
"id": 1042,
"clientsmsid": "sms_672b1234abcd",
"to": "+919876543210",
"sender_id": "SWFBX",
"segments": 1,
"is_unicode": false,
"status": "delivered",
"gateway": "satzilio",
"gateway_message_id": "gw_987654321",
"cost": "0.22",
"error_code": null,
"error_message": null,
"sent_at": "2026-11-09T07:30:00+00:00",
"delivered_at": "2026-11-09T07:30:04+00:00",
"failed_at": null
},
"message": "OK"
}
Status values: pending → sent → delivered or failed. When status is failed, error_code and error_message detail the carrier failure reason.
Errors
| HTTP | Error slug | When |
|---|---|---|
| 401 | unauthenticated | Missing, malformed, or revoked API key. |
| 403 | forbidden |
Key is missing the sms:send or messages:send ability. |
| 404 | not_found | SMS record not found for this merchant. |
List campaigns
Returns a paginated list of campaigns for the merchant.
curl -X GET 'https://www.swiftinbox.in/api/v1/campaigns' \
-H 'X-API-Key: YOUR_API_KEY'
Response · 200
{
"code": 200,
"data": [],
"message": "OK"
}
Errors
| HTTP | Error slug | When |
|---|---|---|
| 401 | unauthenticated | Missing or invalid API key. |
Create a campaign
Creates a new campaign for the merchant.
Request body
| Field | Type | Description |
|---|---|---|
|
name
required
|
string
|
Campaign name. |
|
template_id
required
|
integer
|
Template to use. |
curl -X POST 'https://www.swiftinbox.in/api/v1/campaigns' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"name": "August Promo", "template_id": 42}'
Response · 201
{
"code": 201,
"data": {
"uuid": "cam_abc123"
},
"message": "Created"
}
Errors
| HTTP | Error slug | When |
|---|---|---|
| 401 | unauthenticated | Missing or invalid API key. |
| 422 | validation_failed | Required fields missing or invalid. |
Get campaign details
Returns details of a specific campaign.
curl -X GET 'https://www.swiftinbox.in/api/v1/campaigns/cam_abc123' \
-H 'X-API-Key: YOUR_API_KEY'
Response · 200
{
"code": 200,
"data": {
"uuid": "cam_abc123",
"status": "draft"
},
"message": "OK"
}
Errors
| HTTP | Error slug | When |
|---|---|---|
| 401 | unauthenticated | Missing or invalid API key. |
| 404 | not_found | Campaign not found. |
Launch a campaign
Starts sending a campaign.
curl -X POST 'https://www.swiftinbox.in/api/v1/campaigns/cam_abc123/launch' \
-H 'X-API-Key: YOUR_API_KEY'
Response · 200
{
"code": 200,
"data": {
"status": "running"
},
"message": "Launched"
}
Errors
| HTTP | Error slug | When |
|---|---|---|
| 401 | unauthenticated | Missing or invalid API key. |
| 409 | conflict | Campaign is not in a launchable state. |
Pause a running campaign
Pauses a running campaign. Resume later with the resume endpoint.
curl -X POST 'https://www.swiftinbox.in/api/v1/campaigns/cam_abc123/pause' \
-H 'X-API-Key: YOUR_API_KEY'
Response · 200
{
"code": 200,
"data": {
"status": "paused"
},
"message": "Paused"
}
Errors
| HTTP | Error slug | When |
|---|---|---|
| 401 | unauthenticated | Missing or invalid API key. |
| 409 | conflict | Campaign is not running. |
Resume a paused campaign
Resumes a previously paused campaign.
curl -X POST 'https://www.swiftinbox.in/api/v1/campaigns/cam_abc123/resume' \
-H 'X-API-Key: YOUR_API_KEY'
Response · 200
{
"code": 200,
"data": {
"status": "running"
},
"message": "Resumed"
}
Errors
| HTTP | Error slug | When |
|---|---|---|
| 401 | unauthenticated | Missing or invalid API key. |
| 409 | conflict | Campaign is not paused. |
Adjust campaign send speed
Changes the send speed (messages per second) of a running campaign.
Request body
| Field | Type | Description |
|---|---|---|
|
speed
required
|
integer
|
Messages per second. |
curl -X POST 'https://www.swiftinbox.in/api/v1/campaigns/cam_abc123/speed' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"speed": 10}'
Response · 200
{
"code": 200,
"data": {
"speed": 10
},
"message": "Speed updated"
}
Errors
| HTTP | Error slug | When |
|---|---|---|
| 401 | unauthenticated | Missing or invalid API key. |
| 422 | validation_failed | Speed value out of allowed range. |
List contacts
Returns a paginated list of contacts for the merchant.
curl -X GET 'https://www.swiftinbox.in/api/v1/contacts' \
-H 'X-API-Key: YOUR_API_KEY'
Response · 200
{
"code": 200,
"data": [],
"message": "OK"
}
Errors
| HTTP | Error slug | When |
|---|---|---|
| 401 | unauthenticated | Missing or invalid API key. |
Create a contact
Creates or upserts a contact for the merchant.
Request body
| Field | Type | Description |
|---|---|---|
|
phone
required
|
string
|
E.164 phone number. |
|
name
optional
|
string
|
Contact display name. |
curl -X POST 'https://www.swiftinbox.in/api/v1/contacts' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"phone": "919876543210", "name": "Riya"}'
Response · 201
{
"code": 201,
"data": {
"id": 1,
"phone": "+919876543210"
},
"message": "Created"
}
Errors
| HTTP | Error slug | When |
|---|---|---|
| 401 | unauthenticated | Missing or invalid API key. |
| 422 | validation_failed | Required fields missing or invalid. |
Get contact details
Returns details of a specific contact.
curl -X GET 'https://www.swiftinbox.in/api/v1/contacts/42' \
-H 'X-API-Key: YOUR_API_KEY'
Response · 200
{
"code": 200,
"data": {
"id": 42,
"phone": "+919876543210"
},
"message": "OK"
}
Errors
| HTTP | Error slug | When |
|---|---|---|
| 401 | unauthenticated | Missing or invalid API key. |
| 404 | not_found | Contact not found. |
Mint a JWT for embedded SSO (BETA)
BETA / Testing Feature: Server-to-server mint of a short-lived JWT for Iframe SSO embedding inside partner CRMs. Use the returned embed_url as an iframe src to drop the Swift Inbox UI inside your CRM with the targeted user already signed in. With auto_provision: true, the user is created on-the-fly if they don't exist yet.
Request body
| Field | Type | Description |
|---|---|---|
|
email
optional
|
string
|
Target user's email. Required unless user_id is supplied. |
|
user_id
optional
|
integer
|
Swift Inbox user id. Required unless email is supplied. |
|
ttl_seconds
optional
|
integer
|
Token lifetime, 60–86400 (24h). Default 300 (5 min). |
|
redirect_to
optional
|
string
|
Path inside Swift Inbox to land on. Must start with /. Defaults to /inbox. |
|
auto_provision
optional
|
boolean
|
Create the user if not found. Requires email + name + role. |
|
role
optional
|
string
|
When auto-provisioning: agent or manager. |
|
name
optional
|
string
|
When auto-provisioning: display name, max 120 chars. |
|
features
optional
|
array
|
When auto-provisioning: subset of ["inbox", "tasks"] to grant. |
curl -X POST 'https://www.swiftinbox.in/api/v1/iframe-tokens' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"email": "agent@acme.com",
"ttl_seconds": 300,
"redirect_to": "/inbox",
"auto_provision": true,
"role": "agent",
"features": ["inbox", "tasks"]
}'
Response · 200
{
"code": 200,
"data": {
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOjIsImV4cCI6MTczMjAwMDAwMH0.signature",
"expires_at": "2026-05-20T14:00:00+00:00",
"embed_url": "https://app.example.com/embed?token=eyJ0eXAi...",
"ttl_seconds": 300,
"user": {
"id": 2,
"email": "agent@acme.com",
"name": "Agent Two",
"role": "agent"
},
"provisioned": false
},
"message": "OK"
}
Errors
| HTTP | Error slug | When |
|---|---|---|
| 401 | unauthenticated | Missing or invalid API key. |
| 403 | forbidden |
Key missing iframe:mint or not merchant-scoped. |
| 404 | not_found |
User not found. Pass auto_provision: true + name + role to create them on the fly. |
| 422 | provision_failed |
Auto-provision validation failed. Response includes errors map. |
| 422 | user_inactive | Target user is disabled. |
| 422 | merchant_missing | API key's merchant row is missing (rare; usually a deleted merchant). |