Migration from Twilio

Step-by-step guide to migrate your Twilio integration to Orbit

Migration from Twilio to Orbit

This guide walks you through migrating your SMS, voice, and messaging integration from Twilio to Orbit. Most Twilio concepts map directly to Orbit equivalents, and the migration can be completed incrementally.

Concept Mapping

Twilio Concept	Orbit Equivalent	Notes
Account SID + Auth Token	API Key (dv_live_sk_xxxx)	Single key, simpler auth
Phone Numbers	Numbers API	Same capabilities, lower cost
Messaging Service	Campaigns + Number pools	Built-in sender selection
TwiML	IVR API + Agents	Declarative IVR or AI agents
Studio Flows	Flows (visual builder)	Drag-and-drop flow builder
Programmable Voice	Voice API	Calls, SIP, conferences
Verify	Verify API	OTP/2FA
Conversations	Agent conversations	AI-native conversations
Webhooks	Webhooks	Same pattern, different headers
Status Callbacks	Webhook events	message.delivered, call.completed

---

Step 1: Create Your Orbit Account

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

---

Step 2: Port Your Numbers

You can port existing Twilio numbers to Orbit. The process takes 7–14 business days.

Via API:

curl -X POST https://orbit-api.devotel.io/api/v1/numbers/port \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "numbers": ["[phone]", "[phone]"],
    "current_carrier": "Twilio",
    "authorization_name": "Your Name"
  }'

Alternative: Purchase new numbers and update your systems gradually.

---

Step 3: Update SMS Integration

Twilio (Before)

const twilio = require('twilio')
const client = twilio('ACXXXXXXX', 'auth_token')

await client.messages.create({
  to: '[phone]',
  from: '[phone]',
  body: 'Hello from Twilio!',
  statusCallback: 'https://yourapp.com/webhooks/sms',
})

Orbit (After)

import { Devotel } from '@devotel/sdk'

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

await orbit.messages.send({
  channel: 'sms',
  to: '[phone]',
  body: 'Hello from Orbit!',
  webhookUrl: 'https://yourapp.com/webhooks/sms',
})

Key Differences

Feature	Twilio	Orbit
Auth	Account SID + Token	Single API key in X-API-Key
Send endpoint	client.messages.create()	orbit.messages.send()
Channel selection	Implicit (number type)	Explicit channel field
From number	Required from field	Auto-selected or specified
Status webhook	statusCallback	webhookUrl or global webhooks

---

Step 4: Update Webhook Handlers

Webhook Header Changes

Twilio	Orbit
X-Twilio-Signature (HMAC-SHA1)	X-Devotel-Signature (HMAC-SHA256)

Payload Format Changes

Twilio (form-encoded):

MessageSid=SM123&From=%2B14155551234&To=%2B14155552671&Body=Hello&MessageStatus=delivered

Orbit (JSON):

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

Update Signature Verification

// Twilio (before)
const valid = twilio.validateRequest(authToken, signature, url, params)

// Orbit (after)
import { verifyWebhookSignature } from '@devotel/sdk'
const valid = verifyWebhookSignature(rawBody, signature, 'whsec_your_secret')

---

Step 5: Migrate Voice (if applicable)

TwiML to Orbit IVR

Twilio TwiML:

<Response>
  <Gather input="dtmf" numDigits="1" action="/handle-key">
    <Say>Press 1 for sales, 2 for support.</Say>
  </Gather>
</Response>

Orbit IVR API:

curl -X POST https://orbit-api.devotel.io/api/v1/voice/ivr \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Main Menu",
    "greeting": "Press 1 for sales, 2 for support.",
    "menu": {
      "options": [
        { "key": "1", "action": "transfer_agent", "target": "agt_sales" },
        { "key": "2", "action": "transfer_agent", "target": "agt_support" }
      ]
    }
  }'

Upgrade to AI Agents

Instead of static IVR trees, consider deploying an AI voice agent:

curl -X POST https://orbit-api.devotel.io/api/v1/agents \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Voice Support Agent",
    "type": "conversational",
    "model": "gpt-4o",
    "system_prompt": "You are a helpful phone support agent for Acme Corp.",
    "channels": ["voice"]
  }'

---

Step 6: Migrate Verify (OTP)

Twilio (Before)

await client.verify.v2.services('VA123').verifications.create({
  to: '[phone]',
  channel: 'sms',
})

const check = await client.verify.v2.services('VA123').verificationChecks.create({
  to: '[phone]',
  code: '123456',
})

Orbit (After)

const verification = await orbit.verify.start({
  to: '[phone]',
  channel: 'sms',
})

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

---

Migration Checklist

• Create Orbit account and generate API keys
• Port numbers or purchase new ones
• Install Orbit SDK (npm install @devotel/sdk)
• Update message sending code
• Update webhook endpoint handlers
• Update webhook signature verification
• Migrate voice/IVR flows (if applicable)
• Migrate Verify/OTP (if applicable)
• Update monitoring and alerting
• Run parallel testing (send via both Twilio and Orbit)
• Decommission Twilio integration
• Cancel Twilio account

---

Parallel Running Strategy

We recommend running Twilio and Orbit in parallel during migration:

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

Need help with your migration? Our solutions team offers free migration support for customers moving from Twilio. Contact [e-mail].