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.

Send a template message

The headline send operation most flows start with — a pre-approved template via the unified Messaging API. Templates are required whenever the recipient’s 24-hour freeform window is closed, which is the case for the first message of any conversation.

cURL

curl -X POST https://api.orbit.devotel.io/api/v1/messages/whatsapp \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155550123",
    "type": "template",
    "template": {
      "name": "order_confirmation",
      "language": { "code": "en" }
    }
  }'

Node.js

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

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY });
const res = await orbit.messages.sendWhatsApp({
  to: "+14155550123",
  type: "template",
  template: {
    name: "order_confirmation",
    language: { code: "en" },
  },
});

Python

import os, requests

r = requests.post(
  "https://api.orbit.devotel.io/api/v1/messages/whatsapp",
  headers={"X-API-Key": os.environ["ORBIT_API_KEY"]},
  json={
    "to": "+14155550123",
    "type": "template",
    "template": {
      "name": "order_confirmation",
      "language": { "code": "en" },
    },
  },
)
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/messages/whatsapp", bytes.NewBuffer([]byte(`{
    "to": "+14155550123",
    "type": "template",
    "template": {
      "name": "order_confirmation",
      "language": { "code": "en" }
    }
  }`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/messages/whatsapp')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  to: '+14155550123',
  type: 'template',
  template: {
    name: 'order_confirmation',
    language: { code: 'en' }
  }
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/messages/whatsapp');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
  'to' => '+14155550123',
  'type' => 'template',
  'template' => [
    'name' => 'order_confirmation',
    'language' => ['code' => 'en'],
  ],
]));
echo curl_exec($ch);

{
  "data": {
    "id": "message_a1b2c3",
    "channel": "whatsapp",
    "direction": "outbound",
    "to": "+14155550123",
    "status": "queued"
  },
  "meta": {
    "request_id": "req_w0x1y2z3",
    "timestamp": "2026-09-19T00:00:00.000Z"
  }
}

data.id is the message id you correlate with message.sent and status webhooks. Template variables can be passed as Meta-native template.components or as the flat positional template_params map (e.g. { "1": "Acme" }) — the send rejects with 422 before it reaches Meta when a parameter count mismatches.

Using the SDKs

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

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

// The typed helper covers text, template, media, interactive, location,
// contact, and reaction — a discriminated union on `type`.
const res = await orbit.messages.sendWhatsApp({
  to: "+14155550123",
  type: "template",
  template: { name: "order_confirmation", language: { code: "en" } },
});

The Node SDK is the only typed path — Python reaches this endpoint through its client.request() escape hatch, and Go, Ruby, and PHP use the plain-HTTP-client samples above. See the SDK quickstart.

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

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

Node.js

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

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

const connections = await orbit.request("GET", "/whatsapp/connections");
console.log(connections.data.connections[0].phone_number_id);

Python

import os, requests

r = requests.get(
  "https://api.orbit.devotel.io/api/v1/whatsapp/connections",
  headers={"X-API-Key": os.environ["ORBIT_API_KEY"]},
)
print(r.json()["data"]["connections"][0]["phone_number_id"])

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/whatsapp/connections", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

Ruby

require 'net/http'

uri = URI('https://api.orbit.devotel.io/api/v1/whatsapp/connections')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/whatsapp/connections');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
]);
echo curl_exec($ch);

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 per Meta Embedded Signup session — it exchanges the one-time sign-up code for the long-lived connection. The WABA setup guide walks the signup flow. If the Meta login owns more than one (WABA, phone number) pair, the first call answers with the discovered options; re-POST the same code together with the chosen waba_id and phone_number_id to finalize.

cURL

curl -X POST https://api.orbit.devotel.io/api/v1/whatsapp/connect \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "code": "AQGuxFkT4xYdZq..." }'

Node.js

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

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

// First pass: code only. If the answer lists several (WABA, phone)
// pairs, re-send with waba_id + phone_number_id to finalize.
const connection = await orbit.request("POST", "/whatsapp/connect", {
  code: "AQGuxFkT4xYdZq...",
});
console.log(connection.data.phone_number_id);

Python

import os, requests

r = requests.post(
  "https://api.orbit.devotel.io/api/v1/whatsapp/connect",
  headers={"X-API-Key": os.environ["ORBIT_API_KEY"]},
  json={"code": "AQGuxFkT4xYdZq..."},
)
print(r.json()["data"]["phone_number_id"])

package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/whatsapp/connect", bytes.NewBuffer([]byte(`{
    "code": "AQGuxFkT4xYdZq..."
  }`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/whatsapp/connect')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = { code: 'AQGuxFkT4xYdZq...' }.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/whatsapp/connect');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
  'code' => 'AQGuxFkT4xYdZq...',
]));
echo curl_exec($ch);

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 the business profile

cURL

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

Node.js

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

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

const profile = await orbit.request("GET", "/whatsapp/business-profile");
console.log(profile.data.about);

Python

import os, requests

r = requests.get(
  "https://api.orbit.devotel.io/api/v1/whatsapp/business-profile",
  headers={"X-API-Key": os.environ["ORBIT_API_KEY"]},
)
print(r.json()["data"]["about"])

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/whatsapp/business-profile", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

Ruby

require 'net/http'

uri = URI('https://api.orbit.devotel.io/api/v1/whatsapp/business-profile')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/whatsapp/business-profile');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
]);
echo curl_exec($ch);

{
  "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

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

Node.js

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

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

const updated = await orbit.request("PUT", "/whatsapp/business-profile", {
  about: "Same-day delivery, nationwide",
  vertical: "RETAIL",
});
console.log(updated.data.ok); // true

Python

import os, requests

r = requests.put(
  "https://api.orbit.devotel.io/api/v1/whatsapp/business-profile",
  headers={"X-API-Key": os.environ["ORBIT_API_KEY"]},
  json={"about": "Same-day delivery, nationwide", "vertical": "RETAIL"},
)
print(r.json()["data"]["ok"])  # True

package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("PUT", "https://api.orbit.devotel.io/api/v1/whatsapp/business-profile", bytes.NewBuffer([]byte(`{
    "about": "Same-day delivery, nationwide",
    "vertical": "RETAIL"
  }`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/whatsapp/business-profile')
req = Net::HTTP::Put.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = { about: 'Same-day delivery, nationwide', vertical: 'RETAIL' }.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/whatsapp/business-profile');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
  'about' => 'Same-day delivery, nationwide',
  'vertical' => 'RETAIL',
]));
echo curl_exec($ch);

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. List the products on your catalog:

cURL

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"

Node.js

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

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

const page = await orbit.request(
  "GET",
  "/whatsapp/catalogs/cat_120394857612/products?limit=2",
);
console.log(page.data.products[0].retailer_id);

Python

import os, requests

r = requests.get(
  "https://api.orbit.devotel.io/api/v1/whatsapp/catalogs/cat_120394857612/products",
  params={"limit": 2},
  headers={"X-API-Key": os.environ["ORBIT_API_KEY"]},
)
print(r.json()["data"]["products"][0]["retailer_id"])

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/whatsapp/catalogs/cat_120394857612/products?limit=2", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

Ruby

require 'net/http'

uri = URI('https://api.orbit.devotel.io/api/v1/whatsapp/catalogs/cat_120394857612/products?limit=2')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/whatsapp/catalogs/cat_120394857612/products?limit=2');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
]);
echo curl_exec($ch);

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

Create a product (PUT /products/{productId} updates the same fields and DELETE /products/{productId} removes it):

cURL

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

Node.js

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

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

const product = await orbit.request(
  "POST",
  "/whatsapp/catalogs/cat_120394857612/products",
  {
    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",
  },
);
console.log(product.data.id);

Python

import os, requests

r = requests.post(
  "https://api.orbit.devotel.io/api/v1/whatsapp/catalogs/cat_120394857612/products",
  headers={"X-API-Key": os.environ["ORBIT_API_KEY"]},
  json={
    "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",
  },
)
print(r.json()["data"]["id"])

package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/whatsapp/catalogs/cat_120394857612/products", bytes.NewBuffer([]byte(`{
  "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"
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/whatsapp/catalogs/cat_120394857612/products')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  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'
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/whatsapp/catalogs/cat_120394857612/products');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
  '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',
]));
echo curl_exec($ch);

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

