How to Use csh or tcsh to Make a Phone Call from a New Twilio Number

How to Use csh or tcsh to Make a Phone Call from a New Twilio Number

Emacs or vi?  Today we'll avoid the whole debate and make phone calls with Twilio directly from csh (or, more likely, tcsh).  Without saying goodbye to the C Shell we'll walk through finding an available number, purchasing a number, and making a phone call with the Twilio API and built-in *NIX commands.

Set Your Twilio Credentials in your C Shell

Click to the Twilio console to get started.  Log-in to your existing account or sign up for a free account (be sure to verify your number, you'll need it later).  When that is done, look for the Account Summary as seen below:

Using that information, substitute the account_sid and auth_token variables below with the 'ACCOUNT SID' and 'AUTH TOKEN' variables from the Twilio Console.  (Click on the eyeball icon to expose your AUTH TOKEN).

Run these in your shell:

set account_sid="ACXXXXXXXXXXXXXXXXXXXXX"
set auth_token="your_auth_token"

Find a Twilio Number with cURL in the C Shell

Now that our Account SID and auth token are configured, we can query Twilio's REST API to find available phone numbers.  We will need to find one (and purchase it) to make a phone call from our script.

set 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

If you paste that above command and hit return, available_number will be set to the first number Twilio returns.

Let's explore what's happening in this busy line:

1. set available_number= is the syntax for setting a local variable.  Everything contained in the backtick ( ` ) will be executed and set to available_number.
2. curl -X GET "https://api.twilio.com/[omitted] -u "${account_sid}:${auth_token}" We use the software package cURL and the HTTP verb GET to ask Twilio's available numbers endpoint for a free number.  '-u' is the flag to provide account credentials by HTTP Basic Auth. A ${variable_name} inside of double quotes substitutes the variable names we set earlier into this command.
3. "|" A pipe character in the shell means the results of the previous command are passed to the next command (in this case, we pass Twilio's response to sed).
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. && allows us to chain our commands together in the shell.
6. echo $available_number prints the variable available_number to 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, it will cost money to purchase this number.  Check out our pricing page for more details.

Purchase a Twilio Phone Number in the C Shell

Twilio just returned an available number to us - let's put a ring on it.

Run the following to purchase the number and add it to your account:

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

Hit return and you should be the happy owner of a new Twilio phone number (if you aren't, it's possible the number was already purchased by someone else - re-run the 'available number' step and try again).  

If you're eagle-eyed, you'll probably notice:

• 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

If everything went okay you now own available_number and are ready for the big payoff.

Make a Phone Call with Twilio in Your C Shell

TwiML, Twilio's Markup Language, is a language you write to instruct Twilio on how to handle phone calls.

TwiML has many features (see our TwiML documentation) you should explore once you are done with the command line.  Also, note that Twilio can also host your custom TwiML in TwiML bins, saving you from having to set up hosting to explore.

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

Change the your_number variable below to a verified Twilio number in your account and run the following line:

set your_number="+15555555555"
curl -X POST \
    --data-urlencode "Url=https://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) which will be followed by some relaxing music.  We knew the game, and we played it.

Twilio: Ringing Phones Without Deserting the C Shell

Whether for prototyping or for adding features to your production scripts, exercising the Twilio API from the command line is a useful skill.  With this guide, you should now know how to find, purchase, and utilize a new Twilio number all from csh or tcsh.  We know you'll never let us down - message us @twilio on Twitter with what you build!

Further study: 

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