Per-language recipes

The Quickstart and each SDK page show you a first send. This guide collects the four ways that loop completes on a server integration — send a message and consume its delivery webhook, batch-send with an idempotent backoff loop for 429s, run the OTP send/check round trip, and read paginated usage/deliverability — each with a cURL tab plus Python, Go, Ruby, PHP, Java, and C#. Each snippet ends by accessing the response fields idiomatically (dict access in Python, map access in Go, hash dig in Ruby, array access in PHP, result.get(...) in Java, TryGetProperty in C#). A second section below — Client-side loops — covers the mobile and browser SDKs (push device tokens, in-app chat, web personalization). Where the SDK’s typed scope stops, the language’s escape hatch (client.request / client.Request / $client->request / client.RequestAsync) takes over, and the per-language round trips on batch sends carry a pinned Idempotency-Key, so a retry reads as the sender’s own loop rather than an outright retry — the same provision the rest of the coding surface accepts.

Typed helpers exist on every SDK for messaging (send), voice, and verify send/check. The batch send, the analytics read, and the DLR webhook ingest go through each SDK’s generic request helper — client.request / client.Request / $client->request / client.RequestAsync — against the canonical POST /api/v1/messages/batch and GET /api/v1/analytics/messages routes. Scope per language is on the SDK index.

1. Messages — send, then consume the delivery webhook

POST /api/v1/messages/sms returns the message id immediately; delivery then reports back as a webhook event (message.delivered / message.failed on the endpoint you register in Settings → Webhooks). The first snippet of each tab sends and keeps the id; the second is the raw ingest loop the events arrive on — subscription list message.delivered, message.failed, and the per-language signed-body check (verify the X-Orbit-Signature header with the raw body before parsing, same contract as every event; a full handler per language is at Verify webhook signatures). Response fields: data.id (the msg_... handle) and data.status.

# Send:
curl -X POST https://api.orbit.devotel.io/api/v1/messages/sms \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-conf-98421" \
  -d '{ "to": "+14155552671", "body": "Your order 98421 shipped." }'

# DLR webhook raw ingest (e.g. a Flask-style route returning 200 on match):
RAW=$(</dev/stdin)   # read the raw request body first — HMAC needs the bytes verbatim
SIG=$(echo -n "$RAW" | openssl dgst -sha256 -hmac "$ORBIT_WEBHOOK_SECRET" | awk '{print $2}')
[[ "$SIG" == "$HTTP_X_ORBIT_SIGNATURE" ]] || { echo "bad signature"; exit 1; }
# then parse $RAW and branch on event.type: message.delivered | message.failed

message = client.messages.send_sms(to="+14155552671", body="Your order 98421 shipped.")
print("message id:", message["data"]["id"])

# DLR webhook raw ingest — the second leg of this loop:
from orbit_sdk import verify_webhook

@app.post("/webhooks/orbit")
def handler(request):
    event = verify_webhook(
        payload=request.body,
        signature=request.headers["X-Orbit-Signature"],
        secret=os.environ["ORBIT_WEBHOOK_SECRET"],
    )
    if event["type"] in ("message.delivered", "message.failed"):
        log(event["type"], event["data"]["id"])
    return Response(status=200)

msg, err := client.Messages().SendSMS(context.Background(), orbit.SendSMSInput{
    To:   "+14155552671",
    Body: "Your order 98421 shipped.",
})
fmt.Println("message id:", msg.Data.ID)

// DLR webhook raw ingest — the second leg of this loop:
event, err := orbit.VerifyWebhook(rawBody, signatureHeader, webhookSecret, 0, time.Time{})
// switch event.Type { case "message.delivered": case "message.failed": }

msg = client.messages.send_sms(to: "+14155552671", body: "Your order 98421 shipped.")
puts "message id: #{msg.dig("data", "id")}"

# DLR webhook raw ingest — the second leg of this loop:
event = OrbitSdk::Webhooks.verify(payload: raw_body, signature: sig, secret: ENV["ORBIT_WEBHOOK_SECRET"])
case event["type"]
when "message.delivered", "message.failed"
  log(event["data"]["id"])
end

$msg = $client->messages->sendSms('+14155552671', 'Your order 98421 shipped.');
echo $msg['data']['id'], PHP_EOL;

