Skip to content

Moving from Twilio

Move from Twilio, one product at a time

SMS, voice, verification and numbers map closely to what you run today. Here is every name, endpoint and webhook field, side by side, with exactly what you change.

  • JSON and a Bearer key instead of form fields
  • One signed webhook endpoint for every event
  • Run both side by side, then switch
Concepts

The same ideas, under new names

Most of what you know carries straight over. Where a concept works our way, the note says how, and where we go further, it says what you gain.
Twilio concepts and their PacketExchange equivalents
On TwilioAccount SID and Auth TokenOn PacketExchangeAPI key (px_live_sk_...)Our wayOne secret sent as a Bearer token. Create as many keys as you need, scope each one, and revoke any one without touching the rest.
On TwilioAPI Keys (SK... with a secret)On PacketExchangeScoped API keysGoes furtherEach key can be limited to scopes such as sms:send, voice:send, verify:write or numbers:read, so a leaked messaging key cannot buy numbers.
On TwilioTest credentials and magic numbersOn PacketExchangeTest keys (px_test_sk_...)Our wayA test key runs the real path (validation, routing, pricing) and simulates the send against sandbox credit, so a test answers exactly like production. Sandbox credit is added with an invite code.
On TwilioSubaccountsOn PacketExchangeSub-accountsGoes furtherBuilt for reselling. Each sub-account has its own balance, retail rates and keys, and its keys reach calls and SMS only. Your account earns the difference.
On TwilioStatusCallback URL on each requestOn PacketExchangeSigned webhooks per accountGoes furtherRegister an endpoint once and subscribe it to events (sms.delivered, call.completed and others). Every delivery is signed with HMAC SHA-256, logged and can be resent.
On TwilioTwiML (Url or Twiml on a call)On PacketExchangeCall actionsOur wayA list of steps (say, play, gather, pause, hangup) that travels with the request. There is no markup server to host and nothing to fetch while the call rings.
On TwilioVerify ServicesOn PacketExchangeVerify APIOur wayNo service to create first. Brand, code length, language and expiry go on each start request, and there is no fee per verification.
On TwilioLookupOn PacketExchangeNumber lookupGoes furtherValidation, formatting, country, line type and network, plus the cheapest live voice and SMS price to reach the number. Free on every account.
On TwilioPhone Numbers (IncomingPhoneNumbers)On PacketExchangeNumber storeOur waySearch and request by API. Each purchase carries a sentence on how the number will be used and is reviewed by our team before it is charged, which keeps numbers clean for everyone.
On TwilioElastic SIP TrunkingOn PacketExchangeBusiness SIP trunksOur wayPlans or pay as you go, IP allow list and digest credentials, inbound delivery to your PBX, on routes whose caller ID passed a handset test.
On TwilioConsoleOn PacketExchangeDashboardSameKeys, balance, message and call history, webhooks and their delivery log, numbers and their routing, all in one place.
On TwilioUsage and billingOn PacketExchangePrepaid balanceGoes furtherTop up from $5 by card or crypto, or with an x402 payment. Every reply states what that request cost.
Your first request

Sending a message, before and after

Three things change on every call: the body is JSON, the key goes in an Authorization: Bearer header, and delivery updates go to the webhook you registered once instead of a URL on each request.

Before, on Twilio

twilio: send a message
import twilio from 'twilio';

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

const message = await client.messages.create({
  to: '+447700900123',
  from: 'Acme',
  body: 'Your order 1042 has shipped.',
  statusCallback: 'https://example.com/sms-status',
});
console.log(message.sid, message.status);

After, on PacketExchange

packetexchange: send a message
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;
}

// Delivery updates go to the webhook you registered once, not a per-request URL.
// The idempotency key makes a retry replay the reply instead of sending twice.
const sms = await px('POST', '/comms/sms',
  { to: '+447700900123', from: 'Acme', message: 'Your order 1042 has shipped.' },
  { 'X-Idempotency-Key': randomUUID() },
);
console.log(sms.messageId, sms.status, sms.segments, sms.cost);

The reply already holds the segments billed and the exact cost, so there is no second lookup for the price.

Endpoint by endpoint

The calls your code makes today map across, one by one.

Endpoints

Endpoint by endpoint

All paths sit under https://packetexchange.io/api/v1. Grouped the way you will move them.

Messaging