Send the product to a recipient as a single-product message:

cURL

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

Node.js

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

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

const send = await orbit.request(
  "POST",
  "/whatsapp/catalogs/cat_120394857612/send",
  { to: "+14155550123", product_retailer_id: "SKU-RICE-5KG", body: "Back in stock" },
);
console.log(send.data.status); // "sent"

Python

import os, requests

r = requests.post(
  "https://api.orbit.devotel.io/api/v1/whatsapp/catalogs/cat_120394857612/send",
  headers={"X-API-Key": os.environ["ORBIT_API_KEY"]},
  json={
    "to": "+14155550123",
    "product_retailer_id": "SKU-RICE-5KG",
    "body": "Back in stock",
  },
)
print(r.json()["data"]["status"])  # "sent"

package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/whatsapp/catalogs/cat_120394857612/send", bytes.NewBuffer([]byte(`{
  "to": "+14155550123",
  "product_retailer_id": "SKU-RICE-5KG",
  "body": "Back in stock"
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/whatsapp/catalogs/cat_120394857612/send')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  to: '+14155550123',
  product_retailer_id: 'SKU-RICE-5KG',
  body: 'Back in stock'
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/whatsapp/catalogs/cat_120394857612/send');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
  'to' => '+14155550123',
  'product_retailer_id' => 'SKU-RICE-5KG',
  'body' => 'Back in stock',
]));
echo curl_exec($ch);

