VoIP.ms API Wrapper and Tools
VoIP.ms is a cool VoIP phone, SMS and Conference provider. They also have a cool API that lets you do other cool things. Perl is a cool programming language which makes doing cool things easy. It's all pretty cool...
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.
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.