Messaging endpoints
On TwilioSend a message. POST /2010-04-01/Accounts/{AccountSid}/Messages.jsonOn PacketExchangePOST /comms/smsSameJSON body with to, from and message. The reply carries the segments billed and the exact cost.
On TwilioFetch a message. GET .../Messages/{MessageSid}.jsonOn PacketExchangeGET /comms/sms/{messageId}SameReturns the status timeline, delivered or failed once a carrier receipt arrives.
On TwilioList messages. GET .../Messages.jsonOn PacketExchangeGET /comms/smsSamePaged by date.
On TwilioSend many at once. One request per messageOn PacketExchangePOST /comms/sms/bulkGoes furtherUp to 1,000 messages in one request on an SMS route you bought, with a status for each.
On TwilioSend from your own number. POST .../Messages.json with From set to your numberOn PacketExchangePOST /dids/{id}/messagesOur wayTwo-way SMS lives on the number itself, with its own inbox and threads.

Voice

Voice endpoints
On TwilioPlace a call. POST .../Calls.jsonOn PacketExchangePOST /comms/callsSameWaits for the call to end by default; send "async": true to get the id back at once.
On TwilioFetch a call. GET .../Calls/{CallSid}.jsonOn PacketExchangeGET /comms/calls/{id}SameStatus, timestamps, duration, cost, hangup cause and any keys pressed.
On TwilioList calls. GET .../Calls.jsonOn PacketExchangeGET /comms/callsSamePaged history.

Verify

Verify endpoints
On TwilioStart a verification. POST verify.twilio.com/v2/Services/{ServiceSid}/VerificationsOn PacketExchangePOST /verify/startSameChannels sms, voice and call_in (the user calls a number and the call itself verifies them).
On TwilioCheck a code. POST .../Services/{ServiceSid}/VerificationCheckOn PacketExchangePOST /verify/checkOur wayChecked by verificationId and code, not by phone number and code. A wrong code is a normal 200 with status denied.
On TwilioFetch a verification. GET .../Verifications/{Sid}On PacketExchangeGET /verify/{id}SameAlso GET /verify to list by your own reference, status or channel.

Phone numbers

Phone numbers endpoints
On TwilioSearch available numbers. GET .../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 TwilioBuy a number. POST .../IncomingPhoneNumbers.jsonOn PacketExchangePOST /dids/requestsOur wayA purchase request with a short justification. It is charged and provisioned once our team approves it.
On TwilioList your numbers. GET .../IncomingPhoneNumbers.jsonOn PacketExchangeGET /dids/mineSameEach number with its status, renewal and routing.
On TwilioPoint a number. POST .../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 TwilioRelease a number. DELETE .../IncomingPhoneNumbers/{Sid}.jsonOn PacketExchangePOST /dids/{id}/releaseSameStops renewal and gives the number back.

Lookup

Lookup endpoints
On TwilioLook up a number. GET lookups.twilio.com/v2/PhoneNumbers/{PhoneNumber}On PacketExchangeGET /lookup/{number}Goes furtherFree, with the cheapest live voice and SMS price to reach the number in the same answer.

Account and webhooks

Account and webhooks endpoints
On TwilioWebhook endpoints. Set per request or per numberOn PacketExchangePOST /account/webhooksGoes furtherOne endpoint, many events, a delivery log at GET /account/webhooks/deliveries and a resend for any delivery.
On TwilioAPI keys. POST .../Keys.jsonOn PacketExchangePOST /account/api-keysSameCreated from a signed-in session; scopes and test or live set at creation.
Webhooks

Webhooks, translated

This is the part that changes most. Twilio posts form fields to a URL you set per request or per number and signs them with HMAC-SHA1. We post one JSON shape, { event, data, timestamp }, to the endpoints you registered, signed with HMAC-SHA256 over the timestamp and the body, logged and resendable.

Message status fields

Message status callback fields
On TwilioForm-encoded POSTOn PacketExchangeJSON POST { event, data, timestamp }Our wayParse JSON, then switch on event.
On TwilioX-Twilio-Signature (HMAC-SHA1 of URL and params)On PacketExchangeX-PX-Signature v1 (HMAC-SHA256 of timestamp and body)Goes furtherCheck it over the raw bytes and refuse anything older than five minutes.
On TwilioMessageSidOn PacketExchangedata.messageIdSameThe id the send returned.
On TwilioMessageStatusOn PacketExchangeevent (sms.sent, sms.delivered, sms.failed) and data.statusOur wayOne event per state instead of one field.
On TwilioErrorCodeOn PacketExchangedata.errorCodeOur wayOur own codes, plus the carrier receipt values in carrierStatus and carrierError, so support can see what the network said.
On TwilioTo, FromOn PacketExchangedata.to, data.fromSameAs sent.

