> ## Documentation Index > Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt > Use this file to discover all available pages before exploring further. # WhatsApp API > Manage WhatsApp Business connections, business profile, catalogs, Flows, contacts, calls, and block lists. Sending messages goes through the unified Messaging API. # WhatsApp API Manage everything that surrounds WhatsApp Business messaging — your WABA connection, business profile, product catalogs, Flows, voice calls, and block lists. Sending messages themselves uses the unified [Messaging API](/api-reference/endpoints/messaging) (`POST /api/v1/messages/whatsapp`); this surface is for the configuration that backs those sends. **Base path:** `/api/v1/whatsapp` **Authentication:** API key (`X-API-Key`) or session JWT. ## Connections Each Orbit organization can attach one or more WABA phone numbers. Connections are managed via Meta's Embedded Signup; the `connect` endpoint exchanges the resulting code for a long-lived token. | Method | Path | Purpose | | -------- | ------------------------------------------------------ | ------------------------------------------ | | `POST` | `/api/v1/whatsapp/connect` | Exchange Embedded Signup code → connection | | `GET` | `/api/v1/whatsapp/status` | Connection summary for the calling org | | `GET` | `/api/v1/whatsapp/connections` | List all connected phone numbers | | `PUT` | `/api/v1/whatsapp/connections/{phoneNumberId}/default` | Mark one connection as default | | `PATCH` | `/api/v1/whatsapp/connections/{phoneNumberId}` | Update display name or routing | | `DELETE` | `/api/v1/whatsapp/connections/{phoneNumberId}` | Unlink a single number | | `DELETE` | `/api/v1/whatsapp/disconnect` | Remove the entire WABA connection | ## Business profile The about line, address, vertical, websites, and profile photo that appear in the customer's WhatsApp client. | Method | Path | Purpose | | ------ | ----------------------------------- | ------------------------------------------- | | `GET` | `/api/v1/whatsapp/business-profile` | Read the current profile | | `PUT` | `/api/v1/whatsapp/business-profile` | Update the profile (subject to Meta review) | ## Catalogs & products Used by template messages and the in-WhatsApp shopping experience. | Method | Path | Purpose | | -------- | --------------------------------------------------- | --------------------------------------------------------------------- | | `GET` | `/api/v1/whatsapp/businesses/{businessId}/catalogs` | List catalogs on a Meta business | | `POST` | `/api/v1/whatsapp/catalogs` | Create a catalog | | `GET` | `/api/v1/whatsapp/catalogs` | List catalogs in this org | | `DELETE` | `/api/v1/whatsapp/catalogs/{catalogId}` | Remove a catalog | | `GET` | `/api/v1/whatsapp/catalogs/{catalogId}/products` | List products in a catalog | | `POST` | `/api/v1/whatsapp/catalogs/{catalogId}/products` | Add a product to a catalog | | `PUT` | `/api/v1/whatsapp/products/{productId}` | Update a product's fields | | `DELETE` | `/api/v1/whatsapp/products/{productId}` | Remove a product from a catalog | | `POST` | `/api/v1/whatsapp/catalog/send` | Send a single-product message from a catalog | | `POST` | `/api/v1/whatsapp/catalog/send-list` | Send a multi-product (cart) list message grouped into titled sections | ## Calls — Business Calling WhatsApp Business Calling lets a customer place a voice call to your business from inside the WhatsApp client, and lets your business call any contact who has granted call permission. See the [WhatsApp Business Calling guide](/guides/whatsapp/business-calling) for end-to-end setup, country gates, billing, and lifecycle webhooks. ### Provisioning (per phone number) | Method | Path | Purpose | | ------ | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------- | | `GET` | `/api/v1/whatsapp/connections/{phoneNumberId}/calling` | Read calling state for one phone number (5-min cached) | | `POST` | `/api/v1/whatsapp/connections/{phoneNumberId}/calling/enable` | Enable calling on a phone number (owner / admin) | | `POST` | `/api/v1/whatsapp/connections/{phoneNumberId}/calling/disable` | Disable calling (owner / admin) | | `POST` | `/api/v1/whatsapp/connections/{phoneNumberId}/calling/register-webhook` | Subscribe the WABA to the `calls` webhook field — idempotent (owner / admin) | ### Outbound calls + permissions | Method | Path | Purpose | | ------ | ----------------------------------------------------- | ----------------------------------------------------- | | `POST` | `/api/v1/whatsapp/calling/calls` | Initiate an outbound call (owner / admin / developer) | | `GET` | `/api/v1/whatsapp/calling/permissions?contact_id=…` | List call permissions for a contact | | `POST` | `/api/v1/whatsapp/calling/calls/{metaCallId}/accept` | Accept an inbound call (operator-tier) | | `POST` | `/api/v1/whatsapp/calling/calls/{metaCallId}/decline` | Decline an inbound call | ### Dashboard surfaces | Method | Path | Purpose | | ------ | ------------------------------------ | ----------------------------------------------------------------------------- | | `GET` | `/api/v1/whatsapp/calling/calls` | Paginated `wa_call_logs` for the dashboard. PII-masked for viewer-tier roles. | | `GET` | `/api/v1/whatsapp/calling/analytics` | 30-day KPIs (volume, accept rate, duration, spend). | ## Block list | Method | Path | Purpose | | ------ | -------------------------------- | ---------------------------- | | `GET` | `/api/v1/whatsapp/block-users` | List blocked WhatsApp users | | `POST` | `/api/v1/whatsapp/block-users` | Block one or more contacts | | `POST` | `/api/v1/whatsapp/unblock-users` | Unblock one or more contacts | ## Interactive, Flow & marketing sends Most WhatsApp sends go through the unified [Messaging API](/api-reference/endpoints/messaging). Three send types have dedicated endpoints on this surface because they use Meta message types the unified send doesn't cover: | Method | Path | Purpose | | ------ | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `POST` | `/api/v1/whatsapp/messages/send-interactive` | Send a reply-buttons or list-menu interactive message inside the 24h window (no template review). | | `POST` | `/api/v1/whatsapp/messages/send-flow` | Send a published Flow as an interactive message with a CTA button that opens the multi-screen form (see [WhatsApp Flows](#whatsapp-flows)). | | `POST` | `/api/v1/whatsapp/marketing-messages/send` | Send a MARKETING-category template via Meta's Marketing Messages API (MM Lite) for send-time optimization. | The interactive `action` is either `{ buttons }` (max 3 reply buttons) or `{ button, sections }` (a list menu, max 10 sections × 10 rows each). The recipient's tap returns as `button_reply`/`list_reply` on the inbound webhook. For marketing sends, `tracking_id` is echoed on status webhooks so you can correlate delivery back to a campaign or journey. ```bash theme={null} curl -X POST https://api.orbit.devotel.io/api/v1/whatsapp/messages/send-interactive \ -H "X-API-Key: dv_live_sk_your_key_here" \ -H "Content-Type: application/json" \ -d '{ "to": "+14155550123", "body": "How can we help?", "action": { "buttons": [ { "id": "refunds", "title": "Refunds" }, { "id": "shipping", "title": "Shipping" }, { "id": "agent", "title": "Talk to human" } ] } }' ``` ## WhatsApp Flows WhatsApp Flows are native multi-screen forms — appointment booking, lead capture, surveys, support triage — that render inside the WhatsApp client without sending the customer to a browser. Build and publish a Flow, send it to a recipient with `POST /messages/send-flow`, then read each submission back on the [inbound webhook](#inbound-webhook) (as `interactive.nfm_reply`) and in the per-step funnel. ### Build & manage flows | Method | Path | Purpose | | -------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | `GET` | `/api/v1/whatsapp/flows` | List every Flow registered on the org's WABA | | `POST` | `/api/v1/whatsapp/flows` | Create a draft Flow. Body: `name` and `categories` (one or more). Owner / admin. | | `GET` | `/api/v1/whatsapp/flows/{flowId}` | Read one Flow's metadata, version, and publish status | | `POST` | `/api/v1/whatsapp/flows/{flowId}/assets` | Upload the Flow JSON definition (screens and components) for a draft. Owner / admin. | | `POST` | `/api/v1/whatsapp/flows/{flowId}/publish` | Publish a draft Flow. Publishing is irreversible. Owner / admin. | | `DELETE` | `/api/v1/whatsapp/flows/{flowId}` | Delete a draft Flow. Owner / admin. | | `GET` | `/api/v1/whatsapp/flows/{flowId}/funnel` | Per-step drop-off funnel for a Flow. Optional `since` / `until` ISO-8601 bounds default to the trailing 30 days. | `categories` accepts one or more of `APPOINTMENT_BOOKING`, `LEAD_GENERATION`, `CONTACT_US`, `CUSTOMER_SUPPORT`, `SURVEY`, and `OTHER`. Publish a Flow before you send it; only draft Flows can be deleted. ### Send a flow Send a published Flow to a recipient as an interactive message. The recipient sees a button labelled `flow_cta` that opens the form; their submission returns as `interactive.nfm_reply` on the inbound webhook, with `flow_token` echoed back so you can correlate the reply to a session or journey. ```bash theme={null} curl -X POST https://api.orbit.devotel.io/api/v1/whatsapp/messages/send-flow \ -H "X-API-Key: dv_live_sk_your_key_here" \ -H "Content-Type: application/json" \ -d '{ "to": "+14155550123", "flow_id": "1234567890", "flow_cta": "Book appointment", "body": "Pick a time that works for you.", "header_text": "Schedule a visit", "footer_text": "Powered by Orbit", "flow_token": "sess_9f2c", "flow_action": "navigate", "flow_action_payload": { "screen": "APPOINTMENT" }, "mode": "published" }' ``` `flow_cta` is capped at 20 characters and `body` at 1024. `flow_action` is `navigate` (open at a fixed first screen) or `data_exchange` (drive screens dynamically from your Flow endpoint). Set `mode` to `draft` to preview an unpublished Flow against a test recipient. ### Completion endpoint Flows built on Meta's dynamic data-exchange channel post each screen submission to a dedicated, encrypted endpoint mounted under its own base path: | Method | Path | Purpose | | ------ | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `GET` | `/api/v1/channels/whatsapp/flows` | List the org's local Flow definitions (backs the composer's Flow picker) | | `POST` | `/api/v1/channels/whatsapp/flows/endpoint` | Meta's Flow Endpoint Data Channel — receives encrypted screen-exchange requests and returns the encrypted next screen. Not callable by your application. | Meta signs each `/endpoint` request with `X-Hub-Signature-256` and identifies the tenant with the `X-Devotel-Org-Id` header; the response is the AES-128-GCM-encrypted next-screen payload returned as `text/plain`, per Meta's Flow Endpoint spec. Like the inbound webhook, it's configured in Meta and called by Meta — you don't call it yourself. It's listed here for completeness. ## Test-account analytics | Method | Path | Purpose | | ------ | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | `GET` | `/api/v1/whatsapp/test-account/analytics` | Pre-aggregated KPI counts plus a 30-day daily-volume series for the test-account analytics card, scoped to your OTP-verified recipient. | This is a read-only aggregate for the dashboard's test-account view — it has no provider or billing side-effect. ## Cost optimization Plan a batch of WhatsApp sends *before* they go out. The optimizer picks the cheapest valid Meta conversation category per recipient, sequences utility/authentication ahead of marketing to ride open conversation windows, and (when a `budgetUsd` cap is supplied) defers the sends that would exceed it — returning a projected-spend and savings report. This endpoint is pure planning: it never sends a message. | Method | Path | Purpose | | ------ | -------------------------------------- | ---------------------------------------------------------------------- | | `POST` | `/api/v1/whatsapp/cost-optimizer/plan` | Build a cost-optimized send plan (projected spend, savings, deferrals) | ```bash theme={null} curl -X POST https://api.orbit.devotel.io/api/v1/whatsapp/cost-optimizer/plan \ -H "X-API-Key: dv_live_sk_your_key_here" \ -H "Content-Type: application/json" \ -d '{ "budgetUsd": 25.0, "sends": [ { "id": "msg-1", "to": "+14155550123", "eligibleCategories": ["utility", "marketing"], "withinOpenWindow": true } ] }' ``` ## Inbound webhook The platform also exposes the inbound Meta webhook at `GET/POST /api/v1/whatsapp/webhook` — Meta verifies it on subscription (GET, with the `hub.challenge` token) and posts message + status events to the POST handler. This endpoint is not callable by your application; it's listed here for completeness. ## Example — read current profile ```bash theme={null} curl https://api.orbit.devotel.io/api/v1/whatsapp/business-profile \ -H "X-API-Key: dv_live_sk_your_key_here" ``` ## See also * [Messaging API → Send WhatsApp](/api-reference/endpoints/messaging) — outbound message sending * [Channels → WhatsApp guide](/channels/whatsapp) — concepts, template approval, pricing * [WhatsApp content policy](/compliance/whatsapp-content-policy)