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

200 sample — list connections

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

Returns every connected phone number with the org default flagged (is_default: true) — send this connection’s phone_number_id to any endpoint that accepts a multi-WABA selector:

{
  "data": {
    "connections": [
      {
        "waba_id": "102938475610293",
        "phone_number_id": "918273645012345",
        "phone_display": "+1 415 555 0123",
        "business_name": "Acme Supplies",
        "verified_name": "Acme Supplies",
        "connected_at": "2026-08-27T09:41:12.000Z",
        "status": "active",
        "is_default": true,
        "registration_state": "registered"
      }
    ],
    "default_phone_number_id": "918273645012345"
  },
  "meta": {
    "request_id": "req_a1b2c3d4",
    "timestamp": "2026-08-27T09:41:12.431Z"
  }
}

PUT /connections/{phoneNumberId}/default, PATCH /connections/{phoneNumberId}, and both DELETE variants answer with {"data": {"ok": true}, "meta": {...}}. POST /connect runs once from Meta’s Embedded Signup (it exchanges a one-time sign-up code) — the WABA setup guide walks that flow. The corresponding Node SDK call is:

import Orbit from "@devotel-orbit/node";

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY });

// Inputs sent to this page's samples: {"to": "+14155550123", ...} at a base of /api/v1
const connections = await orbit.request("GET", "/whatsapp/connections");

// Same payload as the example above.
console.log(connections.data.connections[0].phone_number_id);

The corresponding Python call — the Python SDK doesn’t wrap this page’s surface, so its client.request escape hatch runs the same resource (source-only; vendor it from packages/sdk-python):

from orbit_sdk import OrbitClient

client = OrbitClient.from_api_key("dv_test_sk_YOUR_KEY")
connections = client.request("GET", "/whatsapp/connections")

# Same payload as the example above.
print(connections["data"]["connections"][0]["phone_number_id"])

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)

200 sample — read then update the business profile

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

{
  "data": {
    "about": "Same-day delivery across the city",
    "address": "17 Market Street, Mumbai 400001",
    "description": "Wholesale supplies for small retailers",
    "email": "orders@acme.example",
    "websites": ["https://acme.example", "https://support.acme.example"],
    "vertical": "RETAIL",
    "profile_picture_url": "https://scontent.whatsapp.net/v/t61.29473-33/450112233_1_w450.jpg"
  },
  "meta": {
    "request_id": "req_e5f6g7h8",
    "timestamp": "2026-08-27T09:42:03.118Z"
  }
}

Send only the fields you’re changing — everything else stays untouched:

curl -X PUT https://api.orbit.devotel.io/api/v1/whatsapp/business-profile \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "about": "Same-day delivery, nationwide", "vertical": "RETAIL" }'