{
  "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

List the call permissions a contact has granted — paginate with cursor (the call answers pagination.cursor when more rows remain):

cURL

curl "https://api.orbit.devotel.io/api/v1/whatsapp/calling/permissions?contact_id=ctc_9f2c1a&limit=50" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

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

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

const page = await orbit.request(
  "GET",
  "/whatsapp/calling/permissions?contact_id=ctc_9f2c1a&limit=50",
);
console.log(page.data.permissions.length);

Python

import os, requests

r = requests.get(
  "https://api.orbit.devotel.io/api/v1/whatsapp/calling/permissions",
  params={"contact_id": "ctc_9f2c1a", "limit": 50},
  headers={"X-API-Key": os.environ["ORBIT_API_KEY"]},
)
print(len(r.json()["data"]["permissions"]))

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/whatsapp/calling/permissions?contact_id=ctc_9f2c1a&limit=50", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

Ruby

require 'net/http'

uri = URI('https://api.orbit.devotel.io/api/v1/whatsapp/calling/permissions?contact_id=ctc_9f2c1a&limit=50')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/whatsapp/calling/permissions?contact_id=ctc_9f2c1a&limit=50');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
]);
echo curl_exec($ch);

Initiate an outbound call to a contact who has granted permission. from_phone_number_id is the calling-enabled connection from the list above (enable it first via the provisioning endpoints):

cURL

curl -X POST https://api.orbit.devotel.io/api/v1/whatsapp/calling/calls \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "to": "+14155550123", "from_phone_number_id": "918273645012345" }'

Node.js

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

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

const call = await orbit.request("POST", "/whatsapp/calling/calls", {
  to: "+14155550123",
  from_phone_number_id: "918273645012345",
});
console.log(call.data.meta_call_id);

Python

import os, requests

r = requests.post(
  "https://api.orbit.devotel.io/api/v1/whatsapp/calling/calls",
  headers={"X-API-Key": os.environ["ORBIT_API_KEY"]},
  json={"to": "+14155550123", "from_phone_number_id": "918273645012345"},
)
print(r.json()["data"]["meta_call_id"])

package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/whatsapp/calling/calls", bytes.NewBuffer([]byte(`{
  "to": "+14155550123",
  "from_phone_number_id": "918273645012345"
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/whatsapp/calling/calls')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  to: '+14155550123',
  from_phone_number_id: '918273645012345'
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/whatsapp/calling/calls');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
  'to' => '+14155550123',
  'from_phone_number_id' => '918273645012345',
]));
echo curl_exec($ch);

The initiate call answers {"data": {"ok": true, "meta_call_id": "...", "wa_call_log_id": "..."}, "meta": {...}}; call lifecycle events (call.started, call.ended) ride the same webhook as message events. Reads for the dashboard follow the same auth: GET /calling/permissions and the two call mutations are shown above; the paginated call log and the 30-day KPI aggregate are listed under Dashboard surfaces below.

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

List the users currently blocked on your WABA (after pages forward, limit caps at 100):

cURL

curl "https://api.orbit.devotel.io/api/v1/whatsapp/block-users?limit=100" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

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

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

const list = await orbit.request("GET", "/whatsapp/block-users?limit=100");
console.log(list.data);