// DLR webhook raw ingest — the second leg of this loop:
$event = Webhooks::verify(payload: $rawBody, signature: $sig, secret: $_ENV['ORBIT_WEBHOOK_SECRET']);
if (in_array($event['type'], ['message.delivered', 'message.failed'], true)) {
    log($event['data']['id']);
}

Map<String, Object> msg = client.messages.sendSms("+14155552671", "Your order 98421 shipped.");
System.out.println(((Map<?, ?>) msg.get("data")).get("id"));

// DLR webhook raw ingest — the second leg of this loop:
Map<String, Object> event = Webhooks.verify(rawBody, signatureHeader, webhookSecret);
// branch on event.get("type") — message.delivered | message.failed

var msg = await client.Messages.SendSmsAsync(to: "+14155552671", body: "Your order 98421 shipped.");
Console.WriteLine(msg.GetProperty("data").GetProperty("id").GetString());

// DLR webhook raw ingest — the second leg of this loop:
var eventObj = Webhooks.Verify(rawBody, signatureHeader, webhookSecret);
// read eventObj.Type (or branch on the JSON root) — message.delivered | message.failed

UI wiring aside, the DLR itself is a webhook on your registered endpoint — nothing about the send changes; subscribe the endpoint, then teach your handler to keep the message id (from send) through the event’s data.id so retries thread back to the same record. The full event list is Webhook events; the send contract (routing, from overrides, MMS) is on the Messaging API.

2. Batch — bulk-send with a pinned-key 429 loop

POST /api/v1/messages/batch bulk-sends one channel (SMS, WhatsApp, email, RCS, …) to up to 10,000 recipients per call with per-row variables, returning a per-recipient outcome map (HTTP 207 when any row fails) with Idempotency-Key dedup for retries. The snippets below fold the backoff in: an explicit Idempotency-Key pinned on the entire round trip, then on 429 honor the server-named wait (retry_after in the envelope, Retry-After header) before sleeping and re-packing the same key — so the sender’s own loop, not a second-op retry, is what runs on a throttle. Every language below reaches the same canonical route through its escape hatch — client.request in Python/Ruby/PHP, client.Request in Go, client.request in Java, client.RequestAsync in C# — passing /messages/batch relative to the /api/v1 base the SDK prefixes. Response shape: per-recipient data.results[] array with individual statuses and a data.summary counter.

