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",
    "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:

Reason	Meaning
`within_window`	An inbound was received in the last 24 hours — free-form replies are allowed.
`window_expired`	The last inbound is older than 24 hours — template-only.
`no_inbound_history`	No 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"
  }
}

Status	When
`200`	Every recipient succeeded.
`207`	At least one recipient failed (partial or all-failed) — always inspect the body.
`402`	Org balance can’t cover the broadcast floor.
`429`	The recipient count would breach the WABA’s daily `messaging_limit_tier` cap.
`500`	Bulk 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

Send images, video, documents, audio, and stickers over WhatsApp. Each media type has its own size limit, set and enforced by WhatsApp (Meta) at the Graph API — there is no single blanket ceiling. Orbit forwards your media to WhatsApp, so keep each file within the limit for its type or WhatsApp rejects the send.

Type	Max Size	Formats
Image	5 MB	JPEG, PNG
Video	16 MB	MP4, 3GPP
Audio	16 MB	AAC, MP3 (MPEG), MP4, AMR, OGG
Document	100 MB	PDF, DOC, DOCX, PPT, PPTX, XLS, XLSX, TXT
Sticker	100 KB	WebP

Limits are per type, not shared: a 90 MB PDF is accepted as a document but rejected if the same file is sent as an image, and a sticker must stay under 100 KB. Check each file against the limit for its media type before sending.

Platform WABA credentials (operators)

Most tenants connect their own WhatsApp Business Account through the dashboard Embedded Signup flow, and Orbit uses that tenant’s stored credentials at send time. The variables below configure Orbit’s own platform-owned WABA — the shared fallback / send path used for the unverified test account, platform-initiated template management, and WhatsApp Calling registration. Set all three in Secret Manager (or .env for local dev). They are optional at boot: when DEVOTEL_WHATSAPP_ACCESS_TOKEN is set, messaging-bootstrap.ts registers one platform-wide WhatsApp provider; when it is unset, only per-tenant connections resolve at send time.

Variable	Required	Purpose
`DEVOTEL_WHATSAPP_ACCESS_TOKEN`	To enable the platform path	Graph API access token for the platform-owned WABA. Presence of this token is what registers the platform WhatsApp provider at boot.
`DEVOTEL_WHATSAPP_PHONE_NUMBER_ID`	With the access token	Phone-number id of the platform WABA’s sender. Used as the `from` for platform / test-account sends.
`DEVOTEL_WHATSAPP_BUSINESS_ACCOUNT_ID`	With the access token	The platform WABA id. Used to scope template management and to match inbound webhooks routed to the platform account.

Inbound webhook HMAC for WhatsApp still uses the shared DEVOTEL_META_APP_SECRET / DEVOTEL_META_VERIFY_TOKEN regardless of whether the platform credentials are set. The dashboard’s WhatsApp Embedded Signup card and the Meta Ads channel card load Meta’s JS SDK in the browser, so they need a Meta App ID and an Embedded Signup configuration ID available on the client. Two NEXT_PUBLIC_* variables carry those values. Because they are NEXT_PUBLIC_*, they are baked into the dashboard when it is built — changing them requires rebuilding the dashboard, not just updating a server environment variable. Both are optional. Leave them unset for standard production deployments; the defaults connect tenants to Orbit’s production Meta app.

Variable	Required	Purpose
`NEXT_PUBLIC_META_APP_ID`	Optional	Meta App ID used by every Meta channel card (WhatsApp Embedded Signup, Instagram, Messenger, Meta Ads) to initialise the Facebook JS SDK. When unset, the SDK loader and the Meta Ads card fall back to Orbit’s built-in production Meta app. In the WhatsApp Embedded Signup card the effective app ID is normally taken from the server-side WhatsApp status (`DEVOTEL_META_APP_ID`); this build-time value only backs the in-tab OAuth fallback before that status resolves.
`NEXT_PUBLIC_META_CONFIG_ID`	Optional	Embedded Signup configuration ID for the WhatsApp Embedded Signup flow. Unlike the App ID, it has no built-in production fallback: the effective value is normally taken from the server-side WhatsApp status, and this build-time value only backs the brief window before that status resolves. When both the server value and this variable are empty, the Connect action surfaces a misconfiguration message instead of opening Meta’s signup dialog with an empty config.

Override both when you build the dashboard against a non-production Meta app — a staging / preview environment pointed at a test Meta app and Embedded Signup config, or a white-label deployment that runs its own Meta app rather than Orbit’s. Provide both as build-time variables when you build the dashboard, and set the matching server-side DEVOTEL_META_APP_ID so the runtime and build-time values agree.

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).

Getting Started

Channels

AI Agents

Flows

Numbers & Verify

Concepts

Billing

Webhooks

Compliance

Legal

Changelog

WhatsApp

Send a Template Message

Send a Session Message

Check the 24-Hour Window

Response

Send a Broadcast

Response

Features

Media Support

Platform WABA credentials (operators)

Template Management

​WhatsApp

​Send a Template Message

​Send a Session Message

​Check the 24-Hour Window

​Response

​Send a Broadcast

​Response

​Features

​Media Support

​Platform WABA credentials (operators)

​Dashboard Embedded Signup (build-time client config)

​Template Management

WhatsApp

Send a Template Message

Send a Session Message

Check the 24-Hour Window

Response

Send a Broadcast

Response

Features

Media Support

Platform WABA credentials (operators)

Dashboard Embedded Signup (build-time client config)

Template Management