Python

import os, requests

r = requests.get(
  "https://api.orbit.devotel.io/api/v1/whatsapp/block-users",
  params={"limit": 100},
  headers={"X-API-Key": os.environ["ORBIT_API_KEY"]},
)
print(r.json()["data"])

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/whatsapp/block-users?limit=100", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

Ruby

require 'net/http'

uri = URI('https://api.orbit.devotel.io/api/v1/whatsapp/block-users?limit=100')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/whatsapp/block-users?limit=100');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
]);
echo curl_exec($ch);

Block up to 100 users in one call — send the same body to POST /unblock-users to reverse it:

cURL

curl -X POST https://api.orbit.devotel.io/api/v1/whatsapp/block-users \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "users": ["+14155550123", "+14155550199"] }'

Node.js

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

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

// The same body on "/whatsapp/unblock-users" unblocks the users.
const blocked = await orbit.request("POST", "/whatsapp/block-users", {
  users: ["+14155550123", "+14155550199"],
});
console.log(blocked.data);

Python

import os, requests

r = requests.post(
  "https://api.orbit.devotel.io/api/v1/whatsapp/block-users",
  headers={"X-API-Key": os.environ["ORBIT_API_KEY"]},
  json={"users": ["+14155550123", "+14155550199"]},
)
print(r.json()["data"])

package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/whatsapp/block-users", bytes.NewBuffer([]byte(`{
  "users": ["+14155550123", "+14155550199"]
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/whatsapp/block-users')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = { users: ['+14155550123', '+14155550199'] }.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/whatsapp/block-users');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
  'users' => ['+14155550123', '+14155550199'],
]));
echo curl_exec($ch);

Both writes answer {"data": {"ok": true}, "meta": {...}} once Meta confirms the change.

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

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

Node.js

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

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

// The SDK has no typed helper for these five send types yet —
// the low-level request escape hatch reaches them all.
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"

Python

import os, requests

r = requests.post(
  "https://api.orbit.devotel.io/api/v1/whatsapp/messages/send-interactive",
  headers={"X-API-Key": os.environ["ORBIT_API_KEY"]},
  json={
    "to": "+14155550123",
    "body": "How can we help?",
    "action": {
      "buttons": [
        {"id": "refunds", "title": "Refunds"},
        {"id": "shipping", "title": "Shipping"},
        {"id": "agent", "title": "Talk to human"},
      ],
    },
  },
)
print(r.json()["data"]["status"])  # "sent"

package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/whatsapp/messages/send-interactive", bytes.NewBuffer([]byte(`{
  "to": "+14155550123",
  "body": "How can we help?",
  "action": {
    "buttons": [
      { "id": "refunds", "title": "Refunds" },
      { "id": "shipping", "title": "Shipping" },
      { "id": "agent", "title": "Talk to human" }
    ]
  }
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/whatsapp/messages/send-interactive')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  to: '+14155550123',
  body: 'How can we help?',
  action: {
    buttons: [
      { id: 'refunds', title: 'Refunds' },
      { id: 'shipping', title: 'Shipping' },
      { id: 'agent', title: 'Talk to human' }
    ]
  }
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/whatsapp/messages/send-interactive');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
  'to' => '+14155550123',
  'body' => 'How can we help?',
  'action' => [
    'buttons' => [
      ['id' => 'refunds', 'title' => 'Refunds'],
      ['id' => 'shipping', 'title' => 'Shipping'],
      ['id' => 'agent', 'title' => 'Talk to human'],
    ],
  ],
]));
echo curl_exec($ch);

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.

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

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

Node.js

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

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

const send = await orbit.request(
  "POST",
  "/whatsapp/messages/send-location-request",
  {
    to: "+14155550123",
    body: "Please share your location so we can find your nearest store.",
  },
);
console.log(send.data.status); // "sent"

Python

import os, requests

r = requests.post(
  "https://api.orbit.devotel.io/api/v1/whatsapp/messages/send-location-request",
  headers={"X-API-Key": os.environ["ORBIT_API_KEY"]},
  json={
    "to": "+14155550123",
    "body": "Please share your location so we can find your nearest store.",
  },
)
print(r.json()["data"]["status"])  # "sent"

