Programmable Voice

Any device connected by a Twilio SIM can make and receive Programmable Voice calls. This requires the device itself to support PSTN voice calling and the SIM's Rate Plan to have voice_enabled set to true.

Calls to or from a device are programmatically controlled using TwiML.

Mobile-originated calls: when a device attempts to make a call, your software will be asked for TwiML to control the behavior of the call. See "Calls from the Device".

Mobile-terminated calls: any call that arrives to Twilio via an Incoming Phone Number, a SIP Interface, or any other valid ingress channel can be routed to a device. See "Calls to the Device".

Calls from the Device

Every time a device attempts to place an outbound call, your server can control the call using TwiML.

The first step is to set a "Voice Request URL" on the SIM's detail page in the Console. The URL should point to your TwiML, which could be a dynamic application server, a simple static XML file, or a hosted TwiML Bin.

Voice Request URL

Twilio's Request

The HTTP request that retrieves TwiML from your server will conform to the standard TwiML Request schema.

Unlike other TwiML requests, you will see a Twilio SIM Sid in the 'From' parameter:

From=sim:DE467fb57a0cba9641a8208136d42545f8

The To parameter contains the phone number that the device is attempting to dial:

To=+14154898625

In the above example the device, or the person operating the device, is attempting to dial +14154898625 using the device's standard dialer.

Your Response

Your server must respond using valid TwiML. All standard TwiML verbs and nouns can be used.

In many cases you'll want to connect the device to another party using Dial. In the example below, <Dial> is used to connect the call to the device's intended destination. This requires your server to substitute {{To}} with the value of the To HTTP request parameter:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Dial callerId="+15558675309">
        <Number>{{To}}</Number>
    </Dial>
</Response>

With the full power of TwiML at your disposal, there's no reason that you need to route the call exactly as the device has intended.

Using the TwiML below, any time the device attempts to dial any phone number, the caller will hear an infinitely repeating cowbell.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Play loop="0">https://api.twilio.com/cowbell.mp3</Play>
</Response>

Caller ID

When connecting a Wireless call from a device to an external party using <Dial>, a caller ID must be provided, e.g.: <Dial callerId="+15558675309">. The caller ID can be any Twilio Incoming Phone Number or Outgoing Caller ID.

TwiML Bin

A quick and simple way to host TwiML is to use TwiML Bin. The example below uses a TwiML Bin to route all calls as intended by the device:

Wireless Voice TwiML Bin

Calls to the Device

Calls from the PSTN to an IncomingPhoneNumber, from a SIP Interface or created by a Twilio Client can be routed to a device using the <Dial> verb and <Sim> noun containing the SIM Sid.

The simplest example of dialing a SIM-connected device is shown:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Dial>
        <Sim>DE567fb57a0aca9641a8209136d42545f4</Sim>
    </Dial>
</Response>

Any optional attributes of <Dial> can be used. The example below records the call to the device. It attempts to call the device for 15 seconds before handing off TwiML processing to the action URL:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Dial record="record-from-ringing" timeout="15" action="/sim-call-completed">
        <Sim>DE567fb57a0aca9641a8209136d42545f4</Sim>
    </Dial>
</Response>

Logs and Billing

Logs

Logs for Wireless calls are found in the global voice logs section of the Console.

Billing

Most call flows that involve a SIM will include two independent call legs: one call between Twilio and the non-SIM party, and the other between Twilio and the SIM-connected device. The call leg from Twilio to the non-SIM party (PSTN, SIP, Client, etc) is billed at standard Twilio voice rates depending on the connectivity method being used. The other call leg (between Twilio and the SIM) is billed at Programmable Wireless voice rates.

Known Limitations

Non-programmable Calls to the Device

There is a phone number on the SIM known as the MSISDN that is not used by Programmable Voice and that can change if the underlying mobile network operator changes. The presence of the MSISDN means that some (potentially unwanted) calls may arrive straight to your SIM without routing via Twilio. In these cases, Twilio cannot yet offer programmatic control over the calls, and you won't see them in your Twilio call logs. However, 100% of calls from the SIM are programmatically routed by Twilio.

US-only

Programmable Voice is currently only offered when connected in the USA. This is expected to change during the beta.

Trial Accounts

Currently, Wireless Programmable Voice requires an upgraded Twilio account.

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.