curl --request POST \
  --url https://api.orbit.devotel.io/api/v1/channels/amb/agents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "business_id": "apple:com.acme.store",
  "display_name": "Acme Store Support",
  "secret_key": "YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXo/AAECAwQFBg==",
  "msp_id": "orbit-msp-01",
  "status": "pending",
  "capabilities": {
    "text": true,
    "interactive": true,
    "applePay": false
  },
  "logo_url": "https://cdn.acme.example.org/logos/acme.png"
}
'

import requests

url = "https://api.orbit.devotel.io/api/v1/channels/amb/agents"

payload = {
    "business_id": "apple:com.acme.store",
    "display_name": "Acme Store Support",
    "secret_key": "YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXo/AAECAwQFBg==",
    "msp_id": "orbit-msp-01",
    "status": "pending",
    "capabilities": {
        "text": True,
        "interactive": True,
        "applePay": False
    },
    "logo_url": "https://cdn.acme.example.org/logos/acme.png"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    business_id: 'apple:com.acme.store',
    display_name: 'Acme Store Support',
    secret_key: 'YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXo/AAECAwQFBg==',
    msp_id: 'orbit-msp-01',
    status: 'pending',
    capabilities: {text: true, interactive: true, applePay: false},
    logo_url: 'https://cdn.acme.example.org/logos/acme.png'
  })
};

fetch('https://api.orbit.devotel.io/api/v1/channels/amb/agents', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.orbit.devotel.io/api/v1/channels/amb/agents",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'business_id' => 'apple:com.acme.store',
    'display_name' => 'Acme Store Support',
    'secret_key' => 'YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXo/AAECAwQFBg==',
    'msp_id' => 'orbit-msp-01',
    'status' => 'pending',
    'capabilities' => [
        'text' => true,
        'interactive' => true,
        'applePay' => false
    ],
    'logo_url' => 'https://cdn.acme.example.org/logos/acme.png'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://api.orbit.devotel.io/api/v1/channels/amb/agents"

	payload := strings.NewReader("{\n  \"business_id\": \"apple:com.acme.store\",\n  \"display_name\": \"Acme Store Support\",\n  \"secret_key\": \"YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXo/AAECAwQFBg==\",\n  \"msp_id\": \"orbit-msp-01\",\n  \"status\": \"pending\",\n  \"capabilities\": {\n    \"text\": true,\n    \"interactive\": true,\n    \"applePay\": false\n  },\n  \"logo_url\": \"https://cdn.acme.example.org/logos/acme.png\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.orbit.devotel.io/api/v1/channels/amb/agents")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"business_id\": \"apple:com.acme.store\",\n  \"display_name\": \"Acme Store Support\",\n  \"secret_key\": \"YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXo/AAECAwQFBg==\",\n  \"msp_id\": \"orbit-msp-01\",\n  \"status\": \"pending\",\n  \"capabilities\": {\n    \"text\": true,\n    \"interactive\": true,\n    \"applePay\": false\n  },\n  \"logo_url\": \"https://cdn.acme.example.org/logos/acme.png\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.orbit.devotel.io/api/v1/channels/amb/agents")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"business_id\": \"apple:com.acme.store\",\n  \"display_name\": \"Acme Store Support\",\n  \"secret_key\": \"YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXo/AAECAwQFBg==\",\n  \"msp_id\": \"orbit-msp-01\",\n  \"status\": \"pending\",\n  \"capabilities\": {\n    \"text\": true,\n    \"interactive\": true,\n    \"applePay\": false\n  },\n  \"logo_url\": \"https://cdn.acme.example.org/logos/acme.png\"\n}"

response = http.request(request)
puts response.read_body

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

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "status": 123,
    "details": {}
  },
  "meta": {
    "request_id": "<string>",
    "timestamp": "2023-11-07T05:31:56Z",
    "docs_url": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "status": 123,
    "details": {}
  },
  "meta": {
    "request_id": "<string>",
    "timestamp": "2023-11-07T05:31:56Z",
    "docs_url": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "status": 123,
    "details": {}
  },
  "meta": {
    "request_id": "<string>",
    "timestamp": "2023-11-07T05:31:56Z",
    "docs_url": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "status": 123,
    "details": {}
  },
  "meta": {
    "request_id": "<string>",
    "timestamp": "2023-11-07T05:31:56Z",
    "docs_url": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "status": 123,
    "details": {}
  },
  "meta": {
    "request_id": "<string>",
    "timestamp": "2023-11-07T05:31:56Z",
    "docs_url": "<string>"
  }
}

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "<string>",
    "status": 429,
    "retry_after": 2
  },
  "meta": {
    "request_id": "<string>",
    "timestamp": "2023-11-07T05:31:56Z",
    "docs_url": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "status": 123,
    "details": {}
  },
  "meta": {
    "request_id": "<string>",
    "timestamp": "2023-11-07T05:31:56Z",
    "docs_url": "<string>"
  }
}

Channels

Register an Apple Messages for Business agent

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.

POST

api

channels

amb

agents

curl --request POST \
  --url https://api.orbit.devotel.io/api/v1/channels/amb/agents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "business_id": "apple:com.acme.store",
  "display_name": "Acme Store Support",
  "secret_key": "YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXo/AAECAwQFBg==",
  "msp_id": "orbit-msp-01",
  "status": "pending",
  "capabilities": {
    "text": true,
    "interactive": true,
    "applePay": false
  },
  "logo_url": "https://cdn.acme.example.org/logos/acme.png"
}
'