package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/whatsapp/messages/send-location-request", bytes.NewBuffer([]byte(`{
  "to": "+14155550123",
  "body": "Please share your location so we can find your nearest store."
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/whatsapp/messages/send-location-request')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  to: '+14155550123',
  body: 'Please share your location so we can find your nearest store.'
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/whatsapp/messages/send-location-request');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
  'to' => '+14155550123',
  'body' => 'Please share your location so we can find your nearest store.',
]));
echo curl_exec($ch);

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

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

Node.js

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

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

const send = await orbit.request(
  "POST",
  "/whatsapp/messages/send-address-request",
  {
    to: "+14155550123",
    body: "Where should we deliver your order?",
    country: "IN",
    values: { name: "Jane Doe", city: "Mumbai" },
  },
);
console.log(send.data.status); // "sent"

Python

import os, requests

r = requests.post(
  "https://api.orbit.devotel.io/api/v1/whatsapp/messages/send-address-request",
  headers={"X-API-Key": os.environ["ORBIT_API_KEY"]},
  json={
    "to": "+14155550123",
    "body": "Where should we deliver your order?",
    "country": "IN",
    "values": {"name": "Jane Doe", "city": "Mumbai"},
  },
)
print(r.json()["data"]["status"])  # "sent"

package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/whatsapp/messages/send-address-request", bytes.NewBuffer([]byte(`{
  "to": "+14155550123",
  "body": "Where should we deliver your order?",
  "country": "IN",
  "values": { "name": "Jane Doe", "city": "Mumbai" }
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/whatsapp/messages/send-address-request')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  to: '+14155550123',
  body: 'Where should we deliver your order?',
  country: 'IN',
  values: { name: 'Jane Doe', city: 'Mumbai' }
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/whatsapp/messages/send-address-request');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
  'to' => '+14155550123',
  'body' => 'Where should we deliver your order?',
  'country' => 'IN',
  'values' => ['name' => 'Jane Doe', 'city' => 'Mumbai'],
]));
echo curl_exec($ch);

Marketing template sends

POST /marketing-messages/send routes a MARKETING-category template through Meta’s Marketing Messages API (MM Lite) instead of the standard send path, so Meta applies send-time and creative optimization. Required fields: to, template_name, language_code; optional components (template variables), tracking_id (echoed on status webhooks for campaign correlation), and phone_number_id (multi-WABA selector).

cURL

curl -X POST https://api.orbit.devotel.io/api/v1/whatsapp/marketing-messages/send \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "+14155550123",
  "template_name": "autumn_sale",
  "language_code": "en",
  "tracking_id": "camp_autumn_26"
}'

Node.js

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

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

const send = await orbit.request("POST", "/whatsapp/marketing-messages/send", {
  to: "+14155550123",
  template_name: "autumn_sale",
  language_code: "en",
  tracking_id: "camp_autumn_26",
});
console.log(send.data.status); // "sent"

Python

import os, requests

r = requests.post(
  "https://api.orbit.devotel.io/api/v1/whatsapp/marketing-messages/send",
  headers={"X-API-Key": os.environ["ORBIT_API_KEY"]},
  json={
    "to": "+14155550123",
    "template_name": "autumn_sale",
    "language_code": "en",
    "tracking_id": "camp_autumn_26",
  },
)
print(r.json()["data"]["status"])  # "sent"

package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/whatsapp/marketing-messages/send", bytes.NewBuffer([]byte(`{
  "to": "+14155550123",
  "template_name": "autumn_sale",
  "language_code": "en",
  "tracking_id": "camp_autumn_26"
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/whatsapp/marketing-messages/send')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  to: '+14155550123',
  template_name: 'autumn_sale',
  language_code: 'en',
  tracking_id: 'camp_autumn_26'
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/whatsapp/marketing-messages/send');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
  'to' => '+14155550123',
  'template_name' => 'autumn_sale',
  'language_code' => 'en',
  'tracking_id' => 'camp_autumn_26',
]));
echo curl_exec($ch);

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. Create a draft Flow, then upload its screen definition with POST /flows/{flowId}/assets and publish:

cURL

curl -X POST https://api.orbit.devotel.io/api/v1/whatsapp/flows \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Appointment booking", "categories": ["APPOINTMENT_BOOKING"] }'

Node.js

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

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

const flow = await orbit.request("POST", "/whatsapp/flows", {
  name: "Appointment booking",
  categories: ["APPOINTMENT_BOOKING"],
});
console.log(flow.data.id);

