Migrate from enterprise CCaaS to Orbit

This runbook walks you off a per-seat enterprise contact-center suite — Genesys Cloud CX, Talkdesk, Five9, or NICE CXone — onto Orbit’s contact center, channels, and AI voice agents on one account. The migration is phased: audit, move connectivity, rebuild, cut over, validate. Your incumbent suite stays live until the last ported number validates. Plan 2–6 weeks depending on queue count and how many countries carry number-porting lead times. Regulated traffic (HIPAA, call recording) travels with its own approval step — treat it as a workstream, not an afterthought.

Before you begin

Workspace admin on the incumbent suite (Genesys Cloud CX / Talkdesk / Five9 / NICE CXone)
An Orbit account and API key
Admin access on your carrier consoles for SIP trunking and number portals
Export rights on the incumbent for queue configs, call flows, recordings, and reports
A low-stakes destination wave: one non-critical queue or regional number to port first
(Healthcare) A Business Associate Agreement request opened ahead of any PHI traffic — execute before the call-flow cutover, not after

Step 1: Audit what you actually run

Build the inventory before you touch a call flow. Every migrated queue starts here. The migration artifacts section below gives the export schema each audit list fills. Queues and routing. Export the ACD queue list: queue name, skills or routing expressions, SLA targets, ring strategy, overflow and fallback destinations, and in-queue callback offers. Each row becomes one queue to rebuild in Orbit. IVR flows and prompts. Export every call flow: the menu tree, prompts and recordings, business-hours routing, holiday schedules, and each node’s destination — then map every menu node to its outcome (queue, announcement, voicemail, hang-up). That map is the routing contract your rebuilt IVR reproduces first. Agent states and skills. Pull the agent roster with skills assignments, the state list, and the concurrency rules. Orbit’s agent-state routing reproduces the same presence model — map it in the audit so a ported agent never lands in a state that has no equivalent. Analytics, recordings, retention. Export the report definitions you actually run on, plus the raw exports and call recordings your retention and compliance policies require. Historical reporting data does not migrate; take it out while the incumbent still lets you. Numbers, trunks, SIP endpoints. List every number and trunk: local, toll-free, and per-country numbers with the regulatory registrations each one carries, plus the SIP trunks and carriers. This feeds the porting ladder in Step 2 — the registrations travel with each number and gate the port timeline. Compliance posture. Record what the current setup enforces — consent capture, recording disclosures, retention windows. On Orbit these controls are tenant-configurable: your organization sets its own quiet-hours, consent, and retention policy. Write the policy you intend to enforce on the audit sheet, not the one the incumbent defaulted to.

Step 2: Port the trunk and numbers in a ladder

Move connectivity before numbers; validate on shadow traffic before production.

Stand up SIP trunking first. Keep your current carrier and connect its SIP trunk to Orbit with bring-your-own-carrier — the numbers keep ringing on the incumbent while you rebuild. Alternatively terminate calls on Orbit; both paths route on the same voice product surfaces.
Rebuild the IVR on the trunked numbers. Recreate each audited menu flow in Orbit’s visual IVR builder — the builder, SIP trunking, and ACD queues ship on one surface. Reproduce the audited routing contract node for node: same prompts, same business hours, same destinations. At queue-count scale, script the Rebuild the queues and Rebuild the IVR loops below instead of clicking the builder per flow.
Rebuild the queues and agent states. Recreate each audited queue with its skills filters, SLA targets, overflow destinations, and in-queue callback; then the agent roster with its skills and state model. Run the rebuilt queues on shadow traffic — a ported non-critical number — before any production queue points at them.
Port numbers in waves. Move a non-critical queue’s numbers first, validate the full call path, then port customer-facing queues in batches. Number porting runs days to weeks per country and the regulatory registrations travel with the number — stage windows so no two customer-facing queues move at once. To script the batch instead of driving the console, run the Port the batch programmatically loop; hold a rollback check (Rollback check) for each wave.

