API recipes: third-party migrators

The five per-provider migration guides — Twilio, Sinch, MessageBird, Vonage, Infobip — each document the same five migrator loops with provider-specific names. This page is the template: the loops, the expected envelopes, and the branch you take on each outcome, with Twilio as the worked example. Write a connector for another provider (Telnyx, Klaviyo, Bandwidth) by substituting the source-side identifiers; the Orbit side of every loop is provider-agnostic. Base URL is https://api.orbit.devotel.io/api/v1 throughout; authenticate with X-API-Key (test key dv_test_sk_… against the sandbox, live key for a cutover).

These are tenant-owned controls. Orbit supplies and enforces the migration surface; your organization names the source resource (a Messaging Service SID, a LoA file, a webhook URL), owns the source credentials, and makes the go-live call. These recipes are not legal advice.

0. Automate the whole import instead

Five loops below are the code-level migrator; two higher-level surfaces wrap them for operators. Reach for the wizard when the source account’s configuration (numbers, messaging services, templates, contacts) should land on Orbit without hand-mapping; reach for the loops when you need to drive the mapping from your own script or CI pipeline.

Assisted import wizard — Settings → Import → Twilio (or Sinch / MessageBird / Vonage / Infobip) connects a read-only credential, shows a dry-run preview of what lands where, and commits with rollback. Neither the wizard nor the loops touch your live traffic; the existing provider keeps running until you cut over. Full walkthrough: Assisted import wizard.
devotel migrate CLI — the same wizard scriptable from a terminal or pipeline. Install with npm install -g @devotel/cli, devotel auth login, then devotel migrate twilio --account-sid AC… --auth-token … (dry run first; add --run to commit). Flag reference: Devotel CLI guide.

1. Resolve a Twilio Messaging Service SID into `messaging_service_id`

Twilio groups senders under a Messaging Service; Orbit models the same bundle as a messaging service — senders plus opt-out rules plus an inbound webhook — and a send carries it on messaging_service_id. The mapping is a one-line metadata.external_id on the Orbit service you create, so the old MessagingServiceSid=SM… your systems log stays resolvable. List the existing services to find the one your script will tag (or to skip creation when a prior run already landed):

cURL

curl "https://api.orbit.devotel.io/api/v1/messaging/services?limit=100" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

Create the Orbit service with the source id in metadata.external_id — the SID you used to pass to Twilio’s MessagingServiceSid parameter:

cURL

curl -X POST https://api.orbit.devotel.io/api/v1/messaging/services \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Transactional alerts (migrated)",
    "inbound_webhook_url": "https://your-app.example/hooks/orbit/inbound",
    "opt_out": {
      "keywords": ["STOP", "STOPALL", "UNSUBSCRIBE", "CANCEL", "END", "QUIT"],
      "reply": "You are unsubscribed from Acme alerts. Reply START to re-subscribe."
    },
    "metadata": {
      "external_id": "SM9f2a1c4b8d6e5f0a1b2c3d4e5f6a7b8c",
      "external_provider": "twilio"
    }
  }'

201 returns the created service — data.id (msg_svc_…) is the messaging_service_id every subsequent send carries:

201

{
  "data": {
    "id": "msg_svc_01HXV…",
    "name": "Transactional alerts (migrated)",
    "inbound_webhook_url": "https://your-app.example/hooks/orbit/inbound",
    "metadata": {
      "external_id": "SM9f2a1c4b8d6e5f0a1b2c3d4e5f6a7b8c",
      "external_provider": "twilio"
    }
  },
  "meta": { "request_id": "req_msg_svc_create", "timestamp": "2026-09-29T12:00:00.000Z" }
}

Bind the numbers you ported (loop 2) into the service so inbound SMS resolves to the right webhook:

cURL

curl -X POST https://api.orbit.devotel.io/api/v1/messaging/services/msg_svc_01HXV…/phone-numbers \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phone_number_id": "num_01J8Z9K" }'

Send against it the same way your Twilio send carried MessagingServiceSid:

cURL

curl -X POST https://api.orbit.devotel.io/api/v1/messages \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155552671",
    "channel": "sms",
    "messaging_service_id": "msg_svc_01HXV…",
    "body": "Acme: order 98421 shipped."
  }'

Re-resolve the SID to the Orbit id at cutover time — never bake msg_svc_… into your app; read GET /messaging/services once at startup, filter on metadata.external_id, and cache the mapping. Canonical pages: Messaging services console, Migration from Twilio.

2. Port the numbers with an Orbit-issued LoA URL