Python

import os, requests

r = requests.post(
  "https://api.orbit.devotel.io/api/v1/whatsapp/flows",
  headers={"X-API-Key": os.environ["ORBIT_API_KEY"]},
  json={"name": "Appointment booking", "categories": ["APPOINTMENT_BOOKING"]},
)
print(r.json()["data"]["id"])

package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/whatsapp/flows", bytes.NewBuffer([]byte(`{
  "name": "Appointment booking",
  "categories": ["APPOINTMENT_BOOKING"]
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/whatsapp/flows')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  name: 'Appointment booking',
  categories: ['APPOINTMENT_BOOKING']
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/whatsapp/flows');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
  'name' => 'Appointment booking',
  'categories' => ['APPOINTMENT_BOOKING'],
]));
echo curl_exec($ch);

200 sample — list flows

cURL

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

Node.js

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

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

const flows = await orbit.request("GET", "/whatsapp/flows");
console.log(flows.data.map((f: { id: string; name: string }) => f.name));

Python

import os, requests

r = requests.get(
  "https://api.orbit.devotel.io/api/v1/whatsapp/flows",
  headers={"X-API-Key": os.environ["ORBIT_API_KEY"]},
)
print([f["name"] for f in r.json()["data"]])

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/whatsapp/flows", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

Ruby

require 'net/http'

uri = URI('https://api.orbit.devotel.io/api/v1/whatsapp/flows')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/whatsapp/flows');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
]);
echo curl_exec($ch);

{
  "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

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

Node.js

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

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

const send = await orbit.request("POST", "/whatsapp/messages/send-flow", {
  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",
});
console.log(send.data.status); // "sent"

Python

import os, requests

r = requests.post(
  "https://api.orbit.devotel.io/api/v1/whatsapp/messages/send-flow",
  headers={"X-API-Key": os.environ["ORBIT_API_KEY"]},
  json={
    "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",
  },
)
print(r.json()["data"]["status"])  # "sent"

package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/whatsapp/messages/send-flow", bytes.NewBuffer([]byte(`{
  "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"
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/whatsapp/messages/send-flow')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  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'
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/whatsapp/messages/send-flow');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
  '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',
]));
echo curl_exec($ch);

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.

cURL

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

Node.js

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

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

const analytics = await orbit.request("GET", "/whatsapp/test-account/analytics");
console.log(analytics.data);

Python

import os, requests

r = requests.get(
  "https://api.orbit.devotel.io/api/v1/whatsapp/test-account/analytics",
  headers={"X-API-Key": os.environ["ORBIT_API_KEY"]},
)
print(r.json()["data"])

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/whatsapp/test-account/analytics", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

Ruby

require 'net/http'

uri = URI('https://api.orbit.devotel.io/api/v1/whatsapp/test-account/analytics')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/whatsapp/test-account/analytics');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
]);
echo curl_exec($ch);

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

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

Node.js

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

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

const plan = await orbit.request("POST", "/whatsapp/cost-optimizer/plan", {
  budgetUsd: 25.0,
  sends: [
    {
      id: "msg-1",
      to: "+14155550123",
      eligibleCategories: ["utility", "marketing"],
      withinOpenWindow: true,
    },
  ],
});
console.log(plan.data.projectedSpendUsd, plan.data.savingsUsd);

Python

import os, requests

r = requests.post(
  "https://api.orbit.devotel.io/api/v1/whatsapp/cost-optimizer/plan",
  headers={"X-API-Key": os.environ["ORBIT_API_KEY"]},
  json={
    "budgetUsd": 25.0,
    "sends": [
      {
        "id": "msg-1",
        "to": "+14155550123",
        "eligibleCategories": ["utility", "marketing"],
        "withinOpenWindow": True,
      }
    ],
  },
)
print(r.json()["data"]["projectedSpendUsd"], r.json()["data"]["savingsUsd"])

