Skip to content

Moving from Twilio

Phone numbers, step by step

Search, request and point numbers by API. Inbound calls are configured on the number instead of answered with TwiML, and new numbers run beside your old ones while you move.

  • IVR, hours and voicemail built in
  • Run both side by side while you move
  • Every number reviewed, kept clean
Read first

Two things that shape the plan

  • Run new numbers beside the old

    Request numbers here in the same countries, publish them beside your current ones, and retire the old ones when callers have moved. Nobody loses a call while you switch.
  • Every purchase is approved

    A purchase is a request with a sentence or two on how the number will be used: what calls it will receive, who will call it and where it will be published. Our team approves it, then it is charged and provisioned. Filing a request charges nothing.
  • Verify your account first

    Numbers need a verified account. Complete the identity check before you file requests so approval is not held up.
  • Prices are per number

    A setup price and a monthly price per number, shown in the catalogue before you ask. Renewal is automatic unless you switch it off.
Endpoints

Endpoint by endpoint

Phone number endpoints
On TwilioGET .../AvailablePhoneNumbers/{Country}/Local.jsonOn PacketExchangeGET /dids/search or GET /dids/catalogSameSearch by digits (starts with, contains, ends with) or browse by country and type.
On TwilioPOST .../IncomingPhoneNumbers.jsonOn PacketExchangePOST /dids/requestsOur wayA purchase request with a short justification. It is charged and provisioned once our team approves it.
On TwilioGET .../IncomingPhoneNumbers.jsonOn PacketExchangeGET /dids/mineSameEach number with its status, renewal and routing.
On TwilioPOST .../IncomingPhoneNumbers/{Sid}.json with VoiceUrl, SmsUrlOn PacketExchangePATCH /dids/{id}/routing and PUT /dids/{id}/sms-settingsOur wayCalls go to a SIP address, a phone number or a hosted line; SMS can be forwarded to your webhook URL.
On TwilioDELETE .../IncomingPhoneNumbers/{Sid}.jsonOn PacketExchangePOST /dids/{id}/releaseSameStops renewal and gives the number back.
Inbound

What your VoiceUrl did, as settings

Most inbound TwiML does one of a handful of things. Each of those is a setting on the number here.
Inbound call handling
TwiML on Twilio<Dial><Sip> to your PBXOn the number hereRouting mode sipSameWith an optional backup target if the first does not answer.
TwiML on Twilio<Dial> to a phone numberOn the number hereRouting mode forwardSameForward to any number in E.164.
TwiML on Twilio<Dial> to several destinationsOn the number hereCall flow, failover or simultaneousSameUp to 25 destinations in order or all at once, with a ring timeout.
TwiML on TwilioTwilio Client or a SIP domainOn the number hereHosted softphone lineGoes furtherMint SIP credentials on the number and ring a softphone or desk phone directly.
TwiML on Twilio<Gather> menuOn the number hereIVR menuGoes furtherUp to 12 options, each to a destination, voicemail or hang up, with a greeting.
TwiML on TwilioBusiness hours logic in TwiMLOn the number hereOpening hoursGoes furtherWeekly hours, holidays and a time zone, with what to do outside them.
TwiML on Twilio<Record> as voicemailOn the number hereVoicemailOur wayOn no answer or always, with your greeting and an optional transcription.
TwiML on TwilioRecord on <Dial>On the number hereCall recordingOur wayWith or without an announcement, kept for the period you choose.

Inbound messages

Inbound message handling
On TwilioSmsUrl webhook replying with TwiMLOn PacketExchangenumber.sms.received event or the number’s forward URLOur wayA notification, not a reply instruction. Send a reply with POST /dids/{id}/messages.
On TwilioBody, From, ToOn PacketExchangedata.body, data.from, data.toSamePlus data.segments and data.receivedAt.
Running both

Moving callers with no gap in service

  1. Step 1

    Request the new numbers

    Same countries and types as today. Point them at the same destinations as your Twilio numbers, so callers reach the same place whichever number they dial.
  2. Step 2

    Publish both

    Add the new numbers to your website, emails and printed material, and set them as the caller ID and sender on outbound traffic you have moved.
  3. Step 3

    Watch traffic move

    Calls and messages on each number are reported with number.call.received and number.sms.received, and the dashboard shows per-number analytics.
  4. Step 4

    Release the old numbers

    When inbound traffic on a Twilio number has dropped to nothing for long enough to be sure, release it there.

Numbers

Every number shows its monthly price before you ask for it.

Steps

