Migration from Vonage to Orbit

This guide walks you through migrating your SMS, voice, and webhook integration from Vonage (formerly Nexmo) to Orbit. The migration moves fastest if you translate your Vonage-shaped concepts into Orbit concepts first — most have a direct equivalent. Follow the Migrate from Twilio guide’s sibling structure if you run multiple vendor comparisons.

Concept Mapping

Vonage Concept	Orbit Equivalent	Notes
API key + secret, or Application `private.key` JWT	API Key (`dv_live_sk_xxxx`)	One key in the `X-API-Key` header — no JWT generation or keypair rotation
Vonage Applications (voice + webhook URLs)	Messaging Services	Bundles senders, opt-out rules, and inbound webhook config; pass its id as `messaging_service_id` when you send
Vonage Numbers	Numbers API	Buy, port, and assign numbers per service
Vonage Conversations API	Agent conversations	AI-native conversations (see two-way SMS conversations)
`signature` JWT per webhook (or webhook JWT toggle)	`X-Orbit-Signature` HMAC-SHA256 header	Verify per the webhook consumer guide; no JWT library needed
NCCO (JSON call-control objects)	IVR flows API + voice agents	`{ nodes, edges }` graphs; the visual builder saves the same shape
Vonage Verify	Verify API	OTP/2FA with fallback chains
Delivery receipts (`dlr`)	`message.delivered` / `message.failed` events	Same status funnel, different event names
Inbound SMS webhook	`message.inbound` event	Registered on a webhook endpoint, not per-number

Prefer not to do it by hand?

Honest answer up front: the assisted import wizard (dashboard: Settings → Import; CLI: devotel migrate <source>) currently ships connectors for Twilio, Klaviyo, MessageBird, and Telnyx — Vonage is not on the list yet, so this guide is a manual-level path with no one-click wizard. Every step below is copy-paste-ready and the two long-horizon pieces (porting numbers and retooling webhook handlers) are the only parts that touch your account before cut-over; the rest is code on your side. If you have a large estate and want the sequence scripted end-to-end, the same import pipeline carries an external_id label per entity even for manual flows, so your backfill reports stay vendor-consistent. See Platform migration jobs for the job runner.

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

Unlike Vonage — where an Application-scoped JWT signs each request — Orbit authenticates with a flat API key sent in the X-API-Key header. There is no keypair, no private.key file, and no JWT expiry to babysit.

Step 2: Port Your Numbers

Port existing Vonage numbers to Orbit following the Porting numbers end-to-end flow. Expect 7–14 business days; Vonage’s Letter of Authorization (LoA) flow needs the Customer Service Record (CSR) from your Vonage account page, not guessed values — rejections like ADDRESS_MISMATCH and NAME_MISMATCH almost always trace back to a copied-instead-of-guessed field. Vonage quirks to note on the CSR pull:

If your Vonage account holds numbers across sub-accounts, pull the CSR for the master account; the legal entity name must match the one Vonage bills.
SMS-enabled numbers: declare it on the LoA so the carrier ports voice and messaging together; a response of splittable: true on the portability check warns you the carrier may move voice only.

A port request must carry an LoA URL issued by Orbit, so upload the signed PDF to Orbit first and submit the returned URL — a link to your own bucket is rejected with LOA_URL_INVALID_ORIGIN:

# 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 port request, passing the uploaded `data.url` as loaFileUrl.
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", "+14155551235"],
    "currentCarrier": "Vonage",
    "country": "US",
    "authorizedSigner": "Your Name",
    "accountNumber": "123456789",
    "accountPin": "1234",
    "loaFileUrl": "https://storage.googleapis.com/.../loa.pdf?X-Goog-Signature=..."
  }'

Alternative: purchase new numbers on Orbit and update your systems gradually — the full checklist is in the porting guide linked above.

Step 3: Rewrite SMS Sends

Vonage (before)

const { Vonage } = require('@vonage/server-sdk')

const vonage = new Vonage({
  apiKey: 'vongexxx',
  apiSecret: 'secret',
})

await vonage.messages.send({
  to: '+14155552671',
  from: '+18005551234',
  message_type: 'text',
  text: 'Hello from Vonage!',
})

Orbit (after)

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

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

await orbit.messages.send({
  channel: 'sms',
  to: '+14155552671',
  body: 'Hello from Orbit!',
  status_callback: 'https://yourapp.com/webhooks/sms',
})

Key Differences

