Skip to content

Voice

Calls that speak, listen and report back.

Place an outbound call with one request. It can say a message, play your audio and collect the keys the person presses, then tell your app how it went.

$0.0021/min

Lowest live rate, Mexico

6

Languages a call can speak

$0

For a call nobody answers

Overview

An outbound call, scripted in the request

Voice places calls from your app to any phone. You decide what the call does when it is answered, in order: speak, play, gather digits, pause and hang up. The switch runs that script on its own and reports each step back.

At a glance

Place a call
POST /comms/calls
Follow it
GET /comms/calls/{id}
Modes
Wait for the outcome, or async with webhooks
Auth
Bearer API key, scope voice:send
Longest call
Up to 3,600 seconds, default 300
Throughput
10 call requests a second per key

Capabilities

What a call can do

A small, dependable set of steps, decided before the number is dialled.

  • Speak

    Up to 500 characters per step and 1,500 per call, in English, Spanish, French, German, Portuguese or Hindi. Speech is not charged extra.

    { "say": "…" }

  • Play your audio

    An MP3 from your HTTPS address, up to 2 MB. We fetch it once before the call, so a slow host can never stall a live call.

    { "play": "https://…/file.mp3" }

  • Collect keypad digits

    Ask a question by speech or audio and collect 1 to 20 digits, with a timeout, a finish key and up to three tries. The digits come back on the call record and by webhook.

    { "gather": { "say": "…", "digits": 1 } }

  • Async or blocking

    Wait for the outcome in one request, or pass async and get a call ID at once with a status URL, then follow it by webhook.

    async: true answers 202

  • Routing per call

    Smart Routing picks a route for the destination by cheapest, best_quality or balanced, or you pin a route you bought on the marketplace.

    strategy or routeId

  • Inbound on your numbers

    Numbers you hold answer with an IVR menu, business hours, voicemail with transcription, recording and forwarding to a phone or your SIP server.

    PUT /dids/{id}/features/ivr

  • Safe retries

    Send an X-Idempotency-Key and a retried request returns the first call instead of dialling twice.

    X-Idempotency-Key header

  • Test keys that never dial

    A test key runs validation, routing and pricing on the real path and simulates the call, so nothing rings and no real balance moves.

    px_test_sk_ keys

Script a call

Ask a question, collect the answer

The call below asks for one key press, thanks the person and hangs up. With async it returns at once and reports each step by webhook.

  • Actions run in order once the call is answered. hangup must be last; a call can carry up to 10 actions and 5 gathers.
  • The digits pressed arrive in the call.gathered webhook and on GET /comms/calls/{id}.
curl -X POST https://packetexchange.io/api/v1/comms/calls \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -d '{
    "to": "+447700900123",
    "from": "+14155550199",
    "async": true,
    "actions": [
      { "gather": { "say": "Press 1 to confirm your delivery.", "digits": 1 } },
      { "say": "Thank you. Goodbye." },
      { "hangup": true }
    ]
  }'

Response, 202 Accepted

{
  "callId": "…",
  "status": "ringing",
  "mode": "async",
  "actions": 3,
  "statusUrl": "/api/v1/comms/calls/…"
}

The simplest call

Or place a call and wait for its outcome

Leave out async and the request returns when the call ends, with the status, the billable seconds and the cost.

  • Allow a client timeout longer than maxDuration when you wait for the outcome.
# The request returns when the call ends, so allow longer than maxDuration.
curl -X POST https://packetexchange.io/api/v1/comms/calls \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  --max-time 120 \
  -d '{
    "to": "+14155550100",
    "from": "+14155550199",
    "strategy": "cheapest",
    "maxDuration": 60
  }'

Carrier routes

Every call on a route you can see

Each voice route on the marketplace lists its rate, billing increment and caller ID type. Pick by strategy per call, or buy a route and pin it.

Webhooks

Events, signed and retried

Subscribe once and follow every call from the first ring to the final second.

