Previous Page

Table of Contents [ Show]

Copyright and Licensing

You are generally free to use any of the source code that I have written and linked to here as you see fit. Anything on CPAN is licensed using the standard Perl license and anything on GitHub is licensed under GPLv2, because it doesn't have a simple listing for Perl in the drop-down list. I appreciate being informed of anything cool that you might do with this, but don't require it.


Now that the links are out of the way, you might be wondering what this post is actually about. VoIP.ms is a great Canadian VoIP phone service provider. I have an older post, badly in need of updating, discussing what VoIP phone service is and the advantages it provides over a typical land or cellphone line. VoIP.ms as a vendor stands out from the crowd with an incredible API which can be used to write programs to control many aspects of your account.

The primary documentation for the API is written for PHP, a language I try to avoid (not very successfully, since you are currently reading the product of a thousand or more lines of it), and .net, a language which, until recently, wasn't even compatible with my beloved Linux environment. My favourite scripting/high-level programming language is Perl, so I wrote the code linked throughout this article to add a layer of abstraction to the API for Perl and then created several programs utilizing that.


I am in no way affiliated with VoIP.ms. I do not claim ownership of the VoIP.ms logo here or in the article thumbnail. The thoughts expressed here are my own.


The primary function of VoIP.ms is obviously for VoIP telephone calls, however there isn't actually a lot of interaction necessary for the average person which would require API access for the phone features. While this is also true if you have limited need for a normal SMS application, there is also a lot of fun that can be had with an SMS API.

Fetch SMS Messages

I've written a reasonably powerful script for fetching SMS messages. The script works with a simple JSON config file and each configuration value can be overridden at the commandline. The API returns all inbound and outbound messages for the current day (by default; I'll be adding 'to' and 'from' options soon), and so the script also allows you to restrict by direction and message ID.

The script has a couple of possible output methods, including passing each individual message as a JSON string to a command specified for that direction, or it can print all results in a JSON array to STDOUT. I use the '--print' option and store the results to file that is used by a heads up display project that I'm working on. This data is displayed on a monitor in my home along with a bunch of other personal data, including calendar events, daily goals and so on (I will be writing more on this project when more of the code gets to an acceptable level of polish). I also use the the '--direction=in' option and pass the results to a script with '--inbound=/my/path/sms-to-irc.pl' to post the messages to a private IRC channel (code for this to come as well). I can then reply to messages from there, as detailed next.

Send SMS Messages

As above, I have an IRC bot which will listen in a private channel for my replies and send them to the recipient via SMS. The receiving script mentioned above, posts inbound messages with a shortcode ID for the recipient, so the bot looks for replies with "xxx: My Reply.", finds out which phone number "xxx" belongs to then sends the message using a dedicated send script (this code also to come soon). Because the sending functionality is separated, I can send messages from other sources including cron tasks, triggered events and so on. I use these latter options to send messages to myself to alert me to things as wide as traffic delays, library book holds/due dates, and camera motion detection.

Audio Conferencing

A while ago I threw together some tools for creating and manipulating audio conferences in PHP which shells out to the API wrapper that I'd already written in my own time. I've come up with a use-case to utilize audio conferences for personal reasons and so I'm currently working on a new revision of this on my own time, strictly in Perl. I'll post more on it when it is completed.

Other Uses

All of the functionality of the VoIP.ms API is available using the existing module. Given that it is simply an abstraction to allow for easy generation and parsing of HTTP requests, it should work for all future functionality unless the API changes significantly, as well. For people other than myself, there is a lot of functionality to this API that may be very useful. For example, companies with a frequently growing or changing VoIP userbase could make good use of the DID provisioning and configuration options. People who like changing their routing or voicemail messages at various times in the day could use those features (I'm thinking of doing this). The sky is the limit!