How to Use bash or zsh to Make a Phone Call from a New Twilio Number

How to Use bash or zsh to Make a Phone Call from a New Twilio Number

Close that text editor!  We're going to make phone calls with Twilio directly from bash or zsh.  Without ever deserting the command line we'll walk through finding an available number, purchasing it, and making phone calls all using common builtin *NIX commands.

Let's begin!

Set Your Twilio Credentials in bash or zsh

Start by clicking over to the Twilio console.  Either log in or sign up for a free account (be sure to verify your number), and look for the Account Summary as seen below:

You'll want to replace the 'account_sid' and 'auth_token' variables below with the 'ACCOUNT SID' and 'AUTH TOKEN' variables from your Twilio Console.  Click the eyeball icon to expose your auth token and then copy/paste it into the shell.

account_sid="ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
auth_token="your_auth_token"

Find a Twilio number with cURL in bash and zsh

Before we can make a phone call with Twilio we need to get a Twilio phone number. Now that our API credentials are set we can query the AvailablePhoneNumbers resource to find a new phone number for our account.

available_number=`curl -X GET \
    "https://api.twilio.com/2010-04-01/Accounts/${account_sid}/AvailablePhoneNumbers/US/Local"  \
    -u "${account_sid}:${auth_token}" | \
    sed -n "/PhoneNumber/{s/.*<PhoneNumber>//;s/<\/PhoneNumber.*//;p;}"` \
    && echo $available_number 

Running that command will set the variable available_number to the first available number Twilio returns.  

We're doing a few things in this line - let's unpack them here:

1. available_number= is the syntax in bash or zsh for setting a local variable.  The backtick ( ` ) characters contain the expression our shell should evaluate to get the value for our variable.
2. curl -X GET "https://api.twilio.com/[omitted] -u "${account_sid}:${auth_token}" Uses the software package cURL and the HTTP verb GET to ask Twilio's available numbers endpoint for an available number.  '-u' signifies that we will provide account credentials using HTTP Basic Auth. The ${variable_name} syntax inside of double quotes substitutes the variable names we set earlier into the command.
3. "|" A pipe character in the shell means the results of the previous command are passed to the next.
4. sed -n "/PhoneNumber/{s/.*<PhoneNumber>//;s/<\/PhoneNumber.*//;p;}" Uses the stream manipulating package sed to extract just the first occurrence of the <PhoneNumber> tags from Twilio's XML response
5. && the double ampersands mean that the following command will be run immediately after the others finish
6. echo $available_number is a sanity check that we received an output, printing the variable's contents in the shell.

(For advanced users: note that the 'US' after AvailablePhoneNumbers in the URI is the ISO Country Code.)

Note: If you're not in a trial account, you are about to spend money to buy a number.  Check out our pricing page for more details.

Purchase a Twilio Phone Number in bash or zsh

Now that we've found a Twilio phone number that's available for purchase, we need to put a ring on it. The following command will purchase the phone number we just found and add it to our account.

curl -X POST -F "PhoneNumber=${available_number}" \
    "https://api.twilio.com/2010-04-01/Accounts/${account_sid}/IncomingPhoneNumbers" \
    -u "${account_sid}:${auth_token}"

After executing the above you'll be the happy owner of a new Twilio-provided phone number (if you aren't, the number may have just been purchased by someone else - you can re-run the 'available number' step and try again).  Note a few changes here when we use cURL with the IncomingNumber endpoint:

• We're now using the HTTP method POST
• We're POSTing the PhoneNumber parameter to the IncomingPhoneNumbers endpoint, and substituting the phone number we found in the last step

Assuming everything completed successfully and you now own the $available_number, we're almost ready for the big payoff.

Make a Phone Call with Twilio in bash or zsh

When Twilio makes or receives a phone call, it asks your application for instructions on how to handle the call. You write those instructions using TwiML, Twilio's Markup Language.

TwiML has many features (see our TwiML documentation) for you to explore once we are done on the command line.  Note that Twilio can also host your TwiML in TwiML bins, which will save you from having to set up hosting for your explorations.

For this guide, we'll use some sample TwiML which you can find here.

When you're ready to proceed, please edit the your_number variable below and run the following command:

your_number="+15555555555"
curl -X POST \
    --data-urlencode "Url=http://demo.twilio.com/docs/voice.xml" \
    --data-urlencode "To=${your_number}" \
    --data-urlencode "From=${available_number}" \
    "https://api.twilio.com/2010-04-01/Accounts/${account_sid}/Calls" \
    -u "${account_sid}:${auth_token}"

If all went well, you should hear a message from our Alice voice (see more <Say> options) followed by a classic mp3.  I hope we didn't let you down.

At Twilio, We're No Strangers to Bash

Using the Twilio API to make phone calls without leaving your shell should make your prototyping and scripting easier.  You can now automate finding, buying, and making a phone call with Twilio without leaving bash or zsh.

See also: 

• Twilio API Reference
• How To Make REST API Requests in PowerShell