Done in this order, every element carries real traffic at low stakes before customer-facing volume moves. If a wave fails validation, unported numbers still terminate on the incumbent.

Rollback — porting ladder (Step 2)

Gates that must pass before a wave counts as done: the rebuilt IVR reproduces the audited routing contract on the trunked number, the rebuilt queue answers shadow traffic within its SLA target, and the ported batch’s numbers render calls end-to-end. If a ported wave fails validation:

Repoint the SIP route. In your carrier console, return the affected trunk’s termination URI to the incumbent’s endpoint. The carrier route flips; the numbers themselves do not move, so the incumbent starts answering the failed wave’s traffic again within minutes.
Delay the next port batch. Do not submit the next batch’s Letter of Authorization (LOA) until the failed wave re-validates. A queued-but-unsubmitted batch costs nothing; a submitted one burns its port window.
Revert the queue override. In the Orbit flow builder, remove the rebuilt queue from the affected number’s routing and restore the previous menu destination, so the trunked (still-incumbent) numbers fall back to their audited paths.

Step 3: Cut over the AI agents

Run this as a second migration inside the first. The incumbent’s separately licensed agentic add-on cancels at the end — never during the cut-over.

Shadow the agent behind the rebuilt IVR. Keep the rebuilt menu live and add the Orbit AI voice agent as a new front option on production calls, following the phased pattern in the IVR migration approach: the agent shadows on real traffic while the menu keeps its containment baseline.
Move top intents first. When the shadow data shows the agent resolves the top audited intents at least as well as the menu path, promote it for those intents. Rank by what callers actually say (the transcript catalog from Step 1), not by the menu designer’s tree.
Rewire the escalation contract warm. Point the agent’s handoff at the same ACD queues your human agents already work in, with a call summary and the verified intent attached. Pin which queue, which skills filter, and what context the human receives before the agent goes live.
Cancel the incumbent’s AI add-on last. Only after every intent clears its containment gate does the incumbent’s pilot licence or agentic suite stop being a working system.

Rollback — AI-agent cutover (Step 3)

Gates that must pass before an intent counts as cut over: containment on that intent matches or beats the menu path over the shadow window, and handoff spot-checks show the summary and verified intent arriving in the target queue. If a promoted intent fails:

Demote the intent to shadow. Remove the failed intents from the agent’s routing scope and restore the menu node destinations for them in the flow builder. The agent keeps shadowing on the remaining traffic; the menu path takes the demoted intents back.
Revert the handoff wiring only if it missed. If containment held but escalations arrived without context, keep the intent promoted and fix the handoff target — which queue, which skills filter, which summary fields — rather than rolling the whole intent back.
Keep the incumbent AI licence active. Cancel the incumbent’s pilot or agentic add-on only after every intent clears its containment gate; until then it remains your fallback for demoted intents.

Step 4: Validate per wave

Grade every wave on four parity metrics. Read each on its Orbit surface and pair it against the incumbent’s report for the same traffic class and window:

Parity metric	Read it in Orbit	Pair it against
Containment (contained-call share per intent)	Insights dashboards — agent containment reporting	Incumbent’s bot/containment report, same intents
Queue metrics (answer time, SLA attainment, callbacks)	Insights dashboards — queue performance	Incumbent’s queue performance report, last full week
Handoff context (summary + verified intent on escalation)	Supervisor live monitoring and call QA scorecards	Incumbent’s escalation/transfer summary
Channel and state parity (agent states, skills, per-channel spend)	Supervisor live monitoring; channel costs report	Incumbent’s agent-state and usage reports

Copy this checklist per wave — a wave passes only when every box ticks:

Containment parity holds on the same traffic class, Orbit vs incumbent
Answer time and SLA attainment on rebuilt queues match the incumbent’s last full week
Escalation spot-checks show a call summary and verified intent, not a bare transfer
Agent-state transitions and skills assignments line up on the roster
Channel costs report shows no per-channel spend anomaly on the ported batch
Rollback path for this wave is still live (SIP route revertable, next port batch unsubmitted)

