How to Be Alerted When Your VoIP Goes Down

We've found our VoIP setups to be exceptionally reliable, on a par with our former landlines.  But friends have expressed hesitation about tying their communications to the Internet.  What if there's an outage?

You'll practically never ever see this.

First, I hope it's clear that landlines are not immune from outages, either.  And unlike an answering machine hooked up to your landline, your VoIP voicemail is handled at the server level, so callers can still leave messages even if your local Internet is down.  Which, again, rarely happens around here...

But there's comfort in knowing the status of your complete VoIP system.  Fortunately, my provider, voip.ms, provides an applications programming interface (API) that makes it simple (but geeky!) to have your Mac continuously monitor your VoIP-line status and alert you if there's an outage or even if your equipment is having problems.  (My example code below is platform-independent, too, and can be adapted to whatever live-desktop and alert mechanism works for your computer.)

The trick is to leverage a wonderful utility called GeekTool to periodically check your account registration status on voip.ms' servers.  GeekTool can run scripts, and it's pretty easy to make a script which will use voip.ms' API, display the status and even trigger an alert via another popular utility called Growl.

Here's how

First, download and install GeekTool.  (An application version in the Mac App Store is coming soon-- at the time of this writing, it's a Preference panel instead.  OS X Lion users should prowl the site for the latest, Lion-compatible version.  UPDATE: The App Store version is here!  Mac App Store Link)  If you want alerts to pop up to notify you when an outage occurs, also download Growl and be sure to install Growlnotify from the Extras folder on its disk.  (You may already have Growl installed--it's part of Dropbox and other popular utilities and applications--but I doubt you have Growlnotify.)  Now:

• Log on to your voip.ms account.  In the tab marked "Main Menu", select the "SOAP and JSON/REST API". 
• Scroll down to the bottom.  Enable the API, assign a password (which can be different from your login password), and enter your IP address.  Click the update buttons after each entry.
• Scroll up a bit, and look for the link that says "Click here to download Example Codes and API Documentation"  Download this, unzip, and look for the folder entitled "Examples SOAP for PHP5."  In this folder, look for the document "class.voipms.php".
• Open class.voipms.php using TextEdit.  Put your account number and API password in it up top, then save it somewhere handy-- for example, I have a folder called "geekvoip" in my Documents folder.

Your account is now set up for automated access and monitoring.  Here's a simple script which we'll call from GeekTool:

GeekTool.

Copy that and paste into TextEdit.  (Note my example is made to check two subaccounts-- the code is easily modified to handle any number.)  Put your subaccount number(s) in it, and save it with a .php extension in the same folder you just saved class.voipms.php in. In my case, the file is named voip.php.

Now, open GeekTool.  Drag a Shell object onto your desktop.  In the Command field of the object, type a php command to execute the file you just saved.  In my case, the command looks like:

php ~/Documents/geekvoip/voip.php

Good settings for the GeekTool object are a Refresh of perhaps 600 seconds and a timeout of maybe 20 seconds.

My collection of GeekTools

includes status monitors for

my family's two VoIP lines.

You're done!  Position and size the GeekTool object as desired, and it will always be on your desktop.  If you've installed Growlnotify, you'll see a pop-up notification on the exceedingly rare occasion that your VoIP line can't be reached.