Skip to main content

​
Assisted import from Klaviyo, MessageBird, Telnyx, or Twilio

Onboarding ships an assisted import wizard that connects to your current provider, shows you exactly what will come across before anything is written, and runs the import as a background job you can watch, cancel, or roll back. Dedicated connectors exist for Klaviyo, MessageBird, Telnyx, and Twilio. The wizard is always read-only against the source: it never sends messages, changes configuration, or touches live traffic on the old account. Cut-over happens when you point your own integration at Orbit, not when the import finishes.

​
1. Start the wizard and connect a source

Open the import wizard from onboarding (or revisit it later from the dashboard under Settings → Import) and pick your source. Each connector has its own first step:
  • Twilio — OAuth or API credentials. The preferred path is Twilio Connect: click through to authorize Orbit on Twilio’s site and you are returned with a protected session, no secrets pasted anywhere. When Twilio Connect is not available for your account (for example self-hosted subaccounts), the wizard offers a fallback: paste your Account SID (starts with AC) and Auth Token.
  • MessageBird — access key. MessageBird publishes no OAuth flow, so create a live access key under Settings → Developers → API access and paste it. Read scope is sufficient; the key is never used to send traffic.
  • Telnyx — API key. Paste a Telnyx V2 API key (starts with KEY).
  • Klaviyo — private API key. Create one in Klaviyo under Settings → API keys (starts with pk_). Read-only scope covers the whole import.
Whichever path you take, the credential is encrypted before it leaves the page, is used only to read your account during the migration, and is wiped when the import reaches a terminal state (completed, failed, or cancelled). Nothing is ever sent through the old provider as a result of connecting it.

​
2. Pick what carries over

Step two shows one checkbox per entity kind the source supports — all checked by default. Uncheck anything you want to leave behind. Two patterns are worth knowing before you pick:
  • Configuration versus contacts. Some kinds are data — Klaviyo profiles, MessageBird contacts, Twilio recipients — and land in your Orbit contacts table. Others are configuration metadata: Telnyx messaging profiles and 10DLC registrations, MessageBird channels and flows, Klaviyo flow definitions. These carry over as mapped configuration for reference and re-provisioning, not as live senders — registering numbers for messaging on Orbit is its own step (see 10DLC registration).
  • Consent travels with contacts. Opt-out and consent state on imported contacts is preserved, so a suppressed recipient on the old platform stays suppressed in Orbit.
Step three sets a conflict policy per entity that already exists in Orbit: skip (default — leave the Orbit row alone), overwrite, or merge fields. Source account users are not imported as teammates on any of the four connectors; imported rows stay owned by you and can be reassigned afterward.

​
3. Dry-run before you commit

Start the dry-run and nothing is written. The preview shows, per entity kind, the estimated count on the source account, how many rows already exist in Orbit (known conflicts), and an estimated runtime. Use it to sanity-check your picks:
  • Refresh the counts after changing entity selections or conflict policies.
  • If the source rate-limits the preview, wait a moment and retry — a failed dry-run never changes anything.
  • Known conflicts are not errors. They become the rows your conflict policy (skip, overwrite, merge) is applied to, so set that policy on the previous step deliberately rather than accepting the default by accident.
When the preview reads correctly, start the import.

​
4. Run, watch, and verify

The import runs in the background. The final wizard step shows per-entity progress (imported / skipped / failed counters) and finishes with a reconcile table. You can leave the page — the job continues, and the wizard state is URL-encoded so a refresh or a reopened link picks the same job back up. If something goes wrong, the wizard says so explicitly rather than hanging:
  • Import failed. You get a failure banner with a reference to give support, plus a retry action. Rows already imported stay imported.
  • Live progress unavailable. If the progress feed drops, the wizard falls back to polling and, if polling also fails, shows a banner with a link to the durable history view under Audience → Imports (also mirrored on Settings → Migrations).
  • Cancel and rollback. Cancel a running import at any time; rows already brought in remain. After a job finishes, an owner or admin can roll it back from the wizard or from Settings → Migrations, which removes the contacts that specific job created and nothing else.
Verify before you cut anything over:
  • The reconcile table’s imported counts match the dry-run estimates (plus or minus the conflicts you chose to skip).
  • Spot-check imported contacts in Audience → Contacts: phone numbers are E.164, email and consent state match the source, and custom attributes carried over.
  • Lists and segments exist under Audience → Segments (Klaviyo) with their definitions intact.
  • Templates are visible in the template library and flows under Orchestration → Journeys (Klaviyo) where mappings applied.
  • Complete any source-specific follow-ups: port the phone numbers you want to keep (see Port numbers), and re-register messaging senders where the old registration does not transfer.
  • Only then redirect your integration and run the two platforms in parallel for a window before decommissioning the source.

​
Choose the right migration path

This wizard is the assisted path. Two neighbours cover the cases it does not:
  • Migrate from Twilio — the manual, code-level concept map (TwiML → IVR, webhooks, Verify) for when you are rewriting the integration rather than porting account contents.
  • Run a platform migration end-to-end — the operational reference: managing finished jobs, role requirements, and rollback semantics from Settings → Migrations (including the fifth source, Front, which is operated from there rather than the onboarding wizard).