Migration from Sinch to Orbit

This guide walks you through migrating your SMS, multipurpose Conversation API, and Verification integration from Sinch to Orbit. Sinch’s account shape — a service_plan_id-scoped API token, a batch-only send surface, and (for omnichannel) the Conversation API “app” wrapping every channel — differs from Orbit’s model, and each of those concepts has a direct equivalent. The migration is incremental: every step below works alongside your live Sinch traffic until you cut over.

Concept Mapping

Sinch Concept	Orbit Equivalent	Notes
`service_plan_id` + API token	API key (`dv_live_sk_xxxx`) in the `X-API-Key` header	One key authenticates every endpoint — no per-product credentials
SMS batch send (`Batches` resource)	`POST /api/v1/messages` (one recipient) or `POST /api/v1/messages/batch` (`recipients[]`, up to 10,000 per call)	Sinch’s only SMS shape is batch; in Orbit a batch exists for scale and single send is the common path
Conversation API app (SMS/WhatsApp/RCS superapp)	Messaging Service + channel	A service id (`msvc_…`) bundles its sender pool, opt-out list, inbound webhook, and throughput cap — pass it as `messaging_service_id`; the channel is picked explicitly per send instead of living in one app
Delivery-report webhooks (DLR envelope)	Webhook events (`message.delivered`, `message.failed`, inbound `message.received`)	Same event-driven pattern, JSON envelope with an `X-Orbit-Signature` HMAC
Sinch Numbers	Orbit Numbers	Same capabilities; LOA-based porting supported also from Sinch
Sinch Verification	Orbit Verify	Send + check calls plus `verification.*` webhook events, same two-call OTP model

Prefer not to do it by hand?

The import tooling covers the configuration layer — numbers, messaging services, templates, and consent/contact data — before you touch any code:

Dashboard wizard — Settings → Import walks you through connecting a read-only credential, a dry-run preview, and a one-click commit with rollback.
CLI — npm install -g @devotel/cli, devotel auth login, then preview with devotel migrate and commit with --run.

The wizard imports your configuration only — it never moves live traffic, so the Sinch integration keeps running until you cut over. The rest of this guide covers the manual, code-level migration for teams who want full control over each step.

Step 1: Create Your Orbit Account

Sign up at orbit.devotel.io/signup
Generate an API key at Settings → API Keys
Note your key prefix: dv_live_sk_xxxx

Replace every Authorization: Bearer <service_plan_id token> header with X-API-Key: dv_live_sk_xxxx — one header, one key, for SMS, Verify, Numbers, and webhooks alike.

Step 2: Port Your Numbers

Sinch supports LOA-based port-out, so you can move existing numbers to Orbit. The process takes 7–14 business days. A port request must carry a Letter of Authorization (LoA). Orbit only accepts an LoA URL it issued itself, so you upload the signed PDF to Orbit first and submit the returned URL.

# 1. Upload the signed LoA PDF. The response `data.url` is a short-lived signed
#    URL (1-hour default). Pass `ttl_ms` to keep it valid long enough for the
#    carrier to fetch it during submission — here, 24 hours.
curl -X POST "https://api.orbit.devotel.io/api/v1/files/upload?ttl_ms=86400000" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -F "file=@./loa.pdf;type=application/pdf"
# => { "data": { "id": "file_...", "url": "https://storage.googleapis.com/...", ... } }

# 2. Submit the request — same call shape as a Twilio port, with the Sinch
#    account details you used to hold the number.
curl -X POST https://api.orbit.devotel.io/api/v1/numbers/porting \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "numbers": ["+14155551234", "+14155551390"],
    "currentCarrier": "Sinch",
    "country": "US",
    "authorizedSigner": "Your Name",
    "accountNumber": "123456789",
    "accountPin": "1234",
    "loaFileUrl": "https://storage.googleapis.com/.../loa.pdf?X-Goog-Signature=..."
  }'

Alternative: purchase new numbers and update your systems gradually. If the recipient is a US local number you’ll reuse for outbound (including 10DLC traffic), port it before you point sends at Orbit, then finish the 10DLC registration in the dashboard — the 10DLC walkthrough covers the ordering.