A successful update answers {"data": {"ok": true}, "meta": {...}} — Meta re-renders the profile in the customer’s client within minutes. Field caps are validated before the call reaches Meta: about 139 chars, address 256, description 512, email 128, websites at most 2 entries (each an https URL). Exceeding one returns a 422 naming the field, so you never see Meta’s terse error_subcode.

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/catalogs/{catalogId}/send`	Same send with the catalog id in the path instead of the body
`POST`	`/api/v1/whatsapp/catalog/send-list`	Send a multi-product (cart) list message grouped into titled sections

200 sample — catalog lifecycle

Manage products on a catalog the org owns, then send one to a customer:

# 1. List the products on your catalog
curl "https://api.orbit.devotel.io/api/v1/whatsapp/catalogs/cat_120394857612/products?limit=2" \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "data": {
    "products": [
      {
        "id": "8475610234",
        "retailer_id": "SKU-RICE-5KG",
        "name": "Basmati rice 5 kg",
        "description": "Extra-long grain, aged 12 months",
        "price": 1190,
        "currency": "USD",
        "availability": "in stock",
        "image_url": "https://cdn.acme.example/rice-5kg.png"
      }
    ],
    "next_cursor": "eyJvZmZzZXQiOjF9"
  },
  "meta": {
    "request_id": "req_i9j0k1l2",
    "timestamp": "2026-08-27T09:45:11.502Z"
  }
}

# 2. Create a product (PUT /products/{productId} updates the same fields
#    and DELETE /products/{productId} removes it)
curl -X POST https://api.orbit.devotel.io/api/v1/whatsapp/catalogs/cat_120394857612/products \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Basmati rice 5 kg",
  "description": "Extra-long grain, aged 12 months",
  "currency": "USD",
  "price": 1190,
  "retailer_id": "SKU-RICE-5KG",
  "image_url": "https://cdn.acme.example/rice-5kg.png",
  "availability": "in stock"
}'

{
  "data": { "id": "8475610234" },
  "meta": {
    "request_id": "req_m3n4o5p6",
    "timestamp": "2026-08-27T09:45:40.018Z"
  }
}

# 3. Send the product to a recipient as a single-product message
curl -X POST https://api.orbit.devotel.io/api/v1/whatsapp/catalogs/cat_120394857612/send \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "to": "+14155550123", "product_retailer_id": "SKU-RICE-5KG", "body": "Back in stock" }'

{
  "data": {
    "messageId": "msg_e49d7a2c1b",
    "status": "sent"
  },
  "meta": {
    "request_id": "req_q7r8s9t0",
    "timestamp": "2026-08-27T09:46:02.777Z"
  }
}

/catalog/send accepts the same body with catalog_id inside it instead of in the path; /catalog/send-list takes sections (each with title and product_retailer_ids) and returns the same send envelope. A recipient’s cart checkout returns on the inbound webhook as an order message.

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. Five 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-location-request`	Prompt the recipient with a “Send location” button inside the 24h window (no template review).
`POST`	`/api/v1/whatsapp/messages/send-address-request`	Prompt the recipient with a structured delivery-address form 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" }
    ]
  }
}'

200 sample — send → receipt → decoded reply

The send answers with the platform send envelope (status: "sent" on every send endpoint, 200 OK transport):

{
  "data": {
    "messageId": "msg_7c21f90d5a",
    "status": "sent"
  },
  "meta": {
    "request_id": "req_a4b6c8d0",
    "timestamp": "2026-08-27T09:47:31.904Z"
  }
}

Watch message.sent on your tenant webhook to correlate the send, then the inbound Meta webhook carries the recipient’s tap — here a reply-button tap, decoded:

{
  "type": "interactive",
  "interactive": {
    "type": "button_reply",
    "button_reply": { "id": "refunds", "title": "Refunds" }
  },
  "from": "+14155550123",
  "message_id": "msg_7c21f90d5a"
}

The button_reply.id round-trips the id you sent on the button, unmodified. The corresponding Node SDK call (the SDK has no helper for these five send types yet — use the low-level request escape hatch):

import Orbit from "@devotel-orbit/node";

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY });

// Inputs sent to this page's samples: {"to": "+14155550123", ...} at a base of /api/v1
const send = await orbit.request("POST", "/whatsapp/messages/send-interactive", {
  to: "+14155550123",
  body: "How can we help?",
  action: {
    buttons: [
      { id: "refunds", title: "Refunds" },
      { id: "shipping", title: "Shipping" },
      { id: "agent", title: "Talk to human" },
    ],
  },
});

console.log(send.data.status); // "sent"

Location & delivery-address requests

Two more interactive prompts send inside the same 24-hour customer-service window with no template review, and the recipient’s reply threads straight back into the conversation. POST /messages/send-location-request shows a “Send location” button. When the recipient taps it and shares their location, it lands on the inbound webhook as a plain location message (not an interactive reply) — useful for “find your nearest store” or pickup-confirmation flows. Body: to and body (the prompt text, 1-1024 chars).

curl -X POST https://api.orbit.devotel.io/api/v1/whatsapp/messages/send-location-request \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "+14155550123",
  "body": "Please share your location so we can find your nearest store."
}'

POST /messages/send-address-request shows a structured delivery-address form. country is an ISO 3166-1 alpha-2 code (available in India and Singapore as of Meta’s 2026 rollout) and selects the field set Meta renders — it is a wire-format check only, never a coverage or compliance gate. The completed form returns on the inbound webhook as an interactive.address_message reply, so you can attach it straight to an order. Optionally pass values to pre-fill fields you already know, or saved_addresses to offer a returning customer their prior addresses to pick from.

