Moving from Twilio
Voice, step by step
Calls.json becomes POST /comms/calls and TwiML becomes a short list of actions that travels with the call, so there is no markup server to host.
- Say, play, gather, pause, hangup
- Nothing to host while the call runs
- Unanswered calls cost nothing
The shape
A script that travels with the call
On Twilio, the call fetches TwiML from your server when it is answered and comes back to you after every Gather. Here, the whole script is part of the request and the switch runs it on its own, so a call speaks, gathers and ends cleanly even while your server is being deployed or is down.
TwiML verbs
Verb by verb
| TwiML | Call action | How close | What to know |
|---|---|---|---|
| TwiML<Say> | Call action{ "say": "..." } | Same | Up to 500 characters a step and 1,500 a call, in en, es, fr, de, pt or hi. Rendered before dialling. |
| TwiML<Play> | Call action{ "play": "https://.../file.mp3" } | Same | A public HTTPS MP3 up to 2 MB, at most three different files a call. We fetch it once; the switch never calls your host. |
| TwiML<Gather> with numDigits, timeout, finishOnKey | Call action{ "gather": { digits, timeout, finishOnKey, tries } } | Our way | Same controls, with a say or play prompt, and up to three tries. The keys arrive on the call.gathered event. |
| TwiML<Pause length> | Call action{ "pause": 1..10 } | Same | Seconds of silence. |
| TwiML<Hangup> | Call action{ "hangup": true } | Same | Must be the last action. The call also ends when the steps run out. |
| TwiML<Reject> | Call actionNumber settings | Goes further | Inbound handling, including opening hours and what happens out of hours, is set on the number with no code. |
Fields
What maps one to one
| On Twilio | On PacketExchange | How close | What to know |
|---|---|---|---|
| On TwilioTo | On PacketExchangeto | Same | E.164. |
| On TwilioFrom | On PacketExchangefrom | Same | The caller ID, E.164. |
| On TwilioUrl or Twiml | On PacketExchangeactions | Our way | Up to 10 steps, chosen from say, play (an HTTPS MP3), gather, pause and hangup. |
| On TwilioTimeLimit | On PacketExchangemaxDuration | Same | 10 to 3,600 seconds, 300 by default. |
| On TwilioStatusCallback and StatusCallbackEvent | On PacketExchangeAccount webhook (call.ringing, call.answered, call.gathered, call.completed) | Our way | Subscribe once; every call reports to it. |
| On TwilioReturns queued, outcome by callback | On PacketExchangeasync | Goes further | Without async the request waits until the call ends and returns the outcome and cost in one reply; with async it returns the id at once. |
Status values
| On Twilio | On PacketExchange | How close | What to know |
|---|---|---|---|
| On Twilioqueued | On PacketExchangequeued | Same | Accepted, not yet dialled. |
| On Twilioringing | On PacketExchangeringing | Same | Being dialled. |
| On Twilioin-progress | On PacketExchangeanswered | Same | Picked up. |
| On Twiliocompleted | On PacketExchangecompleted | Same | Answered and ended. |
| On Twiliono-answer, busy, failed | On PacketExchangeno_answer, busy, failed | Same | Underscores instead of hyphens. Unanswered calls cost nothing. |
Endpoints
| On Twilio | On PacketExchange | How close | What to know |
|---|---|---|---|
| On TwilioPOST .../Calls.json | On PacketExchangePOST /comms/calls | Same | Waits for the call to end by default; send "async": true to get the id back at once. |
| On TwilioGET .../Calls/{CallSid}.json | On PacketExchangeGET /comms/calls/{id} | Same | Status, timestamps, duration, cost, hangup cause and any keys pressed. |
| On TwilioGET .../Calls.json | On PacketExchangeGET /comms/calls | Same | Paged history. |
Branching flows
When your TwiML branches
Most branching TwiML carries over with one of these patterns, from the most common case to the least.
Decide before you dial
Most TwiML apps fetch the script at answer time only to personalise it. Build the same personalised action list in your code and send it with the call.Gather now, act after
For a confirm or cancel, gather the key and act on call.gathered when the call ends: update the booking, send a confirmation SMS, or place a follow-up call with the next script.Menus on inbound calls
Press 1 for sales, 2 for support belongs on the number: an IVR menu that sends each digit to a destination, voicemail or hang up, with opening hours. See the numbers guide.Conversations, not menus
If the call needs to listen and respond, AI voice agents are described in plain English and make outbound calls over your routes.Connecting people
For calls between people, a SIP trunk puts your own PBX or contact centre on carrier routes with tested caller ID.
Voice
A call carries its script from the moment it is placed.
Steps
Moving it over
- Step 1
Create a voice key
A live key limited to voice:send, and a test key. - Step 2
Turn each TwiML document into an action list
Map Say, Play, Gather, Pause and Hangup one to one using the table above. Flows that branch on input carry over with the patterns below. - Step 3
Swap the call
Replace calls.create with POST /comms/calls. Rename TimeLimit to maxDuration, put the steps in actions, and pass async: true if your code expects to return at once. - Step 4
Subscribe to call events
Register your endpoint for call.ringing, call.answered, call.gathered and call.completed, in place of StatusCallback and StatusCallbackEvent. - Step 5
Map the statuses
in-progress becomes answered, and the final states use underscores (completed, no_answer, busy, failed). - Step 6
Test, then share live traffic
Run each flow on the test key, then a share of live calls per destination before moving the rest.
Code
A confirmation call, before and after
Before, on Twilio
twilio: call and read a message
import twilio from 'twilio';
const client = twilio(process.env.TWILIO_ACCOUNT_SID, process.env.TWILIO_AUTH_TOKEN);
const call = await client.calls.create({
to: '+447700900123',
from: '+15555550100',
twiml: '<Response><Say>Your table is ready. Press 1 to confirm.</Say>'
+ '<Gather numDigits="1" action="/confirm"/></Response>',
timeLimit: 120,
statusCallback: 'https://example.com/call-status',
});
console.log(call.sid, call.status);After, on PacketExchange
packetexchange: call and read 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;
}
// The whole script travels with the call and is fixed before it is dialled.
// The key pressed arrives on the call.gathered webhook as the call ends.
const call = await px('POST', '/comms/calls', {
to: '+447700900123',
from: '+15555550100',
maxDuration: 120,
async: true,
actions: [
{ say: 'Your table is ready.' },
{ gather: { say: 'Press 1 to confirm.', digits: 1, timeout: 5, tries: 2 } },
{ say: 'Thank you. Goodbye.' },
{ hangup: true },
],
}, { 'X-Idempotency-Key': randomUUID() });
console.log(call.callId, call.status); // "ringing"The key pressed arrives on the call.gathered event, so the follow-up runs in your webhook handler.
Webhooks
Status callbacks become events
| On Twilio | On PacketExchange | How close | What to know |
|---|---|---|---|
| On TwilioCallSid | On PacketExchangedata.callId | Same | The id the call returned. |
| On TwilioCallStatus | On PacketExchangeevent (call.ringing, call.answered, call.completed) and data.status | Our way | Final states are completed, no_answer, busy and failed. |
| On TwilioCallDuration | On PacketExchangedata.durationSeconds and data.billableSeconds | Our way | Talk time and the billed time it was rounded to. |
| On TwilioDigits (Gather action URL) | On PacketExchangecall.gathered data.digits | Our way | One call.gathered event per gather, with the digits pressed. |
| On TwilioSipResponseCode | On PacketExchangedata.sipResponseCode and data.hangupCause | Same | The hangup cause comes in plain words too. |
| On TwilioPrice (filled in later) | On PacketExchangedata.cost | Goes further | The final cost is in the completion event and on the call itself. |
handling call.gathered and call.completed
// One event per gather, sent as the call ends.
// data: { callId, to, from, index, digits, status: "received" | "no_input" }
if (event === 'call.gathered' && data.index === 0) {
if (data.digits === '1') await confirmBooking(data.to);
else await sendSms(data.to, 'Reply YES to confirm your table.'); // the follow-up, after the call
}
// The outcome and cost, once the call ends.
if (event === 'call.completed') {
await saveCall(data.callId, data.status, data.durationSeconds, data.cost);
}Testing
Prove it before live traffic
- Step 1
Use a test key
A test key validates the request and the actions and returns a simulated outcome without dialling, rendering speech or fetching your audio. - Step 2
Check every play URL once live
On the first live call, a play file that is not a reachable public HTTPS MP3 is a clean 4xx before anything is dialled, and costs nothing. - Step 3
Watch one call end to end
Place one live call to your own phone with async: true and follow it on GET /comms/calls/{id} and your webhook log.
Gotchas
Things that catch people out
Sync calls hold the request open
Without async the request waits until the call ends. Set your HTTP timeout above maxDuration, or use async.maxDuration defaults to 300
Between 10 and 3,600 seconds. Set it to what the script needs so no call runs longer than you planned.Ten call requests a second per key
Spread larger volumes over time or across keys; for campaigns, the dialer is built for it.Unanswered calls cost nothing
You pay the route rate for answered time, rounded to the route’s billing increment, plus the capped platform fee. The final cost is on call.completed.Put the key point first
A voicemail greeting counts as answered, so short scripts with the key point first work best on every platform.Speech is not charged separately
say steps are rendered before dialling at no extra cost, and repeated phrases are reused.
Questions
Voice, answered
How long can a call run?
As long as you set with maxDuration, from 10 to 3,600 seconds, 300 by default. The call ends when its steps are done or the limit is reached, whichever comes first.
How do I get the digits a caller pressed?
Each gather produces a call.gathered event with the digits or no_input. GET /comms/calls/{id} shows them too.
Can I make calls with my own caller ID?
Yes, from is the caller ID in E.164. Whether it is presented depends on the route; caller ID tests ring a real handset in the destination and show what arrived.
What about inbound calls?
Inbound calls are configured on your numbers rather than answered with TwiML: send them to a SIP address, forward them to a phone, ring a hosted line, offer a menu, or take voicemail, with opening hours.
The other guides
Moving the rest
- Overview and cutover planThe concept map, the plan and the checklist for the whole move.
- MessagingMessages.json to POST /comms/sms, status callbacks to signed events, inbound replies on your numbers.
- VerifyServices, Verifications and VerificationCheck to /verify/start and /verify/check.
- Phone numbersSearching, requesting and pointing numbers, and running old and new numbers side by side.
- Feature comparisonEvery product side by side, and where PacketExchange goes further.
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.