Call status fields

Call status callback fields
On TwilioCallSidOn PacketExchangedata.callIdSameThe id the call returned.
On TwilioCallStatusOn PacketExchangeevent (call.ringing, call.answered, call.completed) and data.statusOur wayFinal states are completed, no_answer, busy and failed.
On TwilioCallDurationOn PacketExchangedata.durationSeconds and data.billableSecondsOur wayTalk time and the billed time it was rounded to.
On TwilioDigits (Gather action URL)On PacketExchangecall.gathered data.digitsOur wayOne call.gathered event per gather, with the digits pressed.
On TwilioSipResponseCodeOn PacketExchangedata.sipResponseCode and data.hangupCauseSameThe hangup cause comes in plain words too.
On TwilioPrice (filled in later)On PacketExchangedata.costGoes furtherThe final cost is in the completion event and on the call itself.

Register the endpoint once

POST /account/webhooks
curl https://packetexchange.io/api/v1/account/webhooks \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/px-events",
    "events": ["sms.sent", "sms.delivered", "sms.failed",
               "call.answered", "call.gathered", "call.completed",
               "verification.approved", "number.sms.received"]
  }'

Create it in the dashboard, or with a key that holds the webhooks:write scope. The reply carries the signing secret; every delivery is listed with its response at GET /account/webhooks/deliveries.

The handler, before and after

Before, on Twilio

twilio: status callback handler
import express from 'express';
import twilio from 'twilio';

const app = express();

// Form-encoded body, signed with X-Twilio-Signature over the URL and params.
app.post('/sms-status',
  express.urlencoded({ extended: false }),
  twilio.webhook(process.env.TWILIO_AUTH_TOKEN),
  (req, res) => {
    const { MessageSid, MessageStatus, ErrorCode } = req.body;
    if (MessageStatus === 'delivered') markDelivered(MessageSid);
    if (MessageStatus === 'failed' || MessageStatus === 'undelivered') markFailed(MessageSid, ErrorCode);
    res.sendStatus(204);
  });

After, on PacketExchange

packetexchange: webhook handler
import express from 'express';
import { createHmac, timingSafeEqual } from 'node:crypto';

const app = express();

// Raw bytes in, so the signature is checked over exactly what was sent.
app.post('/px-events', express.raw({ type: 'application/json' }), (req, res) => {
  const ts = req.get('X-PX-Timestamp') ?? '';
  const mac = createHmac('sha256', process.env.PACKETEXCHANGE_WEBHOOK_SECRET)
    .update(`${ts}.`).update(req.body).digest('hex');
  const expected = Buffer.from(`v1=${mac}`);
  const given = Buffer.from(req.get('X-PX-Signature') ?? '');
  const fresh = /^\d+$/.test(ts) && Math.abs(Date.now() / 1000 - Number(ts)) < 300;
  // Refuse stale or unsigned deliveries; compare in constant time.
  if (!fresh || given.length !== expected.length || !timingSafeEqual(given, expected)) {
    return res.sendStatus(401);
  }

  // One event per state, instead of one MessageStatus field.
  const { event, data } = JSON.parse(req.body);
  if (event === 'sms.delivered') markDelivered(data.messageId);
  if (event === 'sms.failed') markFailed(data.messageId, data.errorCode);
  res.sendStatus(204);
});

One handler serves every event you subscribed to; switch on event instead of reading MessageStatus.

The cutover

Run both side by side, then move each product when the figures agree.

Cutover plan

Nine steps, no big bang