curl -X POST https://api.orbit.devotel.io/api/v1/whatsapp/messages/send-address-request \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "+14155550123",
  "body": "Where should we deliver your order?",
  "country": "IN",
  "values": { "name": "Jane Doe", "city": "Mumbai" }
}'

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.
`GET`	`/api/v1/whatsapp/flows/{flowId}/submissions`	List submissions a published Flow has received (the recipient-side record of each `nfm_reply`).

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.

200 sample — list flows

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

{
  "data": [
    {
      "id": "7845320987654",
      "name": "Appointment booking",
      "status": "PUBLISHED",
      "categories": ["APPOINTMENT_BOOKING"]
    },
    {
      "id": "8076543210987",
      "name": "Support triage",
      "status": "DRAFT",
      "categories": ["CUSTOMER_SUPPORT"],
      "validation_errors": [
        { "error_type": "MISSING_PROPERTY", "message": "Screen APPOINTMENT has no footer" }
      ]
    }
  ],
  "meta": {
    "request_id": "req_u1v2w3x4",
    "timestamp": "2026-08-27T09:50:18.266Z"
  }
}

A draft with validation_errors can’t be published until the upload those errors refer to is fixed — fix the offending screens, re-post the assets, then re-publish.

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"
}'

200 sample — send-flow → receipt

The send answers with the same send envelope as every other send endpoint:

{
  "data": {
    "messageId": "msg_b0d3f8a2e71",
    "status": "sent"
  },
  "meta": {
    "request_id": "req_y5z6a7b8",
    "timestamp": "2026-08-27T09:52:44.091Z"
  }
}

The recipient’s submission returns on the inbound webhook as interactive.nfm_reply, with the flow_token you sent echoed back so you can correlate the reply to a session or journey:

{
  "type": "interactive",
  "interactive": {
    "type": "nfm_reply",
    "nfm_reply": {
      "flow_token": "sess_9f2c",
      "response_json": {
        "screen": "APPOINTMENT",
        "date": "2026-09-01",
        "slot": "10:30"
      }
    }
  },
  "from": "+14155550123"
}

Every submission is also listed on GET /api/v1/whatsapp/flows/{flowId}/submissions, so a reply that arrived before your webhook consumer was ready is never lost. 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: WABA, profile, catalogs, and Flows

WhatsApp API

Connections

200 sample — list connections

Business profile

200 sample — read then update the business profile

Catalogs & products

200 sample — catalog lifecycle

Calls — Business Calling

Provisioning (per phone number)

Outbound calls + permissions

Dashboard surfaces

Block list

Interactive, Flow & marketing sends

200 sample — send → receipt → decoded reply

Location & delivery-address requests

WhatsApp Flows

Build & manage flows

200 sample — list flows

Send a flow

200 sample — send-flow → receipt

Completion endpoint

Test-account analytics

Cost optimization

Inbound webhook

Example — read current profile

See also

​WhatsApp API

​Connections

​200 sample — list connections

​Business profile

​200 sample — read then update the business profile

​Catalogs & products

​200 sample — catalog lifecycle

​Calls — Business Calling

​Provisioning (per phone number)

​Outbound calls + permissions

​Dashboard surfaces

​Block list

​Interactive, Flow & marketing sends

​200 sample — send → receipt → decoded reply

​Location & delivery-address requests

​WhatsApp Flows

​Build & manage flows

​200 sample — list flows

​Send a flow

​200 sample — send-flow → receipt

​Completion endpoint

​Test-account analytics

​Cost optimization

​Inbound webhook

​Example — read current profile

​See also

WhatsApp API

Connections

200 sample — list connections

Business profile

200 sample — read then update the business profile

Catalogs & products

200 sample — catalog lifecycle

Calls — Business Calling

Provisioning (per phone number)

Outbound calls + permissions

Dashboard surfaces

Block list

Interactive, Flow & marketing sends

200 sample — send → receipt → decoded reply

Location & delivery-address requests

WhatsApp Flows

Build & manage flows

200 sample — list flows

Send a flow

200 sample — send-flow → receipt

Completion endpoint

Test-account analytics

Cost optimization

Inbound webhook

Example — read current profile

See also