A port request must carry a Letter of Authorization. Orbit accepts only a LoA URL it issued itself, so you upload the signed PDF first (the upload returns a short-lived signed URL), then pass that URL as loaFileUrl. A link to your own bucket — https://storage.googleapis.com/your-loa-bucket/loa.pdf — is rejected 422 LOA_URL_INVALID_ORIGIN before the carrier sees it. Pre-check eligibility (one call per batch; catches a number another provider owns):

cURL

curl -X POST https://api.orbit.devotel.io/api/v1/numbers/porting/check \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "numbers": ["+14155551234", "+14155551235"] }'

Upload the signed LoA PDF — pass ttl_ms long enough for the carrier to fetch it (24 h here; the default is 1 h and a slow carrier will see an expired URL):

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/files/upload?ttl_ms=86400000" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -F "file=@./loa.pdf;type=application/pdf"

200

{
  "data": {
    "id": "file_01H…",
    "url": "https://storage.googleapis.com/orbit-uploads/file_01H/loa.pdf?X-Goog-Signature=…",
    "expires_at": "2026-09-30T12:00:00.000Z"
  }
}

Submit the port request with data.url from the upload:

cURL

curl -X POST https://api.orbit.devotel.io/api/v1/numbers/porting \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "numbers": ["+14155551234", "+14155551235"],
    "currentCarrier": "Twilio",
    "country": "US",
    "authorizedSigner": "Ada Lovelace",
    "accountNumber": "123456789",
    "accountPin": "1234",
    "loaFileUrl": "https://storage.googleapis.com/orbit-uploads/file_01H/loa.pdf?X-Goog-Signature=…"
  }'

201 returns data.id (prt_…). Ports complete with a carrier over 7–14 business days; track on GET /numbers/porting (one row per request) rather than polling porting/check. When the port lands, bind each new numbers row (it carries a num_… id) into the messaging service from loop 1. Canonical pages: Port numbers, First port walkthrough.

3. Rewire status callbacks into Orbit webhooks

Twilio POSTs form-encoded status callbacks to a statusCallback URL per message; Orbit emits a JSON envelope (message.delivered, message.failed, message.sent) to endpoints you register once under Settings → Webhooks. Subscribe to the event types, then re-point your handler — never translate the old per-message statusCallback URL field-for-field. Register the endpoint (once, tenant-wide):

cURL

curl -X POST https://api.orbit.devotel.io/api/v1/webhooks \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.example/hooks/orbit/status",
    "events": ["message.delivered", "message.failed", "message.sent"],
    "active": true
  }'

201 returns data.id (wh_…) plus a one-time data.secret (whsec_…) — store it; the signature check needs it. The source-side form-encoded body (MessageSid=SM…&MessageStatus=delivered&…) becomes a JSON event — verify X-Orbit-Signature (HMAC-SHA256 over the raw body) before trusting it:

message.delivered event

{
  "id": "evt_msg_001",
  "type": "message.delivered",
  "created_at": "2026-09-29T12:00:00Z",
  "data": {
    "message_id": "msg_abc123",
    "channel": "sms",
    "from": "+14155551234",
    "to": "+14155552671",
    "status": "delivered"
  }
}

Decision table for the verifier:

Source check	Orbit check
`twilio.validateRequest(authToken, signature, url, params)`	`verifyWebhookSignature(rawBody, signature, 'whsec_…')` from the Node SDK
`X-Twilio-Signature` header (HMAC-SHA1)	`X-Orbit-Signature` header (HMAC-SHA256); `X-Devotel-Signature` is legacy, not a build-target
Per-message `statusCallback` URL	One tenant-wide endpoint subscribed to `message.*` events

Canonical pages: Webhook events, Verify webhook signatures, Webhook endpoint operations.

4. Flip the source IVR XML into a published flow

TwiML is a one-response XML document; Orbit models IVRs as IVR flows — a { nodes, edges } graph the visual builder also saves. The mapping is a graph with exactly one ivrStart entry node, the prompts/transfers/hangups the XML declared, and no unreachable nodes. Create a draft, then publish it so inbound callers hit it. Create the draft flow:

cURL

curl -X POST https://api.orbit.devotel.io/api/v1/voice/ivr-flows \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Main menu (migrated from Twilio)",
    "active": true,
    "definition": {
      "nodes": [
        { "id": "start", "type": "ivrStart", "data": {} },
        {
          "id": "menu",
          "type": "menu",
          "data": {
            "prompt": "Press 1 for sales, 2 for support.",
            "menuOptions": [
              { "key": "1", "label": "Sales" },
              { "key": "2", "label": "Support" }
            ]
          }
        },
        { "id": "sales", "type": "transfer", "data": { "transferTo": "+14155550101" } },
        { "id": "support", "type": "transfer", "data": { "transferTo": "+14155550102" } }
      ],
      "edges": [
        { "id": "e1", "source": "start", "target": "menu" },
        { "id": "e2", "source": "menu", "target": "sales" },
        { "id": "e3", "source": "menu", "target": "support" }
      ]
    }
  }'

