Channels API

Channels endpoints exposed by the Devotel CPaaS API Base path: /api/v1/channels Endpoint count: 7

List Apple Messages for Business agents

GET /api/v1/channels/amb/agents

Return all Apple Messages for Business (AMB) agents registered on the tenant’s account, newest first (capped at 200 rows). Use this to render the channel-settings list, or to check approval status (pending → approved → suspended) and capability flags before enabling the AMB channel on the dashboard. Agent secret keys are encrypted at rest and never serialised — the response exposes only a has_secret boolean.

string (enum: true|false)

Sandbox opt-in for Clerk-session-authenticated requests. Set to true to route the call through the test-mode pipeline: no real provider delivery, no credits deducted, response meta.test_mode: true. Ignored for live API keys (dv_live_sk_*) — server-to-server clients must use a test-prefixed key (dv_test_sk_*) to exercise sandbox. Test-prefixed keys unconditionally enable sandbox regardless of this header.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/channels/amb/agents" \
  -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 res = await fetch('https://api.orbit.devotel.io/api/v1/channels/amb/agents', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/channels/amb/agents", headers=headers)
print(r.json())

package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/channels/amb/agents", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/channels/amb/agents')
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/channels/amb/agents');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),

]);

echo curl_exec($ch);

{
  "data": [
    {}
  ],
  "meta": {}
}

List WhatsApp Flows

GET /api/v1/channels/whatsapp/flows

Return the tenant’s Meta WhatsApp Flows (up to 100, newest first) — the inbox composer uses this to prepend a local-flow picker while a response to Meta’s completion webhook lands. Each record carries the remote Meta flow_id (from publishing a draft), the lifecycle status (draft/published/deprecated), the flow’s JSON schema, and the first screen’s id. Only authenticated workspace members may call this.

string (enum: true|false)

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/channels/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 res = await fetch('https://api.orbit.devotel.io/api/v1/channels/whatsapp/flows', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

Python

import os, requests

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

package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/channels/whatsapp/flows", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/channels/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/channels/whatsapp/flows');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),

]);

echo curl_exec($ch);

{
  "data": [
    {}
  ],
  "meta": {}
}

Register an Apple Messages for Business agent

POST /api/v1/channels/amb/agents

Create a new Apple Messages for Business (AMB) agent for the tenant. Supply the business_id issued by Apple Business Register plus the base64 secret_key Apple assigned to the agent; the secret is encrypted with the platform AES-256-GCM envelope before persisting and is never returned by any read endpoint. Optionally set approval status, capability flags (text, interactive, rich link, form, time picker, Apple Pay), and a logo_url shown on the dashboard. Audit trail entry amb.agent_created is recorded.

string

Stripe-style idempotency token. Pass a stable, client-generated value (1-255 chars) to dedupe retries on transient timeouts. The same key+credential+path replays the original response for 24h on 2xx (5min on 4xx, 30s on 5xx). Returns 409 if a concurrent request with the same key is already in flight; replayed responses include the Idempotency-Replay: true response header.

string (enum: true|false)

string

required

Apple Business Register identifier for the business.

string

required

Human-readable name for the agent (1–200 chars).

string

required

Base64 shared secret Apple assigned to the agent (16–2048 chars); encrypted before persistence.

string

Optional Messaging Service Provider id override.

string (enum: pending|approved|suspended)

Approval state; defaults to pending when omitted.

object

Capability flags approved by Apple (text, interactive, richLink, form, timePicker, applePay).

string

Optional HTTPS logo URL shown on the dashboard.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/channels/amb/agents" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "business_id": "string",
  "display_name": "string",
  "secret_key": "string"
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/channels/amb/agents', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "business_id": "string",
  "display_name": "string",
  "secret_key": "string"
}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/channels/amb/agents", headers=headers, json={
  "business_id": "string",
  "display_name": "string",
  "secret_key": "string"
})
print(r.json())