Step 3: Swap the SMS Send Path

Sinch’s SMS surface is the Batches resource — batch-shaped even for a single recipient — so “one endpoint to all your to[] values” has to be read as either a single send or a batch.

Sinch (Before)

const response = await fetch(
  'https://sms.sinch.com/service_plan_id/sp_xxxxxxxx:batches',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer sp_xxxxxxxx',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      from: 'mg_sendernumber',
      to: ['+14155552671'],
      body: 'Hello from Sinch!',
      delivery_report: 'full',
    }),
  }
)

Orbit (After)

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

const orbit = new Orbit({ apiKey: 'dv_live_sk_xxxx' })

// Single recipient
await orbit.messages.send({
  channel: 'sms',
  to: '+14155552671',
  body: 'Hello from Orbit!',
})

// Batch — pass a recipients[] array with optional per-row variables
await fetch('https://api.orbit.devotel.io/api/v1/messages/batch', {
  method: 'POST',
  headers: {
    'X-API-Key': 'dv_live_sk_xxxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    channel: 'sms',
    recipients: [
      { to: '+14155552671', body: 'Hello {{ first_name }}!' },
      { to: '+14155552890' },
    ],
    // Or carry the body once for the whole batch:
    // body: 'Hello {{ first_name }}!',
  }),
})

Field-by-field mapping

Sinch send field	Orbit send field	Notes
`from` (bare sender / `mg_*`)	`messaging_service_id` (`msvc_…`) or a bare `from`	A service id pulls the sender pool, opt-out list, and inbound webhook in one shot; map the Sinch sender id via the service’s `external_id` field
`to[]`	`to` (single) or `recipients[].to` (batch)	`/messages/batch` accepts up to 10,000 recipients per call and returns a per-recipient outcome map
`body`	`body` (shared) or `recipients[].body` (per-row)	Per-row values take priority; a shared `body` fills every row without one
`delivery_report`	Webhook subscription	See step 4 — you subscribe to `message.delivered` / `message.failed` instead of requesting a per-send flag
`parameters` / template variables	`recipients[].variables` (per-row Liquid)	`{{ first_name \| capitalize \| default: "friend" }}` per recipient in one request
`campaign`	`metadata` (per-row on batch)	Optional; useful alongside analytics joins

If your Sinch send was a single-recipient call, leave it single in Orbit. If it genuinely fanned out over to[], move it to /batch; the per-recipient map mirrors what Sinch’s per-batch DLR would have told you.

Step 4: Migrate Delivery-Report Webhooks

Sinch pushes DLRs as HTTP callbacks into an envelope you registered on the batch. Orbit subscribers see the same signal as signed webhook events with a stable event id — you dedupe on it instead of building idempotency out of per-message state.

Envelope mapping

Sinch DLR callback (before)

{
  "correlation_id": "cb_1",
  "status": "Delivered",
  "type": "delivery_status"
}

Orbit webhook event (after)

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

Handler migration

Subscribe once — POST /api/v1/webhooks with events: ["message.delivered", "message.failed", "message.received"] — instead of embedding delivery_report: "full" on every send.
Read the raw body before parsing, and verify against X-Orbit-Signature (HMAC-SHA256 over timestamp.body). X-Devotel-Signature still exists for backward compatibility only.
Dedupe on the envelope id — Orbit retries at-least-once for about 4–5 hours, so the id is the durable key for your seen_events table.
Ack fast (2xx in milliseconds) and hand the work to a queue.

Full walkthrough with verified Node.js and Python receivers in the webhook consumer guide.

Sinch webhook concept	Orbit equivalent
Callback URL registered per-batch	One subscription URL on `POST /api/v1/webhooks`
`correlation_id` (per batch)	Durable event envelope `id`
HMAC-less signature / API-key-style bearer auth	`X-Orbit-Signature` (HMAC-SHA256) header
Per-message `status` map	`message.delivered` / `message.failed` events

Step 5: Map the Conversation API

