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

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

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)

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

curl https://api.orbit.devotel.io/api/v1/whatsapp/business-profile \
  -H "X-API-Key: dv_live_sk_your_key_here"

API Reference

All Endpoints

WhatsApp API

WhatsApp API

Connections

Business profile

Catalogs & products

Calls — Business Calling

Provisioning (per phone number)

Outbound calls + permissions

Dashboard surfaces

Block list

Interactive, Flow & marketing sends

WhatsApp Flows

Build & manage flows

Send a flow

Completion endpoint

Test-account analytics

Cost optimization

Inbound webhook

Example — read current profile

See also

​WhatsApp API

​Connections

​Business profile

​Catalogs & products

​Calls — Business Calling

​Provisioning (per phone number)

​Outbound calls + permissions

​Dashboard surfaces

​Block list

​Interactive, Flow & marketing sends

​WhatsApp Flows

​Build & manage flows

​Send a flow

​Completion endpoint

​Test-account analytics

​Cost optimization

​Inbound webhook

​Example — read current profile

​See also

WhatsApp API

Connections

Business profile

Catalogs & products

Calls — Business Calling

Provisioning (per phone number)

Outbound calls + permissions

Dashboard surfaces

Block list

Interactive, Flow & marketing sends

WhatsApp Flows

Build & manage flows

Send a flow

Completion endpoint

Test-account analytics

Cost optimization

Inbound webhook

Example — read current profile

See also