Vonage integrations tend to be small in code and large in what hangs off them: sender numbers, inbound webhooks, delivery handling and a table of opted-out numbers. A migration succeeds when you move those in the right order, not when the send call compiles.

This is a plan, not a reference to Vonage's API. We haven't read their docs for this post, so compare each step with your own code.

Step 1: inventory what you actually use

Write down, per tenant: the numbers you send from, the registration status, the webhook URLs, the opt-out store and any scheduled or bulk jobs. Anything you can't list will break on cutover day.

Step 2: map the calls

Your Vonage code doesReady equivalent
Sends one textPOST /v1/messages with to, body, consent_attested
Sends a batchPOST /v1/messages/bulk, up to 100 per call
Guards against duplicate sendsIdempotency-Key header, one UUID per message
Receives repliesWebhook registered with Ready
Looks up opted-out numbersGET /v1/opt-outs and GET /v1/opt-outs/:phone

For fields and examples, use the messages docs and the quickstart. We list no other endpoints here, because we won't guess.

Step 3: register before you move volume

Each customer business needs its own registration. File it in the app or by API, and most approvals take 2 to 7 days. Until the registration is approved, an account sends up to 500 texts a calendar month, so don't schedule the cutover for an unregistered tenant.

Step 4: bring the opt-outs

Opt-outs don't travel with a number. Export every STOP from your own table and from the provider, then import them into Ready before the first send. See why the STOP list doesn't come with a ported number; the lesson applies to any provider.

Step 5: port or replace numbers

You can port numbers or buy new ones. Porting preserves your customers' sender identity but takes time and has its own failure points. The port checklist gives the order. A new number means a fresh reputation, so warm it up gently.

Step 6: cut over tenant by tenant

Put the provider choice behind a per-tenant flag. Move a small tenant, watch delivery and replies for a few days, then widen. Keep the old path alive until each tenant is stable.

Gotchas

  • Quiet hours. An API text outside the recipient's window is held only if the window opens within 6 hours; otherwise it's refused and you resend. Handle the 409 as in this guide.
  • Consent attestation. From January 20, 2027 an API send without consent_attested is refused.
  • Segment counts. Emoji drop a segment to 70 characters, and every segment is billed.

Frequently asked questions

Will delivery rates change?

They follow registration and content more than the API. Don't promise a change in either direction.

Do I lose anything by leaving?

Possibly channels and global reach. See Vonage vs Ready.

The practical takeaway

Inventory, map, register, import opt-outs, then move one tenant at a time. Open an account to test.