Standalone script or Nagios/Icinga plugin for alerting using Twilio (
Switch branches/tags
Nothing to show
Clone or download
bfg Merge pull request #3 from tbaschak/apt-readme
Update with Debian/Ubuntu apt commands to pull in requirements
Latest commit 66d6bb3 Nov 24, 2015
Type Name Latest commit message Commit time
Failed to load latest commit information.
bin Added support for messages longer than 160 characters. Dec 3, 2014 Update with Debian/Ubuntu apt commands to pull in requirements Nov 24, 2015


twilio-sms is Perl command line script which is able to send SMS messages using Twilio SMS service.

Even though this script can be used for any kind of SMS messaging needs, it's primary use is Nagios/Icinga alerting.


Perl interpreter and the following modules:

These dependencies can be pulled in automatically on Debian/Ubuntu by running:

  • apt-get -y install libjson-perl libemail-mime-encodings-perl liburi-escape-xs-perl libwww-perl


  • install this package and put the script in $PATH
  • Create default configuration file
twilio-sms --default-config > ~/.twilio-sms.conf
  • Edit configuration file to suit your twilio account settings
from          = "<your twilio telephone number>"
user_id       = "<your twilio user_id>"
auth_token    = "<your twilio auth token>"
timeout       = 5
verbose       = 0
split_big_msg = 0   # set to 1 if you want to send sms messages larger than 1600 chars
rewrite       = 0

twilio-sms searches for configuration files in the following filesystem locations:


The script always tries to read all configuration files listed above, variable values are inherited from previously loaded configuration files if they are omitted from configuration file currently being loaded. The name of the configuration file changes dynamically with the name of the executable. If you rename the executable, you also have to rename the configuration file. To see the real paths searched, call the executable with --help and look for the -c parameter description.

  • Try to send a message :)
echo "Hello World" | twilio-sms -- +1987654321 +1987654322

Nagios/Icinga setup

  • add the following new commands to your Nagios/Icinga configuration:
define command {
    command_name    notify-service-by-twilio
    command_line    /usr/bin/printf "%b" "Service: $SERVICEDESC$\nHost: $HOSTALIAS$\nState: $SERVICESTATE$\n\n$SERVICEOUTPUT$" | /etc/icinga/plugins/twilio-sms -- $CONTACTPAGER$

define command {
    command_name    notify-host-by-twilio
    command_line    /usr/bin/printf "%b" "Host: $HOSTNAME$\nState: $HOSTSTATE$\n\n$HOSTOUTPUT$" | /etc/icinga/plugins/twilio-sms -- $CONTACTPAGER$
  • define new template and update contacts
# contact template
define contact {
    contact_name                    twilio-template
    name                            twilio-template
    alias                           Twilio contact template
    service_notification_period     24x7
    host_notification_period        24x7
    service_notification_options    w,u,c,r
    host_notification_options       d,r
    service_notification_commands   notify-service-by-twilio
    host_notification_commands      notify-host-by-twilio

    register                        0
# REAL contacts, based on twilio-template
define contact {
    use                             twilio-template
    contact_name                    joe_average
    pager                           +1234567890

# you probably want to use contact groups in your
# host/service definitions
define contactgroup {
    contactgroup_name       poor_bastards_on_call
    members                 joe_average
  • update service definitions to use new contactgroups
define service {
  name                            some_service
  # other boring stuff
  contact_groups                  poor_bastards_on_call
  • set up cron job for deferred message processing
# Try to re-send messages using Twilio that were not sent
# at the time of script invocation.
# There are many reasons for messages not being delivered
# on first attempt: internet connection unavailable, twilio
# api outage, etc...

*/15 * * * *	nagios /path/to/twilio-sms -P >/dev/null 2>&1


Usage: twilio-sms [OPTIONS] [-- <recipient> [<recipient> ...]]

This script is simple command line interface to
Twilio ( SMS service.

Input message length is not important since it is split into
multiple SMS messages if it's length exeedes limit of 1600

      --default-config     Prints out default configuration file
  -c  --config=FILE        Read configuration from specified
                           file. NOTE Script tries to read
                           the following files on startup:


  -m  --msg=MSG            Message text
  -M  --msg-file=FILE      Read message text from specified file
                           NOTE: message is read from stdin if -m/-M
                           parameters are omitted.

      --rewrite            Rewrite variables in message with environmental
                           variable values (shell style)

  -R  --recipients=FILE    Read specified file containing recipient numbers
                           (one phone number per line, # comments supported)

  -f  --from=NUM           Sender number (Default: +19493834522)

  -P  --process            Process deferred messages
  -t  --timeout=SECS       HTTP request timeout in seconds (Default: 10)

  -r  --report             Report response statuses
  -v  --verbose            Verbose execution
  -D  --debug              Enable script debugging.
  -V  --version            Prints script version
  -h  --help               This help message


  # send file contents over SMS
  cat /path/to/file | twilio-sms -- +1987654321 +145678923
  twilio-sms -M /path/to/file -- +1987654321 +145678923

  # send simple string
  twilio-sms -m 'Hello world from $USER'  -- +1987654321
  twilio-sms -m 'Hello world from $USER' --rewrite  -- +1987654321
  twilio-sms -m 'Hello world from \$USER' --rewrite  -- +1987654321

  echo 'Hello world from $USER' | twilio-sms  -- +1987654321
  echo 'Hello world from $USER' | twilio-sms --rewrite  -- +1987654321
  echo 'Hello world from \$USER' | twilio-sms --rewrite  -- +1987654321

  # send fortune of the day
  fortune | twilio-sms -- +1987654321

  # process deferred messages (usually from cron)
  twilio-sms -P


The BSD 3-Clause License