201 returns the draft with data.id (flw_…). The graph is validated on save — exactly one ivrStart, at least one terminal (transfer, hangup, voicemail, ringGroup, …), no unreachable nodes, and DTMF keys restricted to 0–9, *, #. transfer.transferTo must be a phone number or an on-net extension, never a raw sip: URI — outbound voice exits only via the Devotel softswitch. Publish so inbound callers hit it (a draft is invisible to traffic):

cURL

curl -X POST https://api.orbit.devotel.io/api/v1/voice/ivr-flows/flw_01HXV…/publish \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

200 returns the new live version number. Prefer to hand-author? The dashboard Voice → IVR Builder canvas posts the same flow and publishes from the UI. Canonical pages: Build IVR flow, IVR builder canvas vs DSL walkthrough.

5. Swap the verify-codes round trip

The source’s verify service (Twilio Verify, Sinch Verify, MessageBird Verify) generates, delivers, and expires an OTP; Orbit’s Verify API does the same with a two-call round trip your backend drives. Never store or compare codes tenant-side. Send — capture data.verification_id:

cURL

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

Check — the user’s answer plus the id from the send:

cURL

curl -X POST https://api.orbit.devotel.io/api/v1/verify/check \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "verification_id": "vrf_9f2a1c…",
    "code": "483920"
  }'

data.status — approved is the only pass. failed means the code didn’t match; retry with the same verification_id until attempts_remaining hits 0, then send a fresh one. expired means the TTL lapsed — send again. In sandbox, the test key simulates delivery; read the expected code from the verification’s dashboard row. Canonical pages: Verify in 30 minutes, Verify API.

Errors as recipes (the 429 / 422 branches a cutover script needs)

Branch on error.code — never on message text, which can drift.

Signal	`error.code`	HTTP	Branch
Send rate over the key’s limit	`RATE_LIMITED`	429	Read `error.retry_after` (also the `Retry-After` header) and wait that many seconds — never blind-exponential-backoff inside a named window; retry with the same `Idempotency-Key` so the retry can’t double-send.
Invalid destination on a send	`INVALID_PHONE_NUMBER`	422	Normalize to E.164, retry the same body — same 422 if you don’t.
LoA URL not issued by Orbit	`LOA_URL_INVALID_ORIGIN`	422	Loop 2: pass `files/upload`’s `data.url`, not your own bucket link.
IVR graph invalid (unreachable node, no terminal, bad DTMF key)	`VALIDATION_ERROR`	422	Loop 4: fix the named field — the message names the node id; never retry the same definition.
Messaging-service binding on a number that isn’t yours	`NUMBER_NOT_OWNED`	422	Loop 1: port it first (loop 2), then bind.
Verify check on an expired id	(status `expired` on `/verify/check`, not a thrown error)	200	Loop 5: send a fresh code; never loop on the same id.
Key issue (wrong prefix, revoked)	`INVALID_API_KEY`	401	Check `dv_test_sk_` vs `dv_live_sk_` and the key’s state in Settings → API Keys.

A customer-side retry wrapper honors the server-provided wait first, then falls back to a capped exponential backoff — the full pattern is at API error handling by example.

WhatsApp

Guides

Messaging Controls

Audience & Support Tools

API recipes: third-party migrators — the per-provider concept template

API recipes: third-party migrators

0. Automate the whole import instead

1. Resolve a Twilio Messaging Service SID into `messaging_service_id`

2. Port the numbers with an Orbit-issued LoA URL

3. Rewire status callbacks into Orbit webhooks

4. Flip the source IVR XML into a published flow

5. Swap the verify-codes round trip

Errors as recipes (the 429 / 422 branches a cutover script needs)

See also

​API recipes: third-party migrators

​0. Automate the whole import instead

​1. Resolve a Twilio Messaging Service SID into messaging_service_id

​2. Port the numbers with an Orbit-issued LoA URL

​3. Rewire status callbacks into Orbit webhooks

​4. Flip the source IVR XML into a published flow

​5. Swap the verify-codes round trip

​Errors as recipes (the 429 / 422 branches a cutover script needs)

​See also

API recipes: third-party migrators

0. Automate the whole import instead

1. Resolve a Twilio Messaging Service SID into `messaging_service_id`

2. Port the numbers with an Orbit-issued LoA URL

3. Rewire status callbacks into Orbit webhooks

4. Flip the source IVR XML into a published flow

5. Swap the verify-codes round trip

Errors as recipes (the 429 / 422 branches a cutover script needs)

See also