> ## Documentation Index > Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt > Use this file to discover all available pages before exploring further. # Migration playbook hub: the vendor-agnostic sequence for any source platform > One hub for moving to Orbit: links to every vendor-specific migration guide with when-to-use notes, the vendor-agnostic step skeleton, number-port vs re-register sequencing, a seven-step cutover runbook, and post-cutover operations. # Migration playbook hub The vendor-specific guides each map one source platform's concepts onto Orbit. This hub covers the shape every migration shares — account, sandbox, numbers, data, templates, webhooks, parallel-run, cutover — so a migration from a platform with no dedicated guide still has an exact playbook, and a migration from one of the covered platforms knows where its guide sits in the sequence. Read your vendor's guide for the concept mapping (what the source calls a messaging service, an app, a flow). Read this hub for the order of operations, because that order does not change with the source. ## 1. Hub map — pick the guide for your source | Guide | Use it when | | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Migrate from Twilio](/guides/migration-from-twilio) | You send on Twilio (SMS, voice/TwiML, Verify). Also the fullest worked example of the manual code-level migration. | | [Migrate from Sinch](/guides/migration-from-sinch) | You send on Sinch — service-plan tokens, batch sends, Conversation API, Sinch Verification. | | [Migrate from Vonage](/guides/migration-from-vonage) | You send on Vonage (Nexmo) — Applications, JWT auth, NCCO call control. | | [Migrate from MessageBird](/guides/migration-from-messagebird) | You send on MessageBird (Bird) — Flow Builder, WhatsApp channels, lookup, MNM. | | [Migrate from Infobip](/guides/migration-from-infobip) | You send on Infobip — base-URL auth, Moments flows, Answers bots, number lookup. | | [Migrate from enterprise CCaaS](/guides/migrate-from-enterprise-ccaas) | Your source is a per-seat contact-center suite — Genesys Cloud CX, Talkdesk, Five9, NICE CXone — with queues, IVRs, and recordings to move. | | [Run a platform migration end-to-end](/guides/platform-migration-jobs) | Your source is Twilio, Telnyx, Klaviyo, MessageBird, or Front and you want the import wizard to pull contacts and configuration instead of rebuilding by hand. | Everything in [Section 2](#2-vendor-agnostic-skeleton) applies to each of these. When your source is not in the table — a regional aggregator, an in-house gateway, a hosted SMSC — apply Section 2 directly: the send endpoint changes per vendor, the migration shape does not. ## 2. Vendor-agnostic skeleton — the eight universal steps Every vendor-specific guide runs the same eight steps; the vendor guides replace step-content where the source platform forces it (for example, Sinch batch sends, Vonage JWTs). Use this checklist for a source with no dedicated guide, and as the audit spine for a covered one. | # | Step | What it means on Orbit | Verify | | - | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | | 1 | Account and KYC | Create the organization, generate an API key, complete regulatory identity where the destination market requires it (sender-ID registration, 10DLC brand and campaign, activated number). | `GET /api/v1/organizations/me` returns your org; a sandbox send succeeds before any traffic moves. | | 2 | Sandbox validation | Send one message of every channel you run — SMS, WhatsApp, email, voice, fax — on a test recipient while the legacy platform still owns production. | A `message.delivered` webhook for the probe arrives at a throwaway receiver. | | 3 | Numbers | Port, re-register, or repoint (Section 3 decides which). Nothing in your integration changes until the number move is planned. | `eligible: true` from the portability preflight, or the RespOrg/repoint route chosen. | | 4 | Recipient and contact data | Export contacts with consent state; import via CSV or the platform-migration wizard. Suppression lists and opt-outs travel with the recipients. | Row counts match the export; a sample contact carries its original opt-out. | | 5 | Templates | Re-author message templates — WhatsApp templates need re-approval, email templates get rebuilt, suppression rules get recreated — on the Orbit surface for that channel. | The re-authored template renders a correct test-send with real variables. | | 6 | Webhooks and delivery receipts | Re-point status callbacks to the Orbit event names (`message.delivered`, `message.failed`, `call.completed`) and re-verify signatures against `X-Orbit-Signature`. | The receiver verifies a live Orbit event against the webhook secret. | | 7 | Parallel-run | Split real traffic between platforms and grade Orbit against the legacy provider on the same traffic class (Section 4). | Delivery-rate parity on the split window before any decommission. | | 8 | Cutover and decommission | Freeze legacy sends, flip routing, keep fallback warm, close the legacy account last. | The seven-step runbook below, each step with its own check. | Section outline vs vendor column: on a covered vendor, each row above maps to one or more sections in that vendor's guide — the row is the constant, the guide is the variable. On an uncovered vendor, the rows are your whole vendor column. ## 3. Number-port sequencing — leave correctly Which move the number makes depends on what your legacy provider is *to the number*, not on which send API you used. Decide per number before you queue anything. | Your legacy provider is… | The number move is… | Why | | ---------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | The carrier that hosts the number (Twilio, Sinch, Vonage, Bandwidth-number holders) | **Port** — full LNP flow: CSR, preflight, LOA, FOC, 7–14 business days. | The number must physically change carriers. Follow [Port a number end-to-end](/guides/port-numbers) and the [first port-in walkthrough](/guides/number-porting-walkthrough-first-port). | | An aggregator riding on someone else's numbers, selling you access (Klaviyo SMS on a shared number, some MessageBird and Infobip setups) | **Re-register, not port** — the sender identity and regulatory registration (10DLC campaign, sender ID) move; the number itself was never yours to port. | Porting a number you do not own stalls at the LOA. Recreate the registration on numbers you buy or bring, per the [10DLC registration guide](/guides/10dlc-registration). | | Your own carrier behind an API layer (BYOC, an in-house gateway) | **Repoint** — keep the carrier and connect its trunk instead of moving numbers. | No port window at all; the SIP route flips at cutover (Step 2 of the [enterprise CCaaS runbook](/guides/migrate-from-enterprise-ccaas) is this pattern). | | Toll-free, anywhere | **RespOrg change** — move the Responsible Organization, not the carrier. | Toll-free never ports carrier-to-carrier; the LNP flow rejects it. | Sequence numbers ahead of everything downstream: ports take days to weeks per country, so the port clock starts before templates are re-authored — not after. A send-side migration that waits on zero ports is the fast lane; plan for it only after the decision table says no number physically moves. ## 4. Runbook for cutover — the canonical seven steps Cutover is the one step that touches live traffic, so it is a checklist, not a migration phase. Freeze, redirect, swap, flip, verify, hold, close. Each step carries its verification command — do not proceed past a step whose check failed. 1. **Freeze sends on the legacy platform.** Stop new dispatches at the traffic manager or code path that selects the provider; drain in-flight batches. Verify: the legacy console's outgoing queue reads zero new entries for a full drain window, while your Orbit-side traffic keeps flowing on the parallel-run split. 2. **Redirect webhook receivers.** Point your event consumer at Orbit signatures and event names (or point Orbit's webhooks at your existing receiver — the receiver wins, the signature check changes). Verify: `curl` a replayed `message.delivered` against your receiver and confirm the `X-Orbit-Signature` verification passes: ```bash theme={null} curl -X POST https://yourapp.example.com/webhooks/orbit \ -H "Content-Type: application/json" \ -H "X-Orbit-Signature: " \ -d '{"type":"message.delivered","data":{...}}' # Expect 2xx from your own verified handler — a signature error here means # the secret, not the receiver, is wrong. ``` 3. **Swap API keys at the sender.** Move `X-API-Key` values from the legacy credential to the Orbit key in your secret store; revoke the legacy key only after Step 6. Verify: a probe send through the production path lands on Orbit: ```bash theme={null} curl -X POST https://api.orbit.devotel.io/api/v1/messages/sms \ -H "X-API-Key: dv_live_sk_..." \ -H "Content-Type: application/json" \ -d '{"to":"+14155552671","body":"cutover probe"}' # Expect data.status: queued — and a delivered webhook within the parallel-run's observed window. ``` 4. **Flip sender identity.** Route production traffic onto the Orbit-registered sender — the ported number, the approved 10DLC campaign, the active sender ID. Verify: the probe's `from` on the recipient handset matches the identity the destination market expects (short-code, alphanumeric ID, or ported long code), not a fallback. 5. **Watch the first-hour parity window.** Compare Orbit's delivery rate on the previously-split traffic class against the legacy baseline you measured in parallel-run. Verify: parity holds within your tolerance on the [insights dashboards](/guides/ask-your-data-insights); a sustained dip reopens Step 2's signature and Step 4's identity findings before it reopens routing. 6. **Hold the fallback warm.** Keep the legacy credential and routing hook alive, unused, for an agreed window — typically one full billing cycle or two peak weeks. Verify: a controlled canary through the legacy path still reaches its destination, so a rollback is a config flip, not a rebuild. 7. **Decommission the legacy account.** Close it only after the hold window passes and the legacy credential carries zero remaining sends. Verify: the legacy account shows no active numbers, no queued campaigns, and no webhook commitments your receiver still depends on — then close, and record the close date in your own ops log. ## 5. Operations after cutover Cutover ends the traffic move; operations is what keeps the migration honest afterward. * **Migration job history.** Platform-migration jobs (wizard-run imports of contacts and configuration) live past onboarding on **Settings → Migrations** — every job with its status, its failure reason, and its rollback state. A finished job that imported wrong rows can still be rolled back after cutover; the operations surface and the API for it are in [Monitor, cancel, and roll back platform migrations](/guides/migration-jobs-operations). * **Audit ledger.** Every migration-relevant change — the import run, the rollback, the key rotation, the port submission — lands in the tenant audit log. When a post-cutover discrepancy appears (a contact that lost its opt-out, a webhook consumer that stopped receiving), the audit ledger is the timeline that says which step introduced it; see the [audit log guide](/guides/audit-log) for reading and exporting it. * **Suppression and consent state.** Opt-outs collected during the parallel-run on the legacy platform must exist in Orbit before decommission. Check the exported suppression list against Orbit's per-channel suppression; a missed row is a compliance defect, not a cosmetic one. Migrating from a platform this hub does not list, or mixing a listed messaging vendor with an unlisted voice provider? The solutions team works unlisted-source migrations regularly — [migrate@devotel.io](mailto:migrate@devotel.io) with your source platform and traffic mix gets you the same parallel-run plan the listed guides assume.