Create a Simple Notification System using Twilio CLI, Programmable Voice, and Programmable Messaging

March 18, 2020
Written by
Twilion
Twilion
Twilion

Messaging Contacts Notifications

If you find yourself needing to broadcast urgent news to your customers or employees, but do not have a notification system in place, this tutorial is for you. In this blog post we'll show you how to create a bash script to quickly send SMS messages or Voice message notifications to several recipients in a CSV.

Prerequisites

To get started with the project you will need the following:

Setting up the Twilio CLI

If you haven’t already done so, go to twilio.com and sign up for a free account or log in to your existing account. Take note of your Account SID and Auth Token as you will need them to login via the CLI in the following steps.

Twilio CLI is a command line interface tool that allows you to manage your Twilio resources directly from your terminal or command prompt. This will be helpful to prevent us from switching between the browser and our terminal since we’ll be using the command prompt to develop our application. Install Twilio CLI for your respective operating system by following this guide.

Once Twilio CLI is installed, login into your account by running this command in your terminal:

$ twilio login

You will be prompted to enter a local ID for the credentials known as the Shorthand identifier, followed by your Account SID and Auth Token. Use “TwilioAccount” as seen in the screenshot below if you don’t know what to specify for the identifier.

Twilio CLI login

Reminder, you can find your Account SID and Auth Token on your Console:

Twilio Account SID and Auth Token

Next, install CLI autocomplete to add support for bash completion:

$ twilio autocomplete bash

Let’s test out the CLI by listing phone numbers available for purchase by area code. Be sure to replace the --area-code with the value of your desired region.

$ twilio api:core:available-phone-numbers:local:list \
  --area-code="222" --country-code US

List of available phone numbers for purchase

Now purchase an available phone number by replacing the --phone-number attribute with a number from the previous command:

$ twilio api:core:incoming-phone-numbers:create \
  --phone-number="+ 12223334444"

Newly purchased Twilio phone number in the CLI

Now that you have tested listing and purchasing a phone number via the CLI, review your phone numbers with a filter for the area code:

$ twilio api:core:incoming-phone-numbers:list --phone-number="+1222"

Note: There are 3 types of numbers (Short Code, Long Code and Toll-Free), each with different characteristics. Please check this document to better understand the differences between Short Code and Toll-Free. This blog post on SMS performance also outlines the differences and best practices for sending SMS via the various phone number types.

In this blog post we will use a Long Code for a simple application with no more than 200 recipients, and no more than 1 message per second. If you are planning on sending more than 7,200 messages a day, please contact Twilio.

For higher throughput and scale, consider a Short Code (message only) or a High Throughput Toll Free number instead.

Test if the CLI is working properly by sending a simple message to your mobile device:

$ twilio api:core:messages:create \
  --from "+12223334444" \   --to "+15556667777" \
  --body "Hello from Twilio!"

NOTE: The --from attribute is the Twilio number you purchased and the --toattribute is your test mobile number.

Create your employee or customer list

As mentioned before, a list of recipients will need to be created in a simple spreadsheet (.csv file), containing the information you will use to send notifications. For each use case (SMS vs Voice) the fields will vary. We will show you a simple example where we want to send SMS and Voice greetings to our customers by name, and inform them of the store hours on a certain date. We are assuming that customers OPTed IN to receive such notifications. These examples could also be easily modified to send information to employees being notified of an office closure or any news that is important and requires immediate response.

In this example, create a small notification.csv file with the following columns and save it to your computer:

Sample CSV with employee or customer information

If you prefer to use Vi or any CLI editor, it should look like this:

Channel,Date,HoursStart,HoursStop,From,Name,To
voice,3/17/20,8:00,17:00,12223334444,Twilio Voice,15556667777
sms,3/18/20,8:00,17:00,12223334444,Twilio SMS,18889990000

NOTE: Be sure to replace the From and To columns with the correct numbers.

Create a simple bash script to send the notifications

We will now create a bash script (or plain text file with a series of commands) to parse our CSV and contact the recipients accordingly. If you are new to programming, please check this guide to learn more about bash scripts.

In your terminal, create a new file named CliNotifications.sh:

$ touch CliNotifications.sh

Test the script

Make sure you saved both files in the same directory.

Execute your script by running ./CliNotifications.sh and check the results.

Twilio CLI bash script output

You should have received a SMS message on your first number and a Voice message on your second as shown in the screenshot below.

iOS SMS screenshot

In case it does not work, follow these steps to troubleshoot:

  • If you get a bash: ./CliNotifications.sh: Permission denied - issue the following command to change the permissions chmod 755 CliNotifications.sh
  • Check the Debugger for error messages
  • Check the Calls Log for error messages (Active Numbers => Calls Log tab)

Twilio call log from the console

Look on the call Details and Insights Summary tabs:

Twilio Call Details and Summary
  • Check the Messages Log for error messages (Active Numbers => Message Log tab)

Twilio Messages Log

Enhance with your actual numbers

If all worked well, you can add all the real customers or employees information to your list. You can also modify the messages by removing or commenting out the following in your code:

       # echo "Date : $date"
       # echo "HoursStart : $hoursStart"
       # echo "HoursStop : $hoursStop"
       # echo "From : $from"
       # echo "Name : $name"
       # echo "To : $to"
       # echo "Channel : $channel"
 

Conclusion: Automating Notifications Using Twilio

In this blog, you have learned how to use Twilio CLI and a Bash script to automate sending notifications to customers or employees.

Note: It is important to observe the proper security and HIPAA compliance measures when using Twilio Programmable Messaging and Voice to contact patients about their individual health status/symptoms. Contact Twilio if you have any questions.

If your organization would like more guidance on how to build solutions or would like to partner together on your work addressing the outbreak, we’re here to help. Reach out to coronavirus@twilio.com.

Possible improvements

Here are a few suggestions on how to extend what we have just built:

  • Add email as a channel option. Configure a SendGrid account and use the SendGrid API or Twilio CLI to send emails as well.
export SENDGRID_API_KEY=SG.xyz.abc

twilio api:core:messages:list \
  -o tsv \
  | twilio email:send \
  --to 'test@example.com'\
  --from 'sender@example.com'\
  --subject='Message log'\
  --text 'Message log'
  • Send notifications using Twilio APIs instead.
  • Improve the script to load 2 files, one for static fields (date, hoursStart, hoursStop, from) and another for the ones that vary per customer or employee (name, to).

Al Kiramoto is a Solutions Engineer at Twilio. He lives in Dallas, TX and enjoys working with customers solving business problems - besides a good barbecue and TexMex food. He can be reached at akiramoto [at] twilio.com

Additional resources

The following reference resources will provide you with in-depth information on some of the topics mentioned in this post: