22nd April 2012

Ruby ASPSMS

Ruby ASPSMS is a Ruby script which is both a command line SMS client in the style of mail and a ruby library. The command line client provides a convenient way to send SMS through the ASPSMS.com SMS gateways from the command line, either manually from your shell, or from automated, scripted tasks such as cron jobs. Since it is also a ruby library, it can be used directly from within ruby web applications without having to run external commands. Ruby ASPSMS is packaged as a ruby gem (gem install aspsms).

ASPSMS.com is a Switzerland-based SMS gateway featuring an XML interface, at rather low prices, and neither setup nor monthly fees, ideal for low to medium volume usage. Note that I am in no way affiliated with ASPSMS.com / Vadian.net, just a happy customer.

Synopsis

Usage:
  aspsms [-M] [-v] [-c file] [-o orig] [-t [n]] [-f] [-b] rcpt [...]
  aspsms  -C  [-v] [-c file]
  aspsms  -O  [-v] [-c file] [-o orig]
  aspsms  -U  [-v] [-c file] [-o orig] [-u code]
Actions:
  -M    send text message read from stdin (implied if recipients are given)
  -C    retrieve credit balance
  -O    check originator authorization
  -U    send originator unlock code; unlock if used with -u
Parameters:
  -o    specify originator (phone number or up to 11 characters)
  -t    truncate message to n bytes, or 160 if used without argument
  -f/-b flashing/blinking text SMS
  -u    specify unlock code
  -c    specify config file (default: ~/.aspsms, [/usr/local]/etc/aspsms)
  -v    verbose
  -h/-V show help/version and exit
Recipient phone number format: international format, e.g. +41XXXXXXXXX

Supported are the following actions:

  • Send text messages, with arbitrary originator, multiple recipients, arbitrary message length, optional truncating, flashing, blinking.
  • Retrieve the credit balance.
  • Check originator authorization.
  • Unlock a new originator.

The underlying ruby library also supports a few additional, advanced features such as delivery notifications. Read the source for more information.

The command line interface was designed to be scriptable and cronjob friendly. The exit status can be relied upon, errors are printed to standard error and unless verbose mode is used, no or only minimal output is written to standard output, ready to be used within backticks in scripts (e.g. credits=$(aspsms -C) or aspsms -A -o "$originator" || exit 1).

Examples

Sending SMS and check for for success:

$ echo 'Hello world!' | aspsms +41791234567
$ echo $?
0

Sending SMS in verbose mode (-v) to multiple recipients:

$ echo 'Hello world!' | aspsms -v +41791234567 +41797654321
message delivered (2 credits used)

Sending flashing SMS (-f) with custom originator (-o):

$ echo 'Hello world!' | aspsms -f -o 'sms.roe.ch' +41791234567

Retrieve credit balance from server:

$ aspsms -C
338.5

Check originator authorization and unlock new originator:

$ aspsms -O -v -o +41790000000
not authorized
$ aspsms -U -v -o +41790000000
sent unlock code
$ aspsms -U -v -o +41790000000 -u <unlock code received by mobile>
unlocked originator
$ aspsms -O -v -o +41790000000
authorized

Installation

gem install aspsms

Configuration

The script reads the configuration file from ~/.aspsms, /usr/local/etc/aspsms or /etc/aspsms. Make sure to set sensible permissions (0600 is a good start).

# ASPSMS configuration file
userkey [USERKEY]
password [PASSWORD]
#originator [DEFAULT ORIGINATOR]
#gateway [GATEWAY OVERRIDE]

Userkey and password deliberately cannot be specified on the command line, as the parameters could then be seen by all users on a shared system (eg. using ps auxw).

HTTP proxy settings are read from the environment variable http_proxy and character set of strings passed as command line arguments or read from stdin is expected to be in the charset defined by the locale as defined by the environment (LC_ALL||LC_CTYPE||LANG).

Development

Please send patches my way or fork the project on GitHub and send me a pull request.

To Do List

  • Rewrite error handling to use custom exception classes in the ASPSMS:: namespace
  • Support (non-)delivery notifications from the command line and ASPSMS::Easy API
  • Support for reading password from a file descriptor or from a keychain
  • Write manual page and improve rdoc

History

The latest version is available as a ruby gem (see Installation).

An older version of the script, before moving to GitHub and RubyGems is still available: aspsms.rb r95

The ruby script is a rewrite of a previous, more limited aspsms.pl perl script.

Fork me on GitHub

18fd1ed9