Skip to content

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 verbs and call actions
TwiML<Say>Call action{ "say": "..." }SameUp 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" }SameA 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, finishOnKeyCall action{ "gather": { digits, timeout, finishOnKey, tries } }Our waySame 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 }SameSeconds of silence.
TwiML<Hangup>Call action{ "hangup": true }SameMust be the last action. The call also ends when the steps run out.
TwiML<Reject>Call actionNumber settingsGoes furtherInbound handling, including opening hours and what happens out of hours, is set on the number with no code.
Fields

What maps one to one

Call request fields
On TwilioToOn PacketExchangetoSameE.164.
On TwilioFromOn PacketExchangefromSameThe caller ID, E.164.
On TwilioUrl or TwimlOn PacketExchangeactionsOur wayUp to 10 steps, chosen from say, play (an HTTPS MP3), gather, pause and hangup.
On TwilioTimeLimitOn PacketExchangemaxDurationSame10 to 3,600 seconds, 300 by default.
On TwilioStatusCallback and StatusCallbackEventOn PacketExchangeAccount webhook (call.ringing, call.answered, call.gathered, call.completed)Our waySubscribe once; every call reports to it.
On TwilioReturns queued, outcome by callbackOn PacketExchangeasyncGoes furtherWithout 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

Call status values
On TwilioqueuedOn PacketExchangequeuedSameAccepted, not yet dialled.
On TwilioringingOn PacketExchangeringingSameBeing dialled.
On Twilioin-progressOn PacketExchangeansweredSamePicked up.
On TwiliocompletedOn PacketExchangecompletedSameAnswered and ended.
On Twiliono-answer, busy, failedOn PacketExchangeno_answer, busy, failedSameUnderscores instead of hyphens. Unanswered calls cost nothing.

Endpoints

Voice endpoints
On TwilioPOST .../Calls.jsonOn PacketExchangePOST /comms/callsSameWaits for the call to end by default; send "async": true to get the id back at once.
On TwilioGET .../Calls/{CallSid}.jsonOn PacketExchangeGET /comms/calls/{id}SameStatus, timestamps, duration, cost, hangup cause and any keys pressed.
On TwilioGET .../Calls.jsonOn PacketExchangeGET /comms/callsSamePaged 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

  1. Step 1

    Create a voice key

    A live key limited to voice:send, and a test key.
  2. 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.
  3. 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.
  4. 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.
  5. Step 5

    Map the statuses

    in-progress becomes answered, and the final states use underscores (completed, no_answer, busy, failed).
  6. 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

Call webhook 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.
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

  1. 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.
  2. 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.
  3. 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.

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.