Moving it over

  1. Step 1

    Create a numbers key

    numbers:read to search and list, numbers:write to request, point and release.
  2. Step 2

    Search

    GET /dids/search by digits (starts with, contains, ends with, exact) or GET /dids/catalog by country and type. Each hit carries a groupId and its SKUs with setup and monthly prices.
  3. Step 3

    Request

    POST /dids/requests with the groupId, skuId and your justification. GET /dids/requests shows where each request stands.
  4. Step 4

    Point it

    Once approved, the number appears on GET /dids/mine. Set calls with PATCH /dids/{id}/routing and messages with PUT /dids/{id}/sms-settings.
  5. Step 5

    Add the extras

    Voicemail, recording, an IVR menu and opening hours are settings on the number, by API or in the dashboard.
  6. Step 6

    Subscribe to activity

    number.call.received, number.sms.received and number.voicemail.received report what reached each number.
Code

Find, get and point a number, before and after

Before, on Twilio

twilio: find, buy and point a number
import twilio from 'twilio';

const client = twilio(process.env.TWILIO_ACCOUNT_SID, process.env.TWILIO_AUTH_TOKEN);

const [found] = await client.availablePhoneNumbers('GB').local.list({ limit: 1 });

const number = await client.incomingPhoneNumbers.create({
  phoneNumber: found.phoneNumber,
  voiceUrl: 'https://example.com/voice',   // TwiML for inbound calls
  smsUrl: 'https://example.com/sms',       // inbound messages
});
console.log(number.sid, number.phoneNumber);

After, on PacketExchange

packetexchange: find, request and point a number
import { randomUUID } from 'node:crypto';

const API = 'https://packetexchange.io/api/v1';

// One JSON request with your API key as a Bearer token.
async function px(method, path, body, headers = {}) {
  const res = await fetch(API + path, {
    method,
    headers: {
      Authorization: `Bearer ${process.env.PACKETEXCHANGE_API_KEY}`,
      'Content-Type': 'application/json',
      ...headers,
    },
    body: body === undefined ? undefined : JSON.stringify(body),
  });
  const json = await res.json();
  if (!res.ok) throw new Error(`${res.status} ${json.error?.code}: ${json.error?.message}`);
  return json.data;
}

// 1. Search by the digits you want. Each hit has a groupId and its SKUs.
const { hits } = await px('GET', '/dids/search?pattern=4420&match=starts_with&limit=5');
const hit = hits[0];

// 2. Request it. Our team approves, then it is charged and provisioned.
const request = await px('POST', '/dids/requests', {
  groupId: hit.groupId,
  skuId: hit.skus[0].skuId,
  justification: 'Support line for our UK customers, printed on invoices and our website.',
}, { 'X-Idempotency-Key': randomUUID() });

// 3. Once it is yours (GET /dids/mine), point calls and messages where you want them.
const didId = (await px('GET', '/dids/mine'))[0].id;
await px('PATCH', `/dids/${didId}/routing`, { mode: 'sip', target: 'sip:support@pbx.example.com' });
await px('PUT', `/dids/${didId}/sms-settings`, {
  smsEnabled: true,
  forwardWebhookUrl: 'https://example.com/inbound-sms',
});

Step 3 runs once the request is approved and the number shows on GET /dids/mine.

Gotchas

Things that catch people out

  • Order numbers ahead of the cutover

    Requests are reviewed quickly, so file them a little before you need them, and let your script use a number once it shows on GET /dids/mine.
  • Keep renewals funded

    Renewals draw on the prepaid balance. An unpaid number is suspended and held for a grace period, five days by default, before it is released.
  • Custom inbound logic

    If your VoiceUrl app does more than route, menu, record or take voicemail, point the number at your own PBX over SIP and keep that logic there.
  • Capacity per number

    Each number has a concurrent call capacity you can read and change, so a busy line can be sized to its traffic.
Questions

Numbers, answered

How do I move my callers across?
Request numbers here, run them beside your Twilio numbers pointed at the same destinations, and release the old ones once traffic has moved.
Why does a number need approval?
Every number purchase is reviewed so numbers are not used for abuse. The request asks how the number will be used, and nothing is charged until it is approved.
Can a number receive SMS?
Where the number supports it. Switch SMS on for the number, then set a forward URL or subscribe to number.sms.received, and reply with POST /dids/{id}/messages.
Can I buy numbers for my own customers?
Yes. Pass a subAccountId to hold the number for one of your sub-accounts; your own balance pays for it.

Start with a test key

Open a free account, create a test key and run your existing flows against the real path without sending anything. Move live traffic when it matches.

Twilio is a trademark of Twilio Inc. PacketExchange is not affiliated with or endorsed by Twilio.