package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/channels/amb/agents", bytes.NewBuffer([]byte(`{
  "business_id": "string",
  "display_name": "string",
  "secret_key": "string"
}`)))
	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/channels/amb/agents')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  "business_id": "string",
  "display_name": "string",
  "secret_key": "string"
}.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/channels/amb/agents');
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
{
  "business_id": "string",
  "display_name": "string",
  "secret_key": "string"
}
JSON);
echo curl_exec($ch);

{
  "data": {},
  "meta": {}
}

Inbound Apple Messages for Business webhook

POST /api/v1/channels/amb/webhook

Receives inbound AMB messages (text, list-picker, form reply, time-picker, Apple Pay events) from Apple. Uses the Authorization: Bearer <jwt> header for HMAC verification per RFC 7515; the router performs a bounded cross-tenant candidate sweep over amb_business_registry and picks the tenant whose secret validates the JWS signing-input. Verified messages are persisted into the tenant inbox before this endpoint acknowledges with { accepted: true }. Persistence failures are logged but acknowledged (Apple retries aggressively on 4xx/5xx).

string

Legacy raw JWT (no Bearer prefix).

string

Apple message id header used as the persistence idempotency key when the body carries none.

string

string (enum: true|false)

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/channels/amb/webhook" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/channels/amb/webhook', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/channels/amb/webhook", headers=headers, json={})
print(r.json())

package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/channels/amb/webhook", bytes.NewBuffer([]byte(`{}`)))
	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/channels/amb/webhook')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {}.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/channels/amb/webhook');
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
{}
JSON);
echo curl_exec($ch);

{
  "data": {
    "accepted": false,
    "persisted": false,
    "message_id": null
  },
  "meta": {}
}

Inbound WhatsApp Flows completion webhook

POST /api/v1/channels/whatsapp/flows/endpoint

Receives a Meta Flow-completion event when a customer finishes a multi-step interactive Flow. Authenticates using the X-Devotel-Org-Id header (org id shape-validated, then the org’s WhatsApp connection credentials + flow private key are resolved). The request body is the Meta-endpoint envelope (encrypted_flow_data, data = ); the signature is HMAC-SHA256 over the raw body using the org’s app_secret. Payloads are persisted to <tenant>.whatsapp_flow_responses keyed to the matching flow. Returns the Meta-specified AES-128-GCM-encrypted JSON as text/plain (NOT the standard { data, meta } envelope); failure replies use the uniform 401 error envelope below.

string

Orbit organization id that owns the flow (required).

string

HMAC-SHA256 over the raw body using the org’s app_secret.

string

string (enum: true|false)

cURL

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

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/channels/whatsapp/flows/endpoint', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/channels/whatsapp/flows/endpoint", headers=headers, json={})
print(r.json())

package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/channels/whatsapp/flows/endpoint", bytes.NewBuffer([]byte(`{}`)))
	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/channels/whatsapp/flows/endpoint')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {}.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/channels/whatsapp/flows/endpoint');
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
{}
JSON);
echo curl_exec($ch);

"string"

Update an Apple Messages for Business agent

PATCH /api/v1/channels/amb/agents/{id}

Partially update an existing AMB agent — rename it, transition its status (approve / suspend), rotate the secret key (the replacement is encrypted before persisting), swap capability flags, or clear/set msp_id and logo_url. Only the fields sent are changed; omitted fields keep their previous value. The public registry mapping (business_id → tenant) is re-synced so inbound webhooks keep routing correctly. Audit trail entry amb.agent_updated is recorded.

string

required

The AMB agent id (UUID).

string (enum: true|false)

string

New name (1–200 chars).

string

Rotated base64 secret (16–2048 chars); encrypted at rest.

string | null

New MSP id, or null to clear.

string (enum: pending|approved|suspended)

Approval-state transition.

object

—

string | null

New HTTPS logo URL, or null to clear.

cURL

curl -X PATCH "https://api.orbit.devotel.io/api/v1/channels/amb/agents/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/channels/amb/agents/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3', {
  method: 'PATCH',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.patch("https://api.orbit.devotel.io/api/v1/channels/amb/agents/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3", headers=headers, json={})
print(r.json())

package main

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

func main() {
	req, _ := http.NewRequest("PATCH", "https://api.orbit.devotel.io/api/v1/channels/amb/agents/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3", bytes.NewBuffer([]byte(`{}`)))
	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/channels/amb/agents/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3')
req = Net::HTTP::Patch.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {}.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/channels/amb/agents/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{}
JSON);
echo curl_exec($ch);

{
  "data": {},
  "meta": {}
}

Delete an Apple Messages for Business agent

DELETE /api/v1/channels/amb/agents/{id}

Remove an AMB agent from the tenant and drop its business_id from the cross-tenant public registry (ownership is scoped to the organization) so inbound Apple Messages webhooks stop routing here. The response returns the deleted id plus deleted: true. Audit trail entry amb.agent_deleted is recorded.

string

required

The AMB agent id (UUID).

string (enum: true|false)

cURL

curl -X DELETE "https://api.orbit.devotel.io/api/v1/channels/amb/agents/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/channels/amb/agents/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3', {
  method: 'DELETE',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.delete("https://api.orbit.devotel.io/api/v1/channels/amb/agents/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3", headers=headers, json={})
print(r.json())

package main

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

func main() {
	req, _ := http.NewRequest("DELETE", "https://api.orbit.devotel.io/api/v1/channels/amb/agents/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3", bytes.NewBuffer([]byte(`{}`)))
	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/channels/amb/agents/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3')
req = Net::HTTP::Delete.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {}.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/channels/amb/agents/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{}
JSON);
echo curl_exec($ch);

{
  "data": {},
  "meta": {}
}

API Reference

All Endpoints

Channels API

Channels API

List Apple Messages for Business agents

List WhatsApp Flows

Register an Apple Messages for Business agent

Inbound Apple Messages for Business webhook

Inbound WhatsApp Flows completion webhook

Update an Apple Messages for Business agent

Delete an Apple Messages for Business agent

​Channels API

​List Apple Messages for Business agents

​List WhatsApp Flows

​Register an Apple Messages for Business agent

​Inbound Apple Messages for Business webhook

​Inbound WhatsApp Flows completion webhook

​Update an Apple Messages for Business agent

​Delete an Apple Messages for Business agent

Channels API

List Apple Messages for Business agents

List WhatsApp Flows

Register an Apple Messages for Business agent

Inbound Apple Messages for Business webhook

Inbound WhatsApp Flows completion webhook

Update an Apple Messages for Business agent

Delete an Apple Messages for Business agent