Twilio Programmable Voice allows you to make voice calls directly from your application or script. In this tutorial, I’ll show you how to use it to make a voice call that plays a text-to-speech message from Bash or other shell scripting languages.
This tutorial is written for Unix shells such as Bash, Zsh, etc. If you are following the tutorial on a Microsoft Windows computer, it is recommended that you work inside the Windows Subsystem for Linux (WSL).
Set up your environment
In this section you are going to set up a brand new project. To keep things nicely organized, open a terminal or command prompt, find a suitable place and create a new directory where the project you are about to create will live:
mkdir phone-call cd phone-call
To be able to access the Twilio service, the shell script will need access to your Twilio account credentials, to log in and authenticate. The most secure way to define these credentials is to add them as environment variables.
The information that you need is the “Account SID” and the “Auth Token”. You can find both in the main dashboard of the Twilio Console, under “Account Info”:
In your terminal, define two environment variables called
TWILIO_AUTH_TOKEN and set them to your account credentials:
export TWILIO_ACCOUNT_SID=xxxxxxxxx export TWILIO_AUTH_TOKEN=xxxxxxxxx
If you want to learn more about environment variables, check out the How to Set Environment Variables tutorial.
Buy a Twilio phone number
To be able to make a phone call, you need to have a phone number associated with your Twilio account to call from. Log in to the Twilio Console, and select Phone Numbers. If you already have one or more numbers listed, you can use one of those. If you don’t have a number yet, click on the “Buy a number” button to buy a Twilio number. Note that if you are using a free account, you will be using your trial credit for this purchase.
In the “Buy a Number” page, select your country and check Voice under the capabilities field. If you’d like to request a number from your region, you can enter your area code in the Number field.
Click the “Search” button to see what numbers are available, and then click “Buy” for the number that you like from the results. After you confirm your purchase, click the “Close” button.
Create a TwiML Bin
TwiML is Twilio’s markup language, an extension to XML that is used to provide instructions to Twilio on how certain events need to be handled. When a call is made from the Twilio phone number you purchased above, you have to provide a URL that returns TwiML instructions, and Twilio will follow these instructions to handle the phone call.
You can host TwiML directly through Twilio, in a TwiML Bin. Navigate to the TwiML Bins section of the Console.
Click the “Create new TwiML Bin” button (or the “+” button) to create a new bin. This will direct you to a new page where you can configure your bin.
Give your bin any friendly name of your choosing, such as bash-call. Then copy and paste the following TwiML into the TwiML field, replacing anything there already:
<?xml version="1.0" encoding="UTF-8"?> <Response> <Say>Hello, from Bash!</Say> </Response>
Scroll down and click the “Create” button. The page will refresh and then at the top of the new page, you will see the “SID” and “URL” values assigned to your new TwiML bin. Copy the URL field to the clipboard.
Making a phone call from a shell script
Fire up your text editor or IDE and create a new file in the phone-call directory you created at the start of the tutorial. You can call it call.sh or any other name that you like.
Enter the following code in this file:
#!/bin/bash read -p "Press Enter to make a phone call" curl -X POST https://api.twilio.com/2010-04-01/Accounts/$TWILIO_ACCOUNT_SID/Calls.json \ --data-urlencode "Url=<TWIML-BIN-URL>" \ --data-urlencode "To=<YOUR-PHONE-NUMBER>" \ --data-urlencode "From=<YOUR-TWILIO-PHONE-NUMBER>" \ -u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN
Make sure you update the following parts of the above code snippet:
<TWIML-BIN-URL>with the URL you just copied from your TwiML bin
<YOUR-PHONE-NUMBER>with your personal phone number
<YOUR-TWILIO-PHONE-NUMBER>with the Twilio phone number you purchased earlier
For the two phone numbers, enter them in the E.164 format, which includes a plus sign, followed by country code, area code and local number.
Head back to your terminal, make sure you have defined the environment variables with your Twilio credentials as indicated above, and then run the script as follows:
The script will prompt you to press Enter to make a phone call. A few seconds after you press this key, your personal phone will ring. When you answer the call, you’ll hear “Hello, from Bash!”, which is the message entered inside the
<Say> element in the TwiML bin.
The phone call was triggered with a request sent to the Twilio API. The
curl command was used to make this request. This command should be pre-installed in your system, but in the odd case it isn’t, you can install it from here.
Now that you have made your first phone call, feel free to go back to your TwiML bin in the Console and edit the message you want the recipient to hear.
In this tutorial you’ve learned how to make a phone call from a shell script. But this is just the beginning. Be sure to check the TwiML reference to find out many more cool things you can add to your scripted phone calls. An interesting improvement you can attempt is to replace the
Url parameter, which provides a link to the TwiML Bin, with the
Twiml parameter, which accepts TwiML code directly. This would allow your script to dynamically generate the message that is played when the recipient picks up.
I can’t wait to see what you build!