Feature	Vonage	Orbit
Auth	API key + secret (or per-request JWT)	Single API key in `X-API-Key`
Send endpoint	`POST /v1/messages` (or SMS API `/rest/sms`)	`POST /api/v1/messages`
Payload format	`message_type` + `text` (+ optional per-message `webhook_url`)	`channel` + `body` (`status_callback` optional)
From number	Required `from` field	Auto-selected or specified
Delivery status	`dlr` webhook configured per Application	`message.delivered` / `message.failed` events or `status_callback` per send

Vonage’s Messages API accepted channel alternatives (sms, mms, whatsapp, …) in message_type; Orbit makes the channel an explicit channel field, which reads the same way in code.

Step 4: Rewrite Inbound and Status Webhook Handlers

Webhook Header Changes

Vonage	Orbit
`signature` field inside the payload (JWT trickle, validated with your public key) or Authorization header	`X-Orbit-Signature` HMAC-SHA256 header

Verify against X-Orbit-Signature — it is the canonical header Orbit sends on every delivery. X-Devotel-Signature is still emitted for backward compatibility only; treat it as legacy and do not build new verifiers against it. The webhook consumer guide has the full receiver recipe (raw-body capture, timestamp window, rotation grace header X-Orbit-Signature-Next).

Payload Format Changes

Vonage sends webhook payloads as JSON at application level, but inbound SMS (from the legacy SMS API) arrives as query/form-encoded pairs. Orbit delivers one canonical JSON envelope for every event: Vonage SMS API inbound (form-encoded):

msisdn=14155551234&to=18005551234&text=Hello&messageId=0B00000123

Orbit inbound (JSON):

{
  "id": "evt_msg_001",
  "type": "message.inbound",
  "created_at": "2026-03-08T12:00:00Z",
  "data": {
    "message_id": "msg_abc123",
    "channel": "sms",
    "from": "+14155551234",
    "to": "+18005551234",
    "body": "Hello"
  }
}

Event-Name Mapping

Map each Vonage webhook subscription to its Orbit event type. Subscribe your endpoint to the Orbit names in the table; the full catalog is at Webhook events.

Vonage webhook	Orbit event type
SMS API inbound (`/sms` webhook)	`message.inbound`
Messages API inbound (`message.inbound` under Messages API)	`message.inbound`
Delivery receipt (`dlr` / `message.status` with `status: delivered\|failed\|rejected`)	`message.delivered` / `message.failed`
Voice `event_url` (answer/completed)	`call.completed`
RTC/Conversation events (member joined, message sent)	Agent conversation events (optional — most teams drop these on migration)

Signature Verification (Vonage JWT trickle → Orbit HMAC)

// Vonage (before) — JWT signature validation per webhook
import jwt from 'jsonwebtoken'
const valid = jwt.verify(payload.signature, publicKey, { algorithms: ['RS256'] })

// Orbit (after) — shared-secret HMAC over the raw body
import { verifyWebhookSignature } from '@devotel-orbit/node'
const valid = verifyWebhookSignature(rawBody, signature, 'whsec_your_secret')

Orbit’s scheme is plain HMAC-SHA256 over the exact raw request body with a shared whsec_ secret you copy once when you register the endpoint. Most teams remove a JWT library from the receiver’s dependency list at this step.

Step 5: Migrate Voice (if applicable)

NCCO to Orbit IVR

Vonage steers a call with NCCO — a JSON array of actions (talk, input, connect, stream, …) returned from your answer_url. In Orbit, the equivalent is an IVR flow: a { nodes, edges } graph (the same shape the visual IVR builder saves), created with POST /api/v1/voice/ivr-flows and published so inbound callers see it. Vonage NCCO (from your answer_url):

[
  {
    "action": "talk",
    "text": "Press 1 for sales, 2 for support."
  },
  {
    "action": "input",
    "type": ["dtmf"],
    "dtmf": { "maxDigits": 1 }
  }
]

Orbit IVR API:

# 1. Create the draft flow
curl -X POST https://api.orbit.devotel.io/api/v1/voice/ivr-flows \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Main Menu",
    "active": true,
    "definition": {
      "nodes": [
        { "id": "start", "type": "ivrStart", "data": {} },
        {
          "id": "menu",
          "type": "menu",
          "data": {
            "prompt": "Press 1 for sales, 2 for support.",
            "menuOptions": [
              { "key": "1", "label": "Sales" },
              { "key": "2", "label": "Support" }
            ]
          }
        },
        { "id": "sales", "type": "transfer", "data": { "transferTo": "+14155550101" } },
        { "id": "support", "type": "transfer", "data": { "transferTo": "+14155550102" } }
      ],
      "edges": [
        { "id": "e1", "source": "start", "target": "menu" },
        { "id": "e2", "source": "menu", "target": "sales" },
        { "id": "e3", "source": "menu", "target": "support" }
      ]
    }
  }'