Rollback stays live until the last ported number validates: trunks came across first and numbers moved in waves, so rolling a wave back means repointing the affected SIP route or delaying the next port batch — nothing gets rebuilt.

Migration artifacts

The audit in Step 1 produces three artifacts. Sketch their shapes now so exports are diffable across weeks. The worked loops after this section execute these two structured-row artifacts against the API — the CSV drives Rebuild the queues, the JSON drives Rebuild the IVR. Queue inventory (CSV). One row per queue:

queue_name,skills_or_routing_expression,sla_target_seconds,ring_strategy,overflow_destination,fallback_destination,inqueue_callback
support-tier1,"language=en AND product=billing",60,simultaneous,queue:support-tier2,voicemail:support-vm,true

IVR node map (JSON). One object per menu node; destination_type ∈ queue, announcement, voicemail, hang-up:

{ "node_id": "main-menu", "prompt_file": "main-menu-en.wav", "menu_options": ["1","2","9"], "business_hours_ref": "weekdays", "destination_type": "queue", "destination": "support-tier1" }

Business-hours and holiday mapping. Map every incumbent schedule to an Orbit business-hours rule set before rebuilding flows — one mapping row per schedule:

Incumbent schedule	Timezone	Orbit business-hours rule set	Holiday calendar entries
Weekdays 08:00–18:00	Europe/Berlin	`weekdays-de`	DE federal + state holidays
24/7	—	none (default open)	—

Registrations travel with the number. For each number in the porting ladder, confirm before you submit the LOA:

Regulatory registration (per-country identity/business registration) captured from the incumbent
Emergency address record exported and ready to re-attach
Caller-ID / CNAM display value recorded
The number’s lifecycle state tracked from port request through activation — see numbers lifecycle

Rebuild the queues

Iterate the queue-inventory CSV through the Voice API — one POST /api/v1/voice/queues per row, then record the returned id as the overflow target for the next row. Loops like this one are the same shape as the API recipes cookbook; pass an Idempotency-Key per row so a retried import can never double-create a queue. Create one queue:

cURL

curl -X POST https://api.orbit.devotel.io/api/v1/voice/queues \
  -H "X-API-Key: dv_live_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: queue-import-support-tier1" \
  -d '{
    "name": "support-tier1",
    "targetServiceLevelSeconds": 60,
    "maxWaitSeconds": 300,
    "overflowAction": "overflow_queue"
  }'

A 201 returns the queue in the standard envelope — data.id (queue_…) is the handle the mapping table records. Static prompts (welcome, periodic, hold music) attach as optional URLs at creation; the callback offer lives on the overflow action (callback instead of voicemail/overflow_queue). Full field catalogue: Voice API. Turn the CSV into a create loop (Node, orbit.request escape hatch — voice/queues has no typed helper):

Node SDK

import { Orbit } from '@devotel-orbit/node';
import { readFileSync } from 'node:fs';

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY });

// Split a CSV line on commas outside quotes — the queue-inventory CSV from
// the Step 1 audit quotes fields that can carry commas.
const parseCsvLine = (line: string): string[] => line.split(/,(?!(?:[^"]*"[^"]*")*[^"]*$)/).map((f) => f.replace(/^"|"$/g, ''));

const rows = readFileSync('queue-inventory.csv', 'utf8').trim().split('\n').slice(1);
const mapping: Record<string, string> = {};
for (const line of rows) {
  const [name, skills, sla, ring, overflow, fallback, callback] = parseCsvLine(line);
  const res = await orbit.request<{ data: { id: string } }>('POST', '/voice/queues', {
    name,
    targetServiceLevelSeconds: Number(sla),
    overflowAction:
      callback === 'true' ? 'callback' : fallback.startsWith('voicemail:') ? 'voicemail' : 'hangup',
  });
  mapping[name] = res.data.id; // queue_…
}

The first pass records CSV name → queue id in mapping — persist it beside the CSV (the IVR loop resolves its destination_type: "queue" nodes against it, and rollback lists what to delete). Second pass wires chained-queue overflow now that every id exists:

Node SDK

for (const line of rows) {
  const [name, , , , overflow] = parseCsvLine(line);
  if (overflow.startsWith('queue:') && mapping[overflow.slice(6)]) {
    await orbit.request('PUT', `/voice/queues/${mapping[name]}`, {
      overflowAction: 'overflow_queue',
      overflowQueueId: mapping[overflow.slice(6)],
    });
  }
}

orbit.request(method, path, body) is the SDK’s escape hatch against the raw REST path (same shape across languages — see API recipes); it auto-adds an Idempotency-Key on every mutating call, so the retry import can never double-create a queue.

Rebuild the IVR

Iterate the IVR node map through the Flows API — one POST /api/v1/flows per menu root, and a POST /api/v1/flows/:id/publish the first time the definition passes review. A 201 returns the new flow as data.status: "draft" (like every other flow create; draft holds until you publish).

cURL

curl -X POST https://api.orbit.devotel.io/api/v1/flows \
  -H "X-API-Key: dv_live_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "main-menu",
    "description": "Rebuilt main menu — routes to the support-tier1 queue.",
    "definition": {
      "nodes": [
        { "id": "trigger_1", "type": "trigger" },
        { "id": "menu_1", "type": "ivr_menu", "config": {
            "prompt": "main-menu-en.wav",
            "options": ["1", "2", "9"],
            "business_hours_ref": "weekdays" } },
        { "id": "queue_1", "type": "queue_route", "config": {
            "queue_id": "queue_a1b2c3d4e5" } }
      ],
      "edges": [
        { "source": "trigger_1", "target": "menu_1" },
        { "source": "menu_1", "target": "queue_1" }
      ]
    },
    "trigger_type": "webhook"
  }'

Resolve destination_type per audit row into the route node: queue → a queue_route node pointed at the id from the queue mapping table; announcement/voicemail/hang-up → a node of the matching type; business_hours_ref rides on the menu node’s config exactly as the audit named it. Publish once — the flow answers traffic only after POST /api/v1/flows/:id/publish; later edits create a new draft version to publish again.

Port the batch programmatically

Submit the LOA artifact list through the Numbers API: pre-check the batch with POST /api/v1/numbers/porting/check, then open one POST /api/v1/numbers/porting request per batch. Numbers stay where they are until the carrier’s Firm Order Commitment (FOC) date, so the LOA carries one request covering every number in the wave — not one request per number.

cURL

# 1) Pre-check the whole batch.
curl -X POST https://api.orbit.devotel.io/api/v1/numbers/porting/check \
  -H "X-API-Key: dv_live_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "numbers": ["+14155552671", "+14155552672"] }'

# 2) Submit the porting request — LOA fields map to the request body.
curl -X POST https://api.orbit.devotel.io/api/v1/numbers/porting \
  -H "X-API-Key: dv_live_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "numbers": ["+14155552671", "+14155552672"],
    "currentCarrier": "Legacy Carrier Inc.",
    "authorizedSigner": "J. Operator",
    "accountNumber": "ACCT-1182",
    "accountPin": "0142",
    "country": "US",
    "contactEmail": "porting-ops@example.com"
  }'

The 201 returns data.id (port_…) and the starting status (submitted); branch on it — porting moves submitted → reviewing → approved → completed, with rejected terminal when the carrier declines. Validate the batch’s eligibility first — a rejected pre-check means the LOA list stops at the gate, and a submitted batch burns its window. Full request lifecycle and per-number port-out: Number porting states, Numbers API.

Rollback check

Before the next wave ports, verify the ported batch’s inbound termination holds: read recent calls aimed at one ported number and confirm the API returns rows (calls are landing on Orbit, not lost). This is the cheapest pre-wave gate on the Voice API.

cURL

curl "https://api.orbit.devotel.io/api/v1/voice/calls?to=%2B14155552671&direction=inbound" \
  -H "X-API-Key: dv_live_sk_YOUR_KEY"

A 200 whose data.length > 0 (and whose most recent row shows a reasonable status/started_at) means the ported DIDs terminate on the new route — proceed to the next wave. An empty data list means the batch route went silent: hold the next LOA and re-run the ladder from Step 2.

Failure modes per phase

Phase	Failure	Symptom	First fix
Step 2 — trunking	SIP trunk register failure	Trunk shows unregistered; inbound calls get 503	Troubleshoot SIP trunking
Step 2 — porting	Port rejection (LOA mismatch)	Losing carrier returns the port order	Number porting states
Parallel run	Webhook subscription drops	Inbound events stop arriving mid-wave	Webhook deliveries
Step 2 — ported batch	Call quality regression	Quality scores drop on the new route	Voice call quality
Dual-run outbound	Quiet-hours / consent gap	Outbound calls blocked in the compliance window	TCPA window blocked calls

Healthcare: BAA before the cutover runs

Treat regulated traffic as its own workstream. A Business Associate Agreement is available on request for qualifying healthcare customers and proceeds through case-by-case review — never an automatic grant. One reviewed agreement covers the LLM, speech-to-text, text-to-speech, and telephony legs because Orbit runs those legs itself; sequence the review before the first healthcare-traffic wave ports, not alongside it. Configure the tenant-owned controls from your Step 1 audit policy — HIPAA compliance lists the full set; at minimum:

Recording consent: the disclosure and opt-out behavior your policy demands, configured per line
PHI handling: which queues and flows are permitted to touch PHI, with prompts and knowledge sources scrubbed accordingly
Retention windows: recording and transcript retention set to your policy values, not the defaults
Quiet-hours and consent rules for any outbound leg attached to a healthcare queue

Next steps

Migration from Twilio to Orbit — channel-level port for SMS, voice, webhooks
Port numbers — the number-porting surface this ladder feeds
SIP trunk setup — bring-your-own-carrier configuration
Number lifecycle — states a number moves through during a port
HIPAA compliance — BAA status and the healthcare controls

WhatsApp

Developer console

Guides

Messaging Controls

Audience & Support Tools

Migrate from enterprise CCaaS (Genesys, Talkdesk, Five9, NICE CXone)

Migrate from enterprise CCaaS to Orbit

Before you begin

Step 1: Audit what you actually run

Step 2: Port the trunk and numbers in a ladder

Rollback — porting ladder (Step 2)

Step 3: Cut over the AI agents

Rollback — AI-agent cutover (Step 3)

Step 4: Validate per wave

Migration artifacts

Rebuild the queues

Rebuild the IVR

Port the batch programmatically

Rollback check

Failure modes per phase

Healthcare: BAA before the cutover runs

Next steps

​Migrate from enterprise CCaaS to Orbit

​Before you begin

​Step 1: Audit what you actually run

​Step 2: Port the trunk and numbers in a ladder

​Rollback — porting ladder (Step 2)

​Step 3: Cut over the AI agents

​Rollback — AI-agent cutover (Step 3)

​Step 4: Validate per wave

​Migration artifacts

​Rebuild the queues

​Rebuild the IVR

​Port the batch programmatically

​Rollback check

​Failure modes per phase

​Healthcare: BAA before the cutover runs

​Next steps

Migrate from enterprise CCaaS to Orbit

Before you begin

Step 1: Audit what you actually run

Step 2: Port the trunk and numbers in a ladder

Rollback — porting ladder (Step 2)

Step 3: Cut over the AI agents

Rollback — AI-agent cutover (Step 3)

Step 4: Validate per wave

Migration artifacts

Rebuild the queues

Rebuild the IVR

Port the batch programmatically

Rollback check

Failure modes per phase

Healthcare: BAA before the cutover runs

Next steps