Each product moves on its own, with both platforms live until the new path has proved itself on real traffic.
  1. Step 1

    Open an account and verify it

    Sign up, then complete the identity check in the dashboard. It is needed before you buy routes or phone numbers, so do it first and it never holds up the cutover.
  2. Step 2

    Fund it

    Top up from $5 by card or crypto, or let software pay with an x402 payment. Everything bills from that one prepaid balance, and every reply says what the request cost.
  3. Step 3

    Create scoped keys

    One test key, and one live key per service with only the scopes it needs: sms:send, voice:send, verify:write or numbers:read. They replace your Account SID and Auth Token, and each can be revoked on its own.
  4. Step 4

    Register one webhook endpoint

    Instead of a StatusCallback on every request, register one HTTPS endpoint and subscribe it to the events you handle. Store its signing secret and check X-PX-Signature on every delivery.
  5. Step 5

    Run your flows on the test key

    A test key goes down the real path, validation, routing, segment counting and pricing, then simulates the send and marks it simulated: true. Sandbox credit is added with an invite code, so your balance is never touched.
  6. Step 6

    Move one product at a time

    Put each product behind a switch in your code and start with the simplest: verification codes or transactional SMS. Voice follows once your call scripts are mapped to call actions (see the voice guide).
  7. Step 7

    Run both side by side

    Send a share of live traffic through PacketExchange and keep the rest where it is. Compare delivery and cost per destination; the cost is in every reply, so there is nothing to reconcile later.
  8. Step 8

    Bring your numbers across

    Request numbers in the countries you need, publish them beside the old ones, and retire the old numbers once callers and replies have moved. The numbers guide covers the overlap.
  9. Step 9

    Switch off, then tidy up

    When a product runs cleanly on its own, turn the old path off. Keep the old credentials until the last delivery receipts and call records have arrived, then revoke them.
Checklist

Before you switch a product over

  • Requests send JSON with Authorization: Bearer and your API key
  • Numbers are E.164, with or without the plus
  • Body is renamed to message on SMS
  • Every send carries an X-Idempotency-Key
  • StatusCallback URLs are gone and one webhook endpoint is registered
  • X-PX-Signature is checked over the raw body, with a five-minute window
  • Code that read price later reads cost from the reply
  • Call statuses use underscores, so no_answer rather than no-answer
  • Verification checks keep and send the verificationId
  • TwiML is replaced with call actions sent with each call
  • A balance.low webhook or a spend alert tells you before the balance runs out
What you gain

What the move adds

The same jobs, with the market and the money in the open. The full comparison goes product by product.
  • A carrier marketplace under every request

    Each message and call rides a route a carrier listed, priced and measured. Pick cheapest, best quality or balanced per request, or name a route you bought.
  • The exact cost in every reply

    Segments, rate and fee are booked before the request leaves, so finance never waits for a usage report and a failed send is refunded on the spot.
  • A published fee with a ceiling

    The carrier rate plus 2%, never more than $0.001 a message or call, and no fee per verification.
  • Retries that never double-send

    An X-Idempotency-Key on a send replays the original reply for 24 hours instead of sending and billing twice.
  • Caller ID you have seen arrive

    Test a route on a real handset in the destination before you send traffic, and run trunks on routes that passed.
  • One balance for everything

    Messaging, voice, numbers and AI voice agents draw on one prepaid balance with one ledger, topped up by card, crypto or x402.
Questions

Moving over, answered

Is the API compatible with Twilio’s, so my code works unchanged?
For messaging, yes. Your Twilio SDK can send, fetch and list messages and receive status callbacks through our compatible API: change the credentials and add one small HTTP client, as the messaging guide shows. Voice, verification and numbers use our own API with JSON bodies and a Bearer key, and each call maps one to one, so the change is mechanical.
How do I move my numbers?
Request numbers in the same countries, run them alongside your current ones, and retire the old ones once traffic has moved. Every number purchase is a request with a sentence on how the number will be used, reviewed by our team before it is charged.
Are there SDKs?
Yes. The packetexchange packages on npm and PyPI cover Node and Python, and every quickstart is written for raw HTTP in eight languages, so nothing depends on a library. The samples on this page use plain fetch and requests for the same reason.
Can I keep my TwiML?
Your TwiML maps to call actions: a short list of steps (say, play, gather, pause and hangup) sent with the call, so there is no markup server to host. Keys pressed arrive on the call.gathered webhook. The voice guide maps each verb and shows how to carry a flow that branches on input.
How does billing differ?
You pay from a prepaid balance at the carrier rate of the route the request used, plus a platform fee of 2% of that cost, never more than $0.001 a message or call. The exact cost is in every reply. A refused or failed message is refunded, and an unanswered call costs nothing.
How do I test before going live?
Test keys run the full path and simulate the send against sandbox credit, which is added with an invite code. Live traffic starts with a top-up from $5, with no contract and no monthly fee.
Do delivery receipts work the same way?
A message moves to delivered only on a carrier receipt that says so, never by inference, and the sms.delivered and sms.failed events tell you when it happens. Each message record shows whether its route has returned receipts recently, so you know what to expect per destination.

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.