import requests

url = "https://api.orbit.devotel.io/api/v1/channels/amb/agents"

payload = {
    "business_id": "apple:com.acme.store",
    "display_name": "Acme Store Support",
    "secret_key": "YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXo/AAECAwQFBg==",
    "msp_id": "orbit-msp-01",
    "status": "pending",
    "capabilities": {
        "text": True,
        "interactive": True,
        "applePay": False
    },
    "logo_url": "https://cdn.acme.example.org/logos/acme.png"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    business_id: 'apple:com.acme.store',
    display_name: 'Acme Store Support',
    secret_key: 'YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXo/AAECAwQFBg==',
    msp_id: 'orbit-msp-01',
    status: 'pending',
    capabilities: {text: true, interactive: true, applePay: false},
    logo_url: 'https://cdn.acme.example.org/logos/acme.png'
  })
};

fetch('https://api.orbit.devotel.io/api/v1/channels/amb/agents', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.orbit.devotel.io/api/v1/channels/amb/agents",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'business_id' => 'apple:com.acme.store',
    'display_name' => 'Acme Store Support',
    'secret_key' => 'YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXo/AAECAwQFBg==',
    'msp_id' => 'orbit-msp-01',
    'status' => 'pending',
    'capabilities' => [
        'text' => true,
        'interactive' => true,
        'applePay' => false
    ],
    'logo_url' => 'https://cdn.acme.example.org/logos/acme.png'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://api.orbit.devotel.io/api/v1/channels/amb/agents"

	payload := strings.NewReader("{\n  \"business_id\": \"apple:com.acme.store\",\n  \"display_name\": \"Acme Store Support\",\n  \"secret_key\": \"YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXo/AAECAwQFBg==\",\n  \"msp_id\": \"orbit-msp-01\",\n  \"status\": \"pending\",\n  \"capabilities\": {\n    \"text\": true,\n    \"interactive\": true,\n    \"applePay\": false\n  },\n  \"logo_url\": \"https://cdn.acme.example.org/logos/acme.png\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.orbit.devotel.io/api/v1/channels/amb/agents")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"business_id\": \"apple:com.acme.store\",\n  \"display_name\": \"Acme Store Support\",\n  \"secret_key\": \"YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXo/AAECAwQFBg==\",\n  \"msp_id\": \"orbit-msp-01\",\n  \"status\": \"pending\",\n  \"capabilities\": {\n    \"text\": true,\n    \"interactive\": true,\n    \"applePay\": false\n  },\n  \"logo_url\": \"https://cdn.acme.example.org/logos/acme.png\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.orbit.devotel.io/api/v1/channels/amb/agents")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"business_id\": \"apple:com.acme.store\",\n  \"display_name\": \"Acme Store Support\",\n  \"secret_key\": \"YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXo/AAECAwQFBg==\",\n  \"msp_id\": \"orbit-msp-01\",\n  \"status\": \"pending\",\n  \"capabilities\": {\n    \"text\": true,\n    \"interactive\": true,\n    \"applePay\": false\n  },\n  \"logo_url\": \"https://cdn.acme.example.org/logos/acme.png\"\n}"

response = http.request(request)
puts response.read_body

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

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "status": 123,
    "details": {}
  },
  "meta": {
    "request_id": "<string>",
    "timestamp": "2023-11-07T05:31:56Z",
    "docs_url": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "status": 123,
    "details": {}
  },
  "meta": {
    "request_id": "<string>",
    "timestamp": "2023-11-07T05:31:56Z",
    "docs_url": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "status": 123,
    "details": {}
  },
  "meta": {
    "request_id": "<string>",
    "timestamp": "2023-11-07T05:31:56Z",
    "docs_url": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "status": 123,
    "details": {}
  },
  "meta": {
    "request_id": "<string>",
    "timestamp": "2023-11-07T05:31:56Z",
    "docs_url": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "status": 123,
    "details": {}
  },
  "meta": {
    "request_id": "<string>",
    "timestamp": "2023-11-07T05:31:56Z",
    "docs_url": "<string>"
  }
}

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "<string>",
    "status": 429,
    "retry_after": 2
  },
  "meta": {
    "request_id": "<string>",
    "timestamp": "2023-11-07T05:31:56Z",
    "docs_url": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "status": 123,
    "details": {}
  },
  "meta": {
    "request_id": "<string>",
    "timestamp": "2023-11-07T05:31:56Z",
    "docs_url": "<string>"
  }
}

Authorizations

Authorization

string

header

required

Dashboard JWT token from Clerk

Headers

Idempotency-Key

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.

Required string length: 1 - 255

X-Test-Mode

enum<string>

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.

Available options:

true,

false

Body

application/json

business_id

string

required

Apple Business Register identifier for the business.

display_name

string

required

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

secret_key

string

required

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

msp_id

string

Optional Messaging Service Provider id override.

status

enum<string>

Approval state; defaults to pending when omitted.

Available options:

pending,

approved,

suspended

capabilities

object

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

logo_url

string<uri>

Optional HTTPS logo URL shown on the dashboard.

Response

One AMB agent record in data, plus the standard request meta envelope.

data

object

API Reference

All Endpoints

Register an Apple Messages for Business agent

Authorizations

Headers

Body

Response