package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/whatsapp/cost-optimizer/plan", bytes.NewBuffer([]byte(`{
  "budgetUsd": 25.0,
  "sends": [
    {
      "id": "msg-1",
      "to": "+14155550123",
      "eligibleCategories": ["utility", "marketing"],
      "withinOpenWindow": true
    }
  ]
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/whatsapp/cost-optimizer/plan')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  budgetUsd: 25.0,
  sends: [
    {
      id: 'msg-1',
      to: '+14155550123',
      eligibleCategories: ['utility', 'marketing'],
      withinOpenWindow: true
    }
  ]
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/whatsapp/cost-optimizer/plan');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
  'budgetUsd' => 25.0,
  'sends' => [
    [
      'id' => 'msg-1',
      'to' => '+14155550123',
      'eligibleCategories' => ['utility', 'marketing'],
      'withinOpenWindow' => true,
    ],
  ],
]));
echo curl_exec($ch);

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.

Verify WhatsApp events on your server

The events those sends produce (message status, inbound replies, button_reply, nfm_reply, order) arrive at your own webhook endpoint signed with your webhook secret. Verify the signature header before trusting the body, and dedupe on the webhook id so a retried delivery never double-processes — the full verifier and retry semantics are in Build your first webhook receiver; the WhatsApp-specific receiver is:

import crypto from "node:crypto";
import express from "express";

const app = express();
// Keep the raw body: the HMAC is computed over the exact bytes Orbit signed.
app.use(express.json({ verify: (req, _res, buf) => { req.rawBody = buf; } }));

const seen = new Set(); // back with Redis or your store in production

app.post("/webhooks/orbit", (req, res) => {
  const signature = req.headers["x-orbit-webhook-signature"];
  const webhookId = req.headers["x-webhook-id"];

  const expected = crypto
    .createHmac("sha256", process.env.ORBIT_WEBHOOK_SECRET)
    .update(req.rawBody)
    .digest("hex");

  if (!signature || signature !== expected) {
    return res.sendStatus(401); // reject unsigned or tampered deliveries
  }
  if (seen.has(webhookId)) {
    return res.sendStatus(200); // retry of an already-processed delivery
  }
  seen.add(webhookId);

  const event = req.body;
  if (event.event === "message.received" && event.channel === "whatsapp") {
    saveInbound({
      from: event.message.from,     // the recipient's WhatsApp number
      text: event.message.text ?? "",
    });
  }

  res.sendStatus(200);
});

import hashlib
import hmac
import os

from flask import Flask, request

app = Flask(__name__)
seen = set()  # back with Redis or your store in production


@app.post("/webhooks/orbit")
def handle_webhook():
    signature = request.headers.get("X-Orbit-Webhook-Signature")
    webhook_id = request.headers.get("X-Webhook-Id")

    expected = hmac.new(
        os.environ["ORBIT_WEBHOOK_SECRET"].encode(),
        request.get_data(),  # exact bytes Orbit signed
        hashlib.sha256,
    ).hexdigest()

    if not signature or not hmac.compare_digest(signature, expected):
        return "", 401  # reject unsigned or tampered deliveries
    if webhook_id in seen:
        return "", 200  # retry of an already-processed delivery
    seen.add(webhook_id)

    event = request.get_json() or {}
    if event.get("event") == "message.received" and event.get("channel") == "whatsapp":
        message = event.get("message") or {}
        save_inbound(from_=message.get("from"), text=message.get("text", ""))

    return "", 200

Reply 200 quickly and queue the work; the same delivery semantics and retry schedule as every other Orbit webhook apply. event.channel === "whatsapp" separates WhatsApp traffic from your other channels on a shared endpoint.

Quick check — read your current profile

The fastest smoke test for a fresh API key is the business-profile read — run the GET /whatsapp/business-profile sample from the Business profile section in any of the six languages; a 200 with your org’s about line confirms the key, the tenant mapping, and the WABA connection in one round trip.

API Reference

All Endpoints

WhatsApp API: WABA, profile, catalogs, and Flows

WhatsApp API

Send a template message

Using the SDKs

Connections

200 sample — list connections

Business profile

200 sample — read 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

Marketing template sends

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

Verify WhatsApp events on your server

Quick check — read your current profile

See also

​WhatsApp API

​Send a template message

​Using the SDKs

​Connections

​200 sample — list connections

​Exchange the Embedded Signup code

​Business profile

​200 sample — read 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

​Marketing template sends

​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

​Verify WhatsApp events on your server

​Quick check — read your current profile

​See also

WhatsApp API

Send a template message

Using the SDKs

Connections

200 sample — list connections

Exchange the Embedded Signup code

Business profile

200 sample — read 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

Marketing template sends

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

Verify WhatsApp events on your server

Quick check — read your current profile

See also