Programmable Toll-Free Phone Numbers with Lower Cost Minutes

Time to read: 4 minutes

March 06, 2017
Written by
Billy Chia
Twilion

programmable-toll-free-numbers

When a business has two numbers listed, one local and one toll-free, which do you call?

Odds are you dial the toll-free number. They put people at ease because you know you won’t incur any long-distance charges. For international customers the ability to call toll-free is especially important. Even when phone plans include long-distance, people still like to dial the toll-free number. It provides a professional image and inspires credibility. And now, Twilio is making it even easier to use toll-free numbers by lowering the cost of voice minutes in the US and Canada. Read on to learn more, or jump ahead to get started with Twilio Programmable Toll-free numbers using the Console or via the phone numbers API.

Programmable Toll-free Numbers

Not all toll-free numbers are created equal. Twilio allows you programmatic control of your calls so you can use your toll-free number for outbound marketing campaigns and at the same time route return calls to your contact center or IVR. You can even send and receive SMS using your toll-free number. You can instantly search for and provision toll-free numbers in the US, Canada, UK, and Australia, with developer preview numbers available in Brazil, France, Germany, India, Ireland, Italy, Mexico, New Zealand, Spain, and Switzerland.

New lower pricing

We’re happy to announce price reductions for inbound and outbound toll-free calling. These changes are part of the ongoing efforts to optimize our underlying costs, and passing those savings to you. If you are using a Twilio toll-free number today then there’s nothing to change on your end. The lower prices will go into effect automatically on the dates specified below. You can also view detailed Programmable Voice pricing.

ProductNew List PriceEffective Date
Voice Calls you receive (inbound) on US & Canada Toll-Free Numbers

(20% reduction)

$0.0220/min03-07-17
Voice Calls made to US & Canada numbers using Toll-Free Numbers

(13.33% reduction)

$0.0130/min04-04-17

Get Started

You can buy and provision toll-free numbers via the Twilio Developer Console or programmatically using our phone number API. Follow along with the instructions below.

Provision Toll-free Numbers in the Console

Log in and visit the phone numbers page in the Console.

Phone numbers in the Console

Click on “Buy a phone number”

Buy a number

Click on “Show advanced search”

Advanced search

Select “toll-free” then click “search”

Toll-free checkbox

Finally, click “Buy” to purchase the toll-free number.

Choose your number

Provision Toll-free Numbers via API

Finding and purchasing phone numbers programmatically is easy with the Twilio REST API. I’ll be using the Twilio Node helper library (version 2.11.1). (Check out Phil’s post to see how to buy phone numbers in Ruby.)  Install the Twilio node library with npm.

$ npm install twilio

Let’s start by using the available phone number endpoint to search for a US toll-free number that includes the string “owl” (the digits “695” on a phone keypad). We’ll then log the formatted version of the numbers to the console. Save the following snippet as app.js.

const accountSid = process.env.TWILIO_ACCOUNT_SID;
const authToken = process.env.TWILIO_AUTH_TOKEN;
const client = require('twilio')(accountSid, authToken);

client.availablePhoneNumbers('US').tollFree.list({
    contains: "owl"
})
    .then((data) => {
        for (let number of data.availablePhoneNumbers) {
            console.log(number.friendlyName);
        }
    });

Notice that I’ve saved my Twilio credentials as environment variables which helps keep them safe and secure and keeps me from accidentally checking them into my source repository.

Then run the script to see the output.

$ node app.js 
(855) 996-9515
(855) 996-9550
(855) 269-5196
(855) 996-9523
(844) 669-5449
(844) 669-5085
...

Now lets update our app to use the incoming phone numbers endpoint which lets us purchase the first number that is returned from our search and configure its voice and messaging webhook URLs.

const accountSid = process.env.TWILIO_ACCOUNT_SID;
const authToken = process.env.TWILIO_AUTH_TOKEN;
const client = require('twilio')(accountSid, authToken);

client.availablePhoneNumbers('US').tollFree.list({
    contains: "owl"
})
    .then((data) => {
        const number = data.availablePhoneNumbers[0];
        return client.incomingPhoneNumbers.create({
            phoneNumber: number.phoneNumber,
            voiceUrl: 'http://demo.twilio.com/docs/voice.xml',
            smsUrl: 'http://demo.twilio.com/docs/sms.xml'
        });
    })
    .then((purchasedNumber) => {
        console.log("Your new phone number is", purchasedNumber.phoneNumber);
        console.log("sid:", purchasedNumber.sid);
        console.log("voiceUrl:", purchasedNumber.voiceUrl);
        console.log("smsUrl:", purchasedNumber.smsUrl);
    });

Finally, let’s verify the number has been provisioned by listing all the phone numbers in our account. (Alternatively you can log in to the console to manage your provisioned numbers.)

const accountSid = process.env.TWILIO_ACCOUNT_SID;
const authToken = process.env.TWILIO_AUTH_TOKEN;
const client = require('twilio')(accountSid, authToken);

client.availablePhoneNumbers('US').tollFree.list({
    contains: "owl"
})
    .then((data) => {
        const number = data.availablePhoneNumbers[0];
        return client.incomingPhoneNumbers.create({
            phoneNumber: number.phoneNumber,
            voiceUrl: 'http://demo.twilio.com/docs/voice.xml',
            smsUrl: 'http://demo.twilio.com/docs/sms.xml'
        });
    })
    .then((purchasedNumber) => {
        console.log("Your new phone number is", purchasedNumber.phoneNumber);
        console.log("sid:", purchasedNumber.sid);
        console.log("voiceUrl:", purchasedNumber.voiceUrl);
        console.log("smsUrl:", purchasedNumber.smsUrl);
            return client.incomingPhoneNumbers.list()
                .then( (data) => {
                    for (let number of data.incomingPhoneNumbers) {
                        console.log(number.phoneNumber, "is provisioned to your account.");
                    }
                });
    });

And the output should be similar to this:

$ node app.js
Your new phone number is +1855XXXXXXX
sid: PNxxx
voiceUrl: http://demo.twilio.com/docs/voice.xml
smsUrl: http://demo.twilio.com/docs/sms.xml
+1855XXXXXXX is provisioned to your account

How to use your new toll-free number

The ability to instantly provision toll-free numbers capable of both voice and sms opens up a host of use cases. Here are a few of the ways we’ve seen folks use Twilio Programmable Toll-free Numbers:

How are you thinking about using toll-free numbers? I’d love to hear about what you are building. Free free to leave a comment or reach out on Twitter.

Related Posts

Related Resources

A newspaper article

Twilio Docs

From APIs to SDKs to sample apps

API reference documentation, SDKs, helper libraries, quickstarts, and tutorials for your language and platform.
An Open book

Resource Center

The latest ebooks, industry reports, and webinars

Learn from customer engagement experts to improve your own communication.
User group reactions

Ahoy

Twilio's developer community hub

Best practices, code samples, and inspiration to build communications and digital engagement experiences.