Sinch’s Conversation API wraps multiple channels inside one “app” that owns the sender and the inbound webhook. In Orbit the equivalent construct is a Messaging Service scoped to a channel, and sends name the channel explicitly. If your Sinch app handled WhatsApp — the most common Conversation-API case — the split looks exactly like the WhatsApp guides.

Conversation API concept	Orbit equivalent
App (SMS + WhatsApp + RCS in one scope)	One Messaging Service per channel (`msvc_…`), or a service + WhatsApp channel selection
Inbound webhook registered on the app	Inbound webhook on the service (`Inbound URL`) — see Messaging services console
Template approval flow for WhatsApp	WhatsApp templates — the same approval cycle surfaces through the WABA guides
Channel selection implicit under app	`channel` field on send (`sms`, `whatsapp`, `rcs`, …)

If your Sinch app mixed SMS and WhatsApp traffic, split it into a SMS Messaging Service plus the WhatsApp WABA path — you’ll get a per-channel throughput cap and a cleaner opt-out list instead of one shared envelope.

Step 6: Migrate Verification

Sinch Verification is the same send/check OTP model as Orbit Verify — two backend calls, plus an optional webhook for asynchronous completion.

Sinch (Before)

await sinch.verifyments.start({
  identity: { type: 'number', endpoint: '+14155552671' },
  method: 'sms',
})

const result = await sinch.verifyments.report({
  identity: { type: 'number', endpoint: '+14155552671' },
  method: 'sms',
  code: '123456',
})

Orbit (After)

const verification = await orbit.verify.send('+14155552671', 'sms')

const result = await orbit.verify.check({
  verification_id: verification.data.verification_id,
  code: '123456',
})

If you don’t want a client library, plain HTTPS works end-to-end — POST /api/v1/verify/send then POST /api/v1/verify/check — see Verify without the SDK.

Migration Checklist

Parallel Running Strategy

We recommend running Sinch and Orbit in parallel during migration:

Phase 1 (Week 1–2): Send 10% of traffic through Orbit, 90% through Sinch
Phase 2 (Week 3–4): Split 50/50 and compare delivery rates
Phase 3 (Week 5): Route 100% through Orbit, keep Sinch as fallback
Phase 4 (Week 6+): Decommission Sinch

Only decommission the service_plan_id credential after cutover is stable — a leftover token that still verifies forces you to treat signature failures as auth bugs.

Need help with your migration? Our solutions team offers free migration support for customers moving from Sinch. Contact migrate@devotel.io.

WhatsApp

Guides

Messaging Controls

Audience & Support Tools

Migrate from Sinch to Orbit: SMS, Conversation API, and Verification

Migration from Sinch to Orbit

Concept Mapping

Prefer not to do it by hand?

Step 1: Create Your Orbit Account

Step 2: Port Your Numbers

Step 3: Swap the SMS Send Path

Sinch (Before)

Orbit (After)

Field-by-field mapping

Step 4: Migrate Delivery-Report Webhooks

Envelope mapping

Handler migration

Step 5: Map the Conversation API

Step 6: Migrate Verification

Sinch (Before)

Orbit (After)

Migration Checklist

Parallel Running Strategy

​Migration from Sinch to Orbit

​Concept Mapping

​Prefer not to do it by hand?

​Step 1: Create Your Orbit Account

​Step 2: Port Your Numbers

​Step 3: Swap the SMS Send Path

​Sinch (Before)

​Orbit (After)

​Field-by-field mapping

​Step 4: Migrate Delivery-Report Webhooks

​Envelope mapping

​Handler migration

​Step 5: Map the Conversation API

​Step 6: Migrate Verification

​Sinch (Before)

​Orbit (After)

​Migration Checklist

​Parallel Running Strategy

Migration from Sinch to Orbit

Concept Mapping

Prefer not to do it by hand?

Step 1: Create Your Orbit Account

Step 2: Port Your Numbers

Step 3: Swap the SMS Send Path

Sinch (Before)

Orbit (After)

Field-by-field mapping

Step 4: Migrate Delivery-Report Webhooks

Envelope mapping

Handler migration

Step 5: Map the Conversation API

Step 6: Migrate Verification

Sinch (Before)

Orbit (After)

Migration Checklist

Parallel Running Strategy