Skip to main content

​
WhatsApp

Reach 2+ billion WhatsApp users through Orbit’s WhatsApp Business API integration. Send template messages, start interactive sessions, and handle rich media — all through a single API.

​
Send a Template Message

WhatsApp requires pre-approved templates for business-initiated conversations. 
curl -X POST https://api.orbit.devotel.io/api/v1/messages/whatsapp \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155552671",
    "type": "template",
    "template": {
      "name": "order_confirmation",
      "language": { "code": "en" },
      "components": [
        {
          "type": "body",
          "parameters": [
            { "type": "text", "text": "ORD-12345" }
          ]
        }
      ]
    }
  }'

​
Send a Session Message

Once a user messages you, a 24-hour session window opens for free-form replies. Use the window-status check to confirm the window is still open before sending. 
curl -X POST https://api.orbit.devotel.io/api/v1/messages/whatsapp \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155552671",
    "type": "text",
    "body": "Thanks for reaching out! How can we help?"
  }'

​
Check the 24-Hour Window

Before composing a free-form (session) message, call the window-status endpoint to confirm the recipient is still inside Meta’s 24-hour re-engagement window. The send pipeline enforces the same check, but this pre-flight lets you gate the UI (force template-only when the window has closed) and avoid a wasted send attempt. 
curl "https://api.orbit.devotel.io/api/v1/messages/whatsapp/window-status?to=+14155552671&from=+18005551234" \
  -H "X-API-Key: dv_live_sk_..."
  • to (required) — the contact’s E.164 number.
  • from (optional) — the WABA number that will be the sender. When omitted, the check spans any of your WABA numbers; when supplied it is scoped to that sender pair (matching the send-time gate).

​
Response

{
  "data": {
    "within_window": true,
    "last_inbound_at": "2026-03-08T09:12:00Z",
    "hours_since_last_inbound": 3,
    "reason": "within_window"
  },
  "meta": {
    "request_id": "req_xyz789",
    "timestamp": "2026-03-08T12:12:00Z"
  }
}
reason is one of:
ReasonMeaning
within_windowAn inbound was received in the last 24 hours — free-form replies are allowed.
window_expiredThe last inbound is older than 24 hours — template-only.
no_inbound_historyNo inbound has ever been received from this contact — last_inbound_at and hours_since_last_inbound are null.
When the window is closed, within_window is false and you must fall back to an approved template message.

​
Send a Broadcast

Fan a single approved template out to up to 256 recipients in one operation (Meta’s documented broadcast-list cap). Each recipient receives a normal 1:1 conversation — there is no shared thread, so per-recipient STOP / opt-out handling is preserved. The endpoint is persist-then-attempt: every recipient is pre-inserted as a pending row in one transaction before the per-recipient send pipeline runs, so a pre-create rejection (template not approved, parameter-count mismatch, 24-hour-window block, fraud guard, quota, sender validation) flips that row to failed rather than throwing without persisting a record. 
curl -X POST https://api.orbit.devotel.io/api/v1/messages/whatsapp/broadcast \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "template_name": "order_confirmation",
    "template_language": "en",
    "from": "+18005551234",
    "template_params": { "1": "Acme Co" },
    "recipients": [
      { "to": "+14155552671", "template_params": { "1": "Alice" } },
      { "to": "+14155552672" }
    ]
  }'
  • recipients (required) — 1–256 entries, each with a to (E.164) and optional per-row template_params / metadata. Per-row template_params override the batch-level shared template_params. Duplicate numbers in one request are rejected (422).
  • template_name (required) — an approved WhatsApp template.
  • template_language, from, template_params, scheduled_at, webhook_url, metadata (optional) — shared across the batch. With scheduled_at set, every recipient lands as scheduled for the worker queue.

​
Response

Returns a per-recipient result array plus a summary. Inspect summary.failed and each results[].status — the HTTP status code signals whether to look at the body. 
{
  "data": {
    "batch_id": "batch_abc123",
    "results": [
      { "message_id": "msg_1", "to": "+14155552671", "status": "sent" },
      {
        "message_id": "msg_2",
        "to": "+14155552672",
        "status": "failed",
        "error_code": "TEMPLATE_NOT_APPROVED",
        "error_message": "Template is not approved"
      }
    ],
    "summary": { "total": 2, "succeeded": 1, "failed": 1, "scheduled": 0 }
  },
  "meta": {
    "request_id": "req_xyz789",
    "timestamp": "2026-03-08T00:00:00Z"
  }
}
StatusWhen
200Every recipient succeeded.
207At least one recipient failed (partial or all-failed) — always inspect the body.
402Org balance can’t cover the broadcast floor.
429The recipient count would breach the WABA’s daily messaging_limit_tier cap.
500Bulk pre-insert failed — no recipients were processed.
Broadcasts are rate-limited to 30 requests/minute per tenant. Larger or recurring sends belong in the campaigns module.

​
Features

  • Template messages — pre-approved message templates for outbound notifications
  • Session messaging — free-form replies within the 24-hour conversation window, with a pre-flight window-status check
  • Broadcast lists — fan one approved template out to up to 256 recipients with per-recipient results
  • Rich media — images, videos, documents, audio, stickers, and location sharing
  • Interactive messages — buttons, list pickers, and quick replies
  • Read receipts — know when messages are delivered and read
  • Catalog & product messages — share product listings directly in chat

​
Media Support

TypeMax SizeFormats
Image5 MBJPEG, PNG
Video16 MBMP4, 3GPP
Document100 MBPDF, DOC, XLSX, etc.
Audio16 MBAAC, MP3, OGG

​
Template Management

Manage templates through the Orbit dashboard under Channels > WhatsApp > Templates, or via the API: 
curl https://api.orbit.devotel.io/api/v1/whatsapp/templates \
  -H "X-API-Key: dv_live_sk_..."
Templates go through Meta’s approval process (typically 1–24 hours).