batch_json() { curl -s -X POST https://api.orbit.devotel.io/api/v1/messages/batch -H "X-API-Key: $ORBIT_API_KEY" -H "Idempotency-Key: campaign-42-attempt-1" -H "Content-Type: application/json" -d "$1"; }
RESP=$(batch_json '{"channel":"sms","messages":[{"to":"+14155552671","body":"hi","variables":{"first_name":"Ada"}}]}')
CODE=$? # or parse HTTP status; on 429, wait $(echo "$RESP" | jq -r '.error.retry_after // header')s, then batch_json "$PAYLOAD" with the SAME key

for attempt in range(4):
    try:
        batch = client.request("POST", "/messages/batch",
            idempotency_key="campaign-42-attempt-1",
            json_body={"channel": "sms", "messages": [{"to": "+14155552671", "body": "Order shipped", "variables": {"first_name": "Ada"}}]},
        )
        break  # any rate limit on this round throws below, not here
    except OrbitRateLimitError as exc:
        time.sleep(exc.retry_after or 5)  # the pinned key rides through on the next attempt too
        continue

var batch map[string]any
body := map[string]any{"channel": "sms", "messages": []map[string]any{{"to": "+14155552671", "body": "Order shipped", "variables": map[string]any{"first_name": "Ada"}}}}
for attempt := 1; attempt <= 4; attempt++ {
    err := client.Request(ctx, "POST", "/messages/batch", nil, body, &batch, "campaign-42-attempt-1")
    if err == nil { break }
    if orbit.IsRateLimit(err) {
        wait := err.(*orbit.Error).RetryAfter
        if wait <= 0 { wait = 5 }
        time.Sleep(time.Duration(wait) * time.Second)
        continue
    }
    return err  // non-429 throws the full damage in
}

batch = nil
4.times do
  begin
    batch = client.request("POST", "/messages/batch",
      idempotency_key: "campaign-42-attempt-1",
      json_body: { channel: "sms", messages: [{ to: "+14155552671", body: "Order shipped", variables: { first_name: "Ada" } }] })
    break
  rescue OrbitSdk::OrbitRateLimitError => err # or the language's throttled class; read its retry-after accessor
    sleep(err.retry_after || 5)
    next
  end
end

for ($attempt = 1; $attempt <= 4; $attempt++) {
    try {
        $batch = $client->request('POST', '/messages/batch', null, [
            'channel' => 'sms',
            'messages' => [['to' => '+14155552671', 'body' => 'Order shipped', 'variables' => ['first_name' => 'Ada']]],
        ], 'campaign-42-attempt-1');
        break;
    } catch (OrbitRateLimitError $err) { // throttled — the key stays pinned for the retry
        usleep(($err->retryAfter ?? 5) * 1_000_000);
        continue;
    }
}

Map<String, Object> body = Map.of(
    "channel", "sms",
    "messages", List.of(Map.of("to", "+14155552671", "body", "Order shipped", "variables", Map.of("first_name", "Ada")))
);
Map<String, Object> batch = null;
for (int attempt = 1; attempt <= 4; attempt++) {
    try {
        batch = client.request("POST", "/messages/batch", null, body, "campaign-42-attempt-1", null);
        break;
    } catch (OrbitRateLimitError err) {           // 429 — honor the named wait, keep the key
        long wait = err.retryAfter != null ? err.retryAfter.getSeconds() : 5;
        Thread.sleep(wait * 1_000);
        continue;
    }
}

var body = new Dictionary<string, object?>
{
    ["channel"] = "sms",
    ["messages"] = new List<Dictionary<string, object?>>
    {
        new() { ["to"] = "+14155552671", ["body"] = "Order shipped", ["variables"] = new Dictionary<string, object?> { ["first_name"] = "Ada" } },
    },
};
Dictionary<string, object?> batch = null;
for (var attempt = 1; attempt <= 4; attempt++)
{
    try
    {
        batch = await client.RequestAsync("POST", "/messages/batch", jsonBody: body, idempotencyKey: "campaign-42-attempt-1");
        break;
    }
    catch (OrbitRateLimitError err)        // the wait is err.RetryAfterSeconds when the API names one
    {
        await Task.Delay(((int?)err.RetryAfterSeconds ?? 5) * 1_000);
        continue;
    }
}

The pinned Idempotency-Key is what makes the loop safe — a retry replays your original 207/200 envelope for 24 h on success codes instead of enqueueing a second batch, so a throttle inside your own loop never double-charges a row. The other failure posture lives below — SDK wide, the same pattern awaits any 429 (send, verify, batch); the full retry-wrapper shape (capped exponential fallback where the server named no wait) is at API error handling by example. The batch contract — per-row variables, the 207 map, RCS/WhatsApp channels — is on the Messaging API.

3. Verify — OTP round trip

Send the code with POST /api/v1/verify/send, keep the returned id, and check what the user typed with POST /api/v1/verify/check. Every SDK wraps both calls typed — the loop closes in two taps either way, and a wrongly-typed or expired code comes back valid: false on the second, never raising for a bad guess (that posture only holds on transport/auth failures). Response fields: data.valid, data.status (approved when the code matches).

# 1. Send
curl -X POST https://api.orbit.devotel.io/api/v1/verify/send \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "to": "+14155552671", "channel": "sms" }'

# 2. Check — the id send returned, plus the code the user typed:
curl -X POST https://api.orbit.devotel.io/api/v1/verify/check \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "verification_id": "ver_01hxyz", "code": "482901" }'

sent = client.verify.send(to="+14155552671", channel="sms")
result = client.verify.check(verification_id=sent["data"]["id"], code="482901")
print("valid:", result["data"]["valid"])     # True
print("status:", result["data"]["status"])   # 'approved'

sent, err := client.Verify().Send(context.Background(), "+14155552671", "sms")
check, err := client.Verify().Check(context.Background(), sent.Data.ID, "482901")
fmt.Println("valid:", check.Data.Valid)      // true
fmt.Println("status:", check.Data.Status)    // "approved"

sent = client.verify.send(to: "+14155552671", channel: "sms")
result = client.verify.check(verification_id: sent.dig("data", "id"), code: "482901")
puts "valid: #{result.dig("data", "valid")}"     # true
puts "status: #{result.dig("data", "status")}"   # 'approved'

$sent = $client->verify->send('+14155552671', 'sms');
$result = $client->verify->check($sent['data']['id'], '482901');
echo 'valid: '.($result['data']['valid'] ? 'true' : 'false').PHP_EOL;  // true
echo 'status: '.$result['data']['status'].PHP_EOL;                     // 'approved'

Map<String, Object> sent = client.verify.send("+14155552671", "sms");
String verificationId = (String) ((Map<?, ?>) sent.get("data")).get("id");
Map<String, Object> result = client.verify.check(verificationId, "482901");
Map<?, ?> data = (Map<?, ?>) result.get("data");
System.out.println("valid: " + data.get("valid"));      // true
System.out.println("status: " + data.get("status"));    // "approved"

var sent = await client.Verify.SendAsync(to: "+14155552671", channel: "sms");
var verificationId = sent.GetProperty("data").GetProperty("id").GetString();
var check = await client.Verify.CheckAsync(verificationId!, code: "482901");
var data = check.GetProperty("data");
Console.WriteLine($"valid: {data.GetProperty("valid").GetBoolean()}");   // True
Console.WriteLine($"status: {data.GetProperty("status").GetString()}");  // "approved"

Re-send and detail posture are on the same endpoint — approved is the only pass, failed re-checks against the same id until attempts_remaining bottoms out, expired re-sends. The full resend/expire contract is at the Verify API reference; the OTP step-by-step for a fresh install (without an SDK) is at Verify integration without our SDK.

4. Usage — paginated usage/deliverability read

GET /api/v1/analytics/messages returns aggregate delivery metrics (totals + time-series) your invoice and carrier-degradation checks hang off — bucket the series with group_by (hour, day, week, month) and page large ranges by splitting the date window. It has no typed helper in any SDK, so each language reads it through its escape hatch — the same low-level call the languages already use for uncovered routes. Response fields: data.totals.delivery_rate, data.totals.total_sent, data.time_series. Aggregation runs against a read replica, so reporting traffic never contends with the live send path.

curl -G https://api.orbit.devotel.io/api/v1/analytics/messages \
  -H "X-API-Key: $ORBIT_API_KEY" \
  --data-urlencode "channel=sms" \
  --data-urlencode "status=delivered" \
  --data-urlencode "start_date=2026-05-01T00:00:00Z" \
  --data-urlencode "end_date=2026-05-08T00:00:00Z" \
  --data-urlencode "group_by=day"

report = client.request(
    "GET", "/analytics/messages",
    params={
        "channel": "sms", "status": "delivered",
        "start_date": "2026-05-01T00:00:00Z", "end_date": "2026-05-08T00:00:00Z",
        "group_by": "day",
    },
)
print("delivery rate:", report["data"]["totals"]["delivery_rate"])
print("total sent:", report["data"]["totals"]["total_sent"])

query := url.Values{
    "channel":    {"sms"},
    "status":     {"delivered"},
    "start_date": {"2026-05-01T00:00:00Z"},
    "end_date":   {"2026-05-08T00:00:00Z"},
    "group_by":   {"day"},
}
var report map[string]any
err := client.Request(context.Background(), "GET", "/analytics/messages", query, nil, &report, "")
totals := report["data"].(map[string]any)["totals"].(map[string]any)
fmt.Println("delivery rate:", totals["delivery_rate"])

report = client.request("GET", "/analytics/messages", query: {
  channel: "sms", status: "delivered",
  start_date: "2026-05-01T00:00:00Z", end_date: "2026-05-08T00:00:00Z",
  group_by: "day",
})
puts "delivery rate: #{report.dig('data', 'totals', 'delivery_rate')}"
puts "total sent: #{report.dig('data', 'totals', 'total_sent')}"

$report = $client->request('GET', '/analytics/messages', [
    'channel' => 'sms', 'status' => 'delivered',
    'start_date' => '2026-05-01T00:00:00Z', 'end_date' => '2026-05-08T00:00:00Z',
    'group_by' => 'day',
]);
echo 'delivery rate: '.$report['data']['totals']['delivery_rate'].PHP_EOL;
echo 'total sent: '.$report['data']['totals']['total_sent'].PHP_EOL;

Map<String, Object> query = new LinkedHashMap<>();
query.put("channel", "sms");
query.put("status", "delivered");
query.put("start_date", "2026-05-01T00:00:00Z");
query.put("end_date", "2026-05-08T00:00:00Z");
query.put("group_by", "day");
Map<String, Object> report = client.request("GET", "/analytics/messages", query, null, null);
Map<?, ?> totals = (Map<?, ?>) ((Map<?, ?>) report.get("data")).get("totals");
System.out.println("delivery rate: " + totals.get("delivery_rate"));
System.out.println("total sent: " + totals.get("total_sent"));

var query = new Dictionary<string, object?>
{
    ["channel"] = "sms",
    ["status"] = "delivered",
    ["start_date"] = "2026-05-01T00:00:00Z",
    ["end_date"] = "2026-05-08T00:00:00Z",
    ["group_by"] = "day",
};
var report = await client.RequestAsync("GET", "/analytics/messages", query: query);
var totals = report.GetProperty("data").GetProperty("totals");
Console.WriteLine($"delivery rate: {totals.GetProperty("delivery_rate").GetDouble()}");
Console.WriteLine($"total sent: {totals.GetProperty("total_sent").GetInt64()}");

All analytics calls share a 60-request/minute budget per tenant and require the analytics:read scope; cursor pagination (meta.pagination) only applies to list endpoints — bucket the rollup time-series with group_by and page by splitting the date window. The per-surface analytics read (the dashboard’s delivery panel pulls the same) and the full parameter matrix are on the Analytics page.

Client-side loops

The four sections above cover the server-language SDKs. The recipes below are the client-side counterpart — the parts of the loop a mobile or browser app runs against Orbit’s end-user surfaces with a publishable key (dv_live_pk_…): register and track a push device token, connect an in-app chat client with a 429-aware send loop, and resolve a personalization slot in the web SDK. Each recipe closes with the escape-hatch provision — for the client SDKs that is the per-call idempotencyKey parameter every send method accepts — and ends by accessing the response or event fields idiomatically (struct fields in Kotlin and Swift, Dart strong types, JS property access in React Native and the browser).

Device-token registration runs in your backend with a secret key — client SDKs never hold one. Each client SDK page — Flutter, Android, iOS, React Native — carries a pre-publish, source-only note; vendor from the monorepo until the first public package publishes.

5. Push — register a device token, then check delivery

Register the device’s FCM/APNs token from your backend with the secret key (POST /api/v1/push/device-tokens on the REST surface; the Node SDK wraps it as orbit.push.tokens.register — an upsert which refreshes last-seen on every token rollover), then list the contact’s tokens (GET /api/v1/push/tokens, or the SDK’s push.tokens.iter iterator) to confirm which platforms became reachable. The mobile tabs show the server-side call the app triggers below — fifth tab = the browser path. The full request/response contract, including DELETE on sign-out, is in the Push reference.

Flutter (Dart)
Android (Kotlin)
iOS (Swift)
React Native (JS)
Web (browser)

// Backend route your app calls on FCM/APNs token rollover (Node SDK):
import { Devotel } from '@devotel-orbit/node';
const orbit = new Devotel({ apiKey: process.env.ORBIT_API_KEY });

app.post('/push/register', async (req, reply) => {
  const { contactId, platform, token } = req.body; // 'android' | 'ios'
  const registered = await orbit.push.tokens.register({
    contact_id: contactId,
    platform,
    token,
  });
  reply.send({ deviceTokenId: registered.data.id });

  // Delivery check — auto-paginating iterator over the registered tokens:
  let platforms = [];
  for await (const t of orbit.push.tokens.iter({ contact_id: contactId })) {
    platforms.push(t.platform);
  }
  reply.send({ platforms });
});

// app.post("/push/register", ...) — your backend (Node SDK):
// FCM tokens rotate; registration is an upsert, so call on every rollover.
const registered = await orbit.push.tokens.register({
  contact_id: contactId,
  platform: "android",
  token: fcmToken,
});
res.json({ deviceTokenId: registered.data.id });

// Delivery check — iterate the registered tokens for the contact:
const platforms = [];
for await (const t of orbit.push.tokens.iter({ contact_id: contactId })) {
  platforms.push(t.platform);
}
res.json({ platforms });

// app.post("/push/register", ...) — your backend (Node SDK):
const registered = await orbit.push.tokens.register({
  contact_id: contactId,
  platform: "ios",         // APNs device token
  token: apnsToken,
});
res.json({ deviceTokenId: registered.data.id });

// Delivery check — iterate the registered tokens for the contact:
const platforms = [];
for await (const t of orbit.push.tokens.iter({ contact_id: contactId })) {
  platforms.push(t.platform);
}
res.json({ platforms });

// app.post("/push/register", ...) — your backend (Node SDK):
const registered = await orbit.push.tokens.register({
  contact_id: body.contactId,
  platform: body.platform, // "android" or "ios" off the app
  token: body.token,
});
res.json({ deviceTokenId: registered.data.id });

// Delivery check — iterate the registered tokens for the contact:
const platforms = [];
for await (const t of orbit.push.tokens.iter({ contact_id: body.contactId })) {
  platforms.push(t.platform);
}
res.json({ platforms });

// Web Push doesn't need a backend hop — the browser SDK registers the
// PushSubscription envelope directly with the publishable key:
import { OrbitPush } from '@devotel-orbit/web';

if (OrbitPush.isSupported()) {
  const push = new OrbitPush({
    publicKey: 'dv_live_pk_…',
    vapidPublicKey: VAPID_PUBLIC_KEY,
  });
  const registration = await push.register(); // null on permission denial
  if (registration) {
    console.log('device token:', registration.deviceTokenId);
    console.log('endpoint:', registration.subscription.endpoint);
  }
}

6. Chat — connect, send with optimistic echo, handle 429

Construct the client with a publishable key, subscribe handlers before connect(), and branch on the typed error. A 429 carries the server-parsed Retry-After on a named field — wait it out instead of hammering the send loop; widened slightly per language below, then deduplicated with a pinned key.

Flutter (Dart)
Android (Kotlin)
iOS (Swift)
React Native (JS)
Web (browser)

import 'package:orbit_flutter/orbit_chat.dart';

final chat = OrbitChatClient(
  publicKey: 'dv_live_pk_…',
  storage: myOrbitStorage,        // resume the conversation across launches
  appInfo: 'acme-flutter/2.3.1',
);
await chat.connect();

// Deduplicate your own retry loop with a pinned key — the per-call
// idempotency escape hatch:
final key = 'msg-${DateTime.now().microsecondsSinceEpoch}';
try {
  await chat.sendMessage('Where is my order?', idempotencyKey: key);
} on OrbitChatApiError catch (err) {
  if (err.statusCode == 429) {
    final wait = err.retryAfterSeconds; // int? — null when no header
    await Future.delayed(Duration(seconds: wait ?? 5));
    // retry with the SAME key — the server dedupes the echo
  }
}

import io.orbit.devotel.chat.OrbitApiError

try {
    // sendMessage optimistically echoes, then confirms.
    chat.sendMessage("Where is my order?")
} catch (err: OrbitApiError) {
    when (err.status) {
        429 -> {
            val wait = err.retryAfterSeconds   // Int? — null when no header
            delay((wait ?: 5) * 1000L)
        }
        401 -> // rotate the publishable key and construct a new client
        else -> println("orbit error: HTTP ${err.status}")
    }
}

import OrbitChat

do {
    // sendMessage optimistically echoes, then confirms.
    try await chat.sendMessage("Where is my order?")
} catch let err as OrbitAPIError {
    switch err.status {
    case 429:
        let wait = err.retryAfterSeconds   // Int? — nil when no header
        try? await Task.sleep(nanoseconds: UInt64(wait ?? 5) * 1_000_000_000)
    case 401:
        // rotate the publishable key, build a new client
        break
    default:
        print("orbit error: HTTP \(err.status)")
    }
}

import { OrbitApiError } from "@devotel-orbit/react-native";

try {
  // sendMessage optimistically echoes, then confirms.
  await chat.sendMessage("Where is my order?");
} catch (err) {
  if (err instanceof OrbitApiError && err.status === 429) {
    // Property is an own-property only when the server sent Retry-After.
    const wait = "retryAfterSeconds" in err ? err.retryAfterSeconds : 5;
    await new Promise((r) => setTimeout(r, (wait ?? 5) * 1000));
  }
}

// The drop-in OrbitChat widget owns the send loop end to end. When you
// drive the same conversations API yourself, config option names differ
// per surface — the widget uses baseUrl, OrbitPersonalization uses
// apiUrl:
import { OrbitChat } from '@devotel-orbit/web';

const chat = new OrbitChat({
  publicKey: 'dv_live_pk_…',
  baseUrl: 'https://api.orbit.devotel.io/api/v1',
  agentName: 'Support',
});
chat.mount();

7. Web — fetch a personalization slot and inject markup

GET /sdk/personalize resolves one slot for the current visitor: it reads the visitor’s segment off their contact-score record, picks the highest-priority active variant (segment-specific first, slot default as fallback), and returns content / cta_url / cta_text / variant. The web SDK’s getPersonalization(slot) returns a generic empty default on non-OK or timeout — and render(slot, element, { html: true }) only opts into HTML injection when the server-side variant markup passed the markup validation (scripts and inline handlers are rejected with 422 at variant write time, so check the variant save response rather than assuming the slot renders). The end-to-end setup — slots, segments, lift — is in the Personalize website content guide.

Web (browser)
cURL

import { OrbitPersonalization } from '@devotel-orbit/web';

const personalization = new OrbitPersonalization({
  publicKey: 'dv_live_pk_…',
  apiUrl: 'https://api.orbit.devotel.io',
});
await personalization.identify({ email: 'user@example.com' });

// One call resolves and injects (render() awaits getPersonalization
// internally). html opts in explicitly — variants whose markup failed
// the server-side 422 validation at write time never reach visitors.
await personalization.render('hero-banner', '#hero', { html: true });

// Or resolve the payload yourself and decide:
const payload = await personalization.getPersonalization('hero-banner');
// payload.segment (or null when unknown), payload.content,
// payload.cta_url / payload.cta_text, payload.variant

curl -G https://api.orbit.devotel.io/sdk/personalize \
  -H "X-API-Key: dv_live_pk_..." \
  --data-urlencode "slot=hero-banner" \
  --data-urlencode "anonymous_id=anon_abc123"

Response fields: data.slot, data.segment (null for unknown visitors), data.content, data.cta_url, data.cta_text, data.variant (null when the generic default resolved). Cache guidance: the endpoint sends Cache-Control: private, max-age=60, stale-while-revalidate=120, so browser fetchers may serve a minute-old variant while refreshing in the background.

WhatsApp

Developer console

Contact center

Guides

Messaging Controls

Audience & Support Tools

Per-language recipes: message + DLR webhooks, batch, OTP verify, and deliverability past first send

Per-language recipes

1. Messages — send, then consume the delivery webhook

2. Batch — bulk-send with a pinned-key 429 loop

3. Verify — OTP round trip

4. Usage — paginated usage/deliverability read

Client-side loops

5. Push — register a device token, then check delivery

6. Chat — connect, send with optimistic echo, handle 429

7. Web — fetch a personalization slot and inject markup

​Per-language recipes

​1. Messages — send, then consume the delivery webhook

​2. Batch — bulk-send with a pinned-key 429 loop

​3. Verify — OTP round trip

​4. Usage — paginated usage/deliverability read

​Client-side loops

​5. Push — register a device token, then check delivery

​6. Chat — connect, send with optimistic echo, handle 429

​7. Web — fetch a personalization slot and inject markup

Per-language recipes

1. Messages — send, then consume the delivery webhook

2. Batch — bulk-send with a pinned-key 429 loop

3. Verify — OTP round trip

4. Usage — paginated usage/deliverability read

Client-side loops

5. Push — register a device token, then check delivery

6. Chat — connect, send with optimistic echo, handle 429

7. Web — fetch a personalization slot and inject markup