The graph is validated on save: exactly one entry node (ivrStart), at least one terminal node (transfer, hangup, voicemail, ringGroup, …), no unreachable nodes, and no loops without an exit. DTMF menuOptions[].key values must be 0–9, *, or #. Transfer targets must be phone numbers or on-net extensions — raw sip: URIs are rejected at save (outbound voice exits only via the Devotel softswitch).

# 2. Publish the draft to the live runtime (returns the new version number)
curl -X POST https://api.orbit.devotel.io/api/v1/voice/ivr-flows/{flowId}/publish \
  -H "X-API-Key: dv_live_sk_your_key_here"

Prefer not to hand-author the graph? Build the flow visually at Voice > IVR Builder and publish from the canvas — the API above is the same surface the builder calls.

Upgrade to AI Agents

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

curl -X POST https://api.orbit.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": "voice",
    "model": "claude-sonnet-4-6",
    "system_prompt": "You are a helpful phone support agent for Acme Corp.",
    "channels": ["voice"]
  }'

Step 6: Migrate Verify (OTP)

Vonage (before)

// Vonage Verify API request/verify flow
const verification = await vonage.verify.start({
  number: '+14155552671',
  brand: 'Acme Corp',
})

const check = await vonage.verify.check(verification.request_id, '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',
})

Orbit’s Verify API is send-then-check per request — no per-request brand config is needed because the brand name sits on your Verify profile, not per-call. Fallback chains (SMS → voice) live at the profile level too; see Verify in 30 minutes for the profile setup and the wrong-code error shape.

Migration Checklist

Parallel Running Strategy

We recommend running Vonage and Orbit in parallel during migration:

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

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

WhatsApp

Guides

Messaging Controls

Audience & Support Tools

Migrate from Vonage to Orbit: SMS, voice, and webhooks

Migration from Vonage to Orbit

Concept Mapping

Prefer not to do it by hand?

Step 1: Create Your Orbit Account

Step 2: Port Your Numbers

Step 3: Rewrite SMS Sends

Vonage (before)

Orbit (after)

Key Differences

Step 4: Rewrite Inbound and Status Webhook Handlers

Webhook Header Changes

Payload Format Changes

Event-Name Mapping

Signature Verification (Vonage JWT trickle → Orbit HMAC)

Step 5: Migrate Voice (if applicable)

NCCO to Orbit IVR

Upgrade to AI Agents

Step 6: Migrate Verify (OTP)

Vonage (before)

Orbit (after)

Migration Checklist

Parallel Running Strategy

​Migration from Vonage to Orbit

​Concept Mapping

​Prefer not to do it by hand?

​Step 1: Create Your Orbit Account

​Step 2: Port Your Numbers

​Step 3: Rewrite SMS Sends

​Vonage (before)

​Orbit (after)

​Key Differences

​Step 4: Rewrite Inbound and Status Webhook Handlers

​Webhook Header Changes

​Payload Format Changes

​Event-Name Mapping

​Signature Verification (Vonage JWT trickle → Orbit HMAC)

​Step 5: Migrate Voice (if applicable)

​NCCO to Orbit IVR

​Upgrade to AI Agents

​Step 6: Migrate Verify (OTP)

​Vonage (before)

​Orbit (after)

​Migration Checklist

​Parallel Running Strategy

Migration from Vonage to Orbit

Concept Mapping

Prefer not to do it by hand?

Step 1: Create Your Orbit Account

Step 2: Port Your Numbers

Step 3: Rewrite SMS Sends

Vonage (before)

Orbit (after)

Key Differences

Step 4: Rewrite Inbound and Status Webhook Handlers

Webhook Header Changes

Payload Format Changes

Event-Name Mapping

Signature Verification (Vonage JWT trickle → Orbit HMAC)

Step 5: Migrate Voice (if applicable)

NCCO to Orbit IVR

Upgrade to AI Agents

Step 6: Migrate Verify (OTP)

Vonage (before)

Orbit (after)

Migration Checklist

Parallel Running Strategy