Each delivery carries X-PX-Signature, v1= followed by an HMAC SHA-256 of the timestamp and the raw body. Failed deliveries are retried with a growing back-off and can be resent.

  • call.ringingThe call was handed to the switch and is being dialled.
  • call.answeredThe person picked up and the script started.
  • call.gatheredDigits collected by a gather step, one event per gather.
  • call.completedThe call ended, with status, billable seconds and cost.
  • number.call.receivedA call arrived on a number you hold.
  • number.voicemail.receivedA caller left a voicemail on one of your numbers.

Pricing

Per second of a connected call

A call is billed for its billable seconds at the rate of the route that carried it, in that route's billing increment, plus a platform fee of 2% of the carrier cost that never exceeds $0.001 a call. Unanswered calls cost nothing.

Account and API keys
Free
Unanswered or failed call
Free
Speech and digit collection
No extra charge
Platform fee
2% of carrier cost, at most $0.001 a call
Top up
From $5 by card or crypto

Lowest live rates right now, per minute

  • India mobile$0.007878 /min
  • Nigeria mobile$0.0160 /min
  • Philippines mobile$0.0250 /min
  • Bangladesh mobile$0.011425 /min
  • Mexico$0.0021 /min
  • United Kingdom mobile$0.0260 /min
  • United States$0.0060 /min

Live rates are the cheapest listed route for an ordinary number in each destination, read from the marketplace as this page was served.

In production

Built for production

A call that carries its own script runs the same way every time, whatever happens on your side.

  • Nothing to hostThe script travels with the request, so a call speaks, gathers and ends cleanly even while your servers are deploying.
  • The outcome in one replyWait for the call to end and get the status, duration and exact cost in one response, or pass async and follow it by webhook.
  • Speech at no extra costsay steps are rendered before dialling in six languages and are not charged on top of the route.
  • Caller ID you can checkEvery route states its caller ID type, and a caller ID test shows what a real handset in the destination displays.
  • Unanswered calls are freeYou pay for answered time only, rounded to the route billing increment, with a platform fee that never exceeds $0.001 a call.
  • A sandbox on the real pathTest keys validate the request and the actions and simulate the call against sandbox credit, so nothing rings.

Moving over

Your call flows map across, verb by verb.

Coming from Twilio

The names you know, mapped

TwiML becomes a short list of actions that travels with the call. The move-over guide maps every verb.

TwilioCalls resource, POST .../Calls.jsonHerePOST /comms/callsJSON body with to, from and actions.
TwilioTwiML <Say>, <Play>, <Gather>, <Pause>, <Hangup>Heresay, play, gather, pause, hangup actionsSent in the request rather than fetched from your URL when the call answers.
TwilioUrl / TwiML fetched on answerHereThe script sent with the callNo markup server to host. Digits pressed arrive on call.gathered for your app to act on.
TwilioStatusCallback with StatusCallbackEventHerecall.ringing, call.answered, call.gathered, call.completedWebhook endpoints subscribed on the account, signed.
TwilioCall SIDHerecallIdGET /comms/calls/{id} while the call runs and after it ends.

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

Questions

Voice, answered

How is a call billed?
Billable seconds at the route rate, in the route's billing increment, plus a platform fee of 2% of the carrier cost, never more than $0.001 a call. Unanswered calls and calls that fail cost nothing, and speech is not charged extra.
What happens with the key someone presses?
The digits come back on the call.gathered webhook and on the call record, and your app can act on them at once: place a follow-up call or send a message based on them.
Which languages can a call speak?
English, Spanish, French, German, Portuguese and Hindi. Set a default language on the call or a language on each say step.
What caller ID will people see?
The number you pass in from, on routes that carry it. Each route states its caller ID type before you use it, and you can test what a handset displays with a caller ID test.
Can I take inbound calls?
Yes, on numbers you hold. Each number can forward to a phone or your SIP server, play an IVR menu, follow business hours, take voicemail with transcription and record calls.
Can I test without dialling?
Yes. A test key runs the full request path and simulates the call against sandbox credit, so nothing rings.

Place your first call today

Free account, an API key on sign-up and carrier rates from the first second. No contract and no monthly fee.

Prefer to talk it through? Contact the team.