Swift Inbox API

Getting started

1. Sign in to Swift Inbox and open Manage → Integrate → API keys.
2. Create a key with the abilities you need (e.g. messages:send, templates:read). The plaintext token is shown once — copy it immediately.
3. Make a sanity call to GET /me to confirm the key + abilities.
4. 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:

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 message statuses update or inbound button replies occur.

Supported Event Types

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",
  "msg_id": "MSG_CUSTOM_001",
  "camp_id": "CAMP_AUGUST_01",
  "client_reference": "order-1234",
  "wa_message_id": null,
  "status": "skipped_low_probability",
  "recipient": "+919876543210",
  "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",
  "msg_id": "MSG_CUSTOM_001",
  "camp_id": "CAMP_AUGUST_01",
  "client_reference": "order-1234",
  "wa_message_id": "wamid.HBgMOTE4MTQzOTU2NDM4...",
  "status": "sent",
  "recipient": "+919876543210",
  "timestamp": "2026-08-01T08:50:00+00:00"
}

{
  "event": "msg_delivered",
  "msg_id": "MSG_CUSTOM_001",
  "camp_id": "CAMP_AUGUST_01",
  "client_reference": "order-1234",
  "wa_message_id": "wamid.HBgMOTE4MTQzOTU2NDM4...",
  "status": "delivered",
  "recipient": "+919876543210",
  "timestamp": "2026-08-01T08:50:02+00:00"
}

{
  "event": "msg_read",
  "msg_id": "MSG_CUSTOM_001",
  "camp_id": "CAMP_AUGUST_01",
  "client_reference": "order-1234",
  "wa_message_id": "wamid.HBgMOTE4MTQzOTU2NDM4...",
  "status": "read",
  "recipient": "+919876543210",
  "timestamp": "2026-08-01T08:51:15+00:00"
}

{
  "event": "msg_failed",
  "msg_id": "MSG_CUSTOM_001",
  "camp_id": "CAMP_AUGUST_01",
  "client_reference": "order-1234",
  "wa_message_id": "wamid.HBgMOTE4MTQzOTU2NDM4...",
  "status": "failed",
  "recipient": "+919876543210",
  "error_code": "131026",
  "error_title": "Undeliverable",
  "error_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"
}

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

Create a campaign

Creates a new campaign for the merchant.

Request body

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

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

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

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

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

Adjust campaign send speed

Changes the send speed (messages per second) of a running campaign.

Request body

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

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

Create a contact

Creates or upserts a contact for the merchant.

Request body

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

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

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

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

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

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

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

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

Send a template message in bulk

Send an approved template to multiple recipients in one request. Useful for broadcasts and large campaigns.

Request body

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

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

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

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

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

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

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

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

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

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

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