To celebrate the New Year, it seemed only fitting to bring Google Voice calling out of the cloud and into our favorite social hangout. For our special New Year's project, we're pleased to introduce Tweet2Dial. It lets you use Twitter or your favorite Twitter client to make free outbound calls through Google Voice to anyone in the United States or Canada. Just send a Direct Message to your new Twitter account and, in less than a minute, your phone will ring connecting you to the person's phone number you specified in your Twitter message. In addition, you also can send SMS messages to anyone with an SMS-capable device in the U.S. and Canada. All of this magic is managed on your existing Asterisk® server or almost any Linux server or Mac. There's no Asterisk overhead to process the calls and SMS messages because Asterisk isn't required! But, to start 2010 off on the right foot, we've included a little bonus at the end of this article for all the Asterisk administrators in the house. If you happen to be using an Asterisk server, you now can manage it from Twitter with Tweet2Dial, too.

For those with cellphone plans that let you designate certain numbers for free, unlimited calling (such as Sprint, AT&T, Verizon, and T-Mobile), adding your Google Voice number to your preferred number list will mean that all of your Tweet2Dial-originated cellphone calls to anyone and everyone throughout the U.S. and Canada will now also be totally free with no impact on your bucket of call minutes.

Yes, we know Jajah is working on something similar for Twitter. But you have to be invited to participate in Jajah's beta (we didn't make the cut!), free calls are limited to two minutes, and both parties have to have a Twitter account which doesn't work too well for calling grandma. So why put up with all the limitations and restrictions of Jajah when you can do it yourself?

There's been some tech chatter that the procedure we've outlined below is complicated. If you can paint by number or bake cookies from the back of a Nestle's bag, trust me. You can handle this! Getting a Mac or a Linux server set up to support Tweet2Dial only takes a minute or two. So ignore the trade rags. Some of them can barely read. 🙂

If you've already gone through our Google Voice tutorial which enables free Google Voice calling on your Asterisk server, or if you've installed our all-in-one Orgasmatron V build on your Asterisk server, or if you have a Mac or you've built your own Linux server without Asterisk, there's no need to wait for Jajah and no need to limit your calls to two minutes or to those with Twitter accounts! You can call anyone in the United States or Canada right now, talk as long as you like, and do it all for free with Tweet2Dial, Twitter, and Google Voice! If you're a Windows user, check out the Google Voice Dialer for Windows.

Prerequisites. To get started, you can use your Asterisk server configured for Google Voice as we've outlined above. We won't actually be using Asterisk to place the calls, but our previous tutorials get your server properly set up with Google Voice and the latest, awesomest1pygooglevoice to support Tweet2Dial. Any of the Asterisk aggregations such as PBX in a Flash will work great.

If you don't have a PBX in a Flash server with Google Voice already configured, shame on you! Just kidding. Actually, any recent CentOS or Fedora Linux server will work just as well today. Log into your server as root. Run rpm -q python to make sure you have at least Python 2.4 installed on your system. If not, run: yum update python. Then execute the following commands:

Tweet2Dial also will run just fine on any Mac of recent vintage. We've actually tested it with Snow Leopard. Basically, to get Python and Apache set up properly, you have to enable root access, switch to root user access with su in Terminal, activate PHP support in Apache, turn on Web Sharing in System Preferences->Sharing, run easy_install simplejson as root to install simplejson (the Python Setup Tools already are in place!), using a browser download pygooglevoice to your Downloads folder, untar it as root in Terminal with the same command as above, and then while still logged into Terminal as root, go to the Downloads/pygooglevoice-0.5 folder and run the following command: python setup.py install. The only variations in the Tweet2Dial setup will be the storage location for Tweet2Dial (there is no root folder on a Mac) and the methodology for setting up the crontab entry (HINT: we'll run crontab -e to add a crontab entry since there is no /etc/crontab file). Just follow along using the Mac-specific instructions below for details, and everything will work swimmingly.

To test whether your server is properly configured for Tweet2Dial, log in as root and type: gvoice. You should be prompted for an email address. If so, press Ctrl-C to exit. You're ready to roll. If not, pygooglevoice has not been properly installed on your server.

You'll obviously need a Google Voice account. Request an invite here or just post a brilliant comment below, and one might magically appear in your inbox. Configure your Google Voice account with all the phone numbers from which you want to place outbound calls. One of these numbers will already be the go-between number for Google Voice and your PBX in a Flash server (IPkall or SIPgate) if you've followed our previous tutorials. Now simply add additional numbers that you want to use to place outbound Google Voice calls. This would include numbers such as your cellphone, your vacation home, and your direct-dial office number. You do not need to enable them for ringing when inbound calls arrive on your GV number.

For today's project, you'll also need a new Twitter account even if you already have one. Why? Because you can't send a Direct Message to yourself with Twitter. So we'll use your primary Twitter account to send Direct Messages with dialing instructions to your secondary Twitter account. Then we'll use Tweet2Dial to poll your secondary account and retrieve the dialing instructions to actually place the outbound calls with pygooglevoice through your server. It sounds harder than it actually is. Honest! Assuming you already have Google Voice running on your Asterisk server, you'll be tweeting away in 10 minutes. If you have a current Linux server, add an extra 2 minutes to install pygooglevoice using the steps above.

Usage Considerations. Before someone asks, let's address Question #1. Can others send messages to my Twitter account in order to make outbound calls through my server using Google Voice? And the answer is yes and no. We're going to configure your new secondary Twitter account with Protect My Tweets enabled. This means you have to approve friends and also become their friend before they could send a Direct Message to your secondary Twitter account. So, yes, if you approve, any Twitter user could theoretically place calls using your Twitter secondary account. For the average reader, we wouldn't recommend it for a couple of reasons. Here's why.

Google Voice only lets you link a handful of phone numbers to your GV account. So, for your friends to be able to place calls using your GV credentials, you'd have to forfeit one of your allotted quota of numbers for each person... or their phone would never ring to place the outbound calls. Yours unfortunately would! Remember, Google Voice always places two calls to complete a connection: one to you (using one of the phone numbers defined in your GV account) and one to the person with whom you wish to speak.

The other reason for not opening this up to other callers is that Google Voice limits your account to one outbound call at a time. If others are using Twitter to make calls using your GV credentials, it means you can't. And there's no mechanism for easily identifying when a call already is in progress. So our recommendation is to keep your secondary Twitter account private and set up Following and Follower linkage only with your primary Twitter account. This will mean that Direct Messages to your secondary Twitter account can only originate from your primary Twitter account. You can still place outbound calls to anybody, but others can't!

Having said all of that, we've designed Tweet2Dial so that you can allow others to use your secondary Twitter account to place Google Voice calls using their own GV credentials. This saves them the aggravation of setting all of this up, but it means they have to trust you enough to share their Google Voice credentials. After all, what are friends for? 😉 At the end of this article, we'll walk you through how to do this if you really have the urge. We would hasten to add that the actual processing load on your server is virtually zero so don't be deterred by performance concerns. Pygooglevoice sends the calling instructions to Google Voice, and then your server is completely out of the call loop. We've still limited outbound call setup to one call per minute, but these calls do not have any impact on Asterisk resources and only very minimal impact on your server. The only drawback to hosting Tweet2Dial for your friends is that, if five simultaneous Twitter messages are sitting in the queue, it would mean the last call request won't be processed until about 5 minutes after the Twitter message was sent. But, unless you have a bunch of extremely chatty friends, call request congestion shouldn't be a problem.

One final word of caution. Twitter currently permits a maximum of 150 Twitter API calls per hour per account. There is some good news. Within the next few weeks, this limit will be increased to 1500 per hour, but it hasn't happened yet. This application is designed to poll your secondary Twitter account once a minute to retrieve and then discard your oldest, existing Direct Message. So it uses 120 of your allotted 150 API calls per hour to work its magic. You are well advised NOT to run any third-party Twitter applications with this secondary Twitter account, or you will quickly exceed the current connection limitation. When the API limit is reached, it means none of your pending call requests would be processed until the next hour rolls around... at least until Twitter raises this connection limit. Once Twitter raises the API limit, we may revisit our code and eliminate the current one call per minute limitation. So stay tuned!

Creating A Secondary Twitter Account. First, let's get your secondary Twitter account set up. Go to twitter.com and create a new account with a very secure password! You must enter a different email address than the one used for your primary account. Use one you can actually access! Log into your new account and choose Settings. Scroll down to Protect my tweets and check the box by clicking on it. Save your settings. NOTE: This check box is critically important. It keeps the entire world from being able to access your server! There are other layers in the security model, but this one is VERY IMPORTANT so verify it twice! Now log back into your primary account. Then goto http://twitter.com/SecondaryAccountName and request access. You'll get a message that your request for access has been sent. Log out and back into your secondary account once again. Authorize your primary account name as a Follower. Now log out and back into your Primary Account. We'll use it to send a Direct Message to your secondary account in a few minutes.

Installation and Configuration. To install Tweet2Dial, log into your server as root and issue the following commands:

If you're doing this on a Mac, there is no wget application and no root folder so you'll need to download tweet2dial.tgz with your browser. Save it to your Downloads folder. Then open a Terminal window and execute this command:

Begin by entering your secondary Twitter name and password by replacing TwitterUsername and TwitterPassword with your actual credentials. Be careful here. Capitalization matters! If you set up your Twitter username as gvNerdUno, don't enter gvnerduno! Now move down to the four $user entries. The first is your primary Twitter account name. Replace YourPrimaryTwitterUsername with your actual Twitter account name. Again be careful of capitalization! Next, enter the login email address for your Google Voice account replacing YourGoogleVoiceEmailAddress@gmail.com. Next, enter your Google Voice password replacing YourGoogleVoicePassword. Finally, enter one of the 10-digit ringback numbers you've configured in your Google Voice account by replacing 6781234567. Do NOT use the one that's reserved for use by Asterisk! This is the number that will be called by default whenever you place an outbound call with Twitter. You'll have the option of overriding it, but this saves your having to enter both a destination phone number and a callback number each time you wish to place a call. Be sure to preserve the quotes around each of the entries. Once you've double-checked all of your entries for typos, save your changes: Ctrl-X, Y, then Enter.

Tweet2Dial Test Drive. Now that everything is set up, let's place a test call to be sure everything is working. Log into your primary Twitter account. Click on Direct Messages. Choose your secondary Twitter account from the pulldown menu. In the block below Send a Direct Message, enter a 10-digit number in the U.S. or Canada that's different from your default callback number. Then click the Send button. It's that simple! Once Twitter tells you the message has been sent, log into your Asterisk server and execute the following commands.cd /root./tweet2dial.php

If you're on a Mac, just open a Terminal window and type ./tweet2dial.php. In either case, you should get a response indicating that your call has been placed, and your default phone number should begin to ring. When you answer it, Google Voice will place a call to the 10-digit number that you entered in your Twitter direct message above.

Now, just for fun, run Tweet2Dial again: ./tweet2dial.php. If everything is working properly, you will see the following message: Nothing to do.

Finally, assuming you have configured another callback number in Google Voice that is close at hand and not your Asterisk callback number, send another Twitter direct message with the following syntax: 8439876543:6781234567 where 8439876543 is the 10-digit number of someone you wish to call and 6781234567 is a 10-digit ringback number already set up in your Google Voice account. Once the message has been sent, run Tweet2Dial again from the command prompt.

When you're sure everything is working reliably, add the following entry to the bottom of /etc/crontab unless you're using a Mac. This will run the application once a minute around the clock looking for incoming Twitter messages:

* * * * * root /root/tweet2dial.php > /dev/null

If you're running this on a Mac, add an entry to your crontab like this. From the Terminal window, run: crontab -e. Once the vi editor opens, type:

* * * * * /users/youracct/tweet2dial.php

Substitute the name of your Mac account for youracct. Then press the Esc key followed by :wq. Check your work by typing: crontab -l. Your entry should look like this:

* * * * * /users/youracct/tweet2dial.php

Sending SMS Messages with Twitter. To send SMS messages using Twitter, you'll use the same scenario outlined above to place free phone calls. Just send a direct message to your secondary Twitter account. Only those that you have authorized as friends can send direct messages to this account so it's as secure as you want it to be. The syntax for an SMS message looks like this where 6781234567 is the cellphone or Google Voice number of the SMS recipient:

SMS:6781234567:Here is a sample SMS message

Any replies to an SMS message which you send using Twitter will be forwarded to the email address that you used to set up your Google Voice account.

For Whiz Kids Only. Now let's say you want to let your spouse use her Twitter account to place calls using her very own Google Voice credentials. First, you need to authorize her as a follower in your secondary Twitter Account. Second, you need to add a new block of code in tweet2dial.php that looks like the following. Place it immediately below the existing $user entries in the file:

Notice that the only change is this array subset is numbered [2] while the original was numbered [1]. You can add as many as you like so long as you increment this number and provide the credentials for each user. Now you have your own little Jajah-like sandbox, and it's absolutely free.

For Asterisk Administrators Only. Want to manage your Asterisk server from Twitter? There's an app for that. We promised you a New Year's bonus so here it is. First, read our last article which explains how to manage your Asterisk server using email messages and the Asterisk CLI. Now you can do exactly the same thing using Twitter direct messages. The only Twitter user that can do this on your server is the Twitter account name you specified in the #1 $user slot above. So you don't have to worry about your pals trashing your Asterisk server if you give them privileges with Tweet2Dial. The syntax for issuing CLI commands using Tweet2Dial looks like this:

CLI: database show cidname 8437978000

Just be sure Direct Messages from your primary Twitter account begin with CLI in all CAPS followed by a colon, a space, and then the desired CLI command. That's all there is to it. You'll get a confirmation Direct Message in your main Twitter account once the command has been executed assuming you have established Following and Follower linkage between your primary and secondary Twitter accounts. Test sending DMs in both directions to double-check it. And if you've enabled email delivery for Direct Messages in your Twitter configuration, you'll get an email confirmation as well. Because of Twitter's 140 character limitation, some commands such as help don't provide all of the output you normally would receive from the CLI. You'll only get the last line. Aside from that, the CLI functionality is identical to interacting directly with the Asterisk CLI and the email implementation we outlined previously. Here's the CLI response:

Before you can use the CLI interface in Tweet2Dial, you have to enable it. Edit tweet2dial.php and change $CLIenable=false to $CLIenable=true. And, yes, we understand there are some of you that don't trust Twitter to keep your commands secure. Well, first of all, in order to penetrate your Asterisk server, someone would have to send a Twitter Direct Message from your primary Twitter account. So they'd need your password and they'd need to know the syntax for Asterisk CLI commands AND the syntax for sending them via Twitter. But, there's always a Cracker Rapper2 somewhere. Right? So we've also built a password into the system at your server's end so you can sleep more comfortably. The default password is CLI. But feel free to change it to anything you like. Just edit tweet2dial.php and find this line: $CLIpword = "CLI";. Replace CLI (between the quotes only!) with whatever password you'd like. After saving your changes, you'll need to adjust your Twitter messages accordingly. For example, if you changed your password to FooBar, then your future Twitter CLI command syntax would look like this: FooBar: help. Enjoy!

Special Thanks. As Nerd Vittles prepares to celebrate its Fifth Birthday, we want to take a moment to thank those that have made Nerd Vittles and the PBX in a Flash project possible. Without the generous financial support of Vitelity and Google's AdSense program plus the unwavering support of our hosting providers who provide free downloads of PBX in a Flash around the globe, all of what we do would be much more difficult and expensive! It's not too late for you to kick in a nickel or two as well if a fleeting moment of generosity should strike. 😉 There's a Donate button at the top of the page. Finally, we want to thank Digium® for their continuing support of the Asterisk project and their generous contribution of hardware to the PBX in a Flash development team during 2009. Happy New Year everybody!

whos.amung.us If you're wondering what your fellow man is reading on Nerd Vittles these days, wonder no more. Visit our new whos.amung.us statistical web site and check out what's happening. It's a terrific resource both for us and for you.

Special Thanks to Our Generous Sponsors

FULL DISCLOSURE: 3CX, RentPBX, Amazon, Vitelity, DigitalOcean, Vultr and others provide financial support to Nerd Vittles and our open source projects through advertising or referral revenue. We’ve chosen these providers not the other way around. Our decisions were based upon their corporate reputation and the quality of their offerings and their pricing. Our technology recommendations are reached independently of financial considerations except in situations in which comparable products at comparable pricing are available from multiple sources. In this limited case, we support our sponsors because our sponsors support us.

Awesome Vitelity Special. Vitelity has generously offered a terrific discount for Nerd Vittles readers. You now can get an almost half-price DID from our special Vitelity sign-up link. If you're seeking the best flexibility in choosing an area code and phone number plus the lowest entry level pricing plus high quality calls, then Vitelity is the hands-down winner. Vitelity provides Tier A DID inbound service in over 3,000 rate centers throughout the US and Canada. When you use our special link to sign up, Nerd Vittles gets a few shekels down the road to support our open source development efforts while you get an incredible signup deal as well. The going rate for Vitelity's DID service is $7.95 a month which includes up to 4,000 incoming minutes on two simultaneous channels with terminations priced at 1.45¢ per minute. Not any more! For our users, here's a deal you can't (and shouldn't) refuse! Sign up now, and you can purchase a Tier A DID with unlimited incoming calls and four simultaneous channels for just $3.99 a month. To check availability of local numbers and tiers of service from Vitelity, click here. NOTE: You can only use the Nerd Vittles sign-up link to order your DIDs, or you won't get the special pricing! Vitelity's rate is just 1.44¢ per minute for outbound calls in the U.S. There is a $35 prepay when you sign up. This covers future usage. Any balance is refundable if you decide to discontinue service with Vitelity.

Hello Ward! Great to see this article today! As soon as I get home I’ll be playing with this. Thanks to NerdVittles now from Puerto Rico I have a Florida Number (GVoice) and a Washington number (IPKall), and soon I will have a free tweet2dial! 😀 Thanks!

REQUEST: Does anyone know how to set up asterisk to receive an SMS with a number and call-back the number the SMS came from and patch it with a call to the received number? (also if anyone know an international SMS provider please email me). sethpr@hotmail.com Thanks.

Thanks Ward. This is great.
I’ve been trying to do some digging around the internet to see if anyone has been doing any integration with femtocells and PIAF? Heard anything? Sounds like magicJack has a new product coming out, and wondered if it could be integrated into PIAF?

Just a quick comment. I followed your instructions (several times) before I looked further at the tweet2dial.php file and after some testing found that the line:

require “/root/twitter.lib.php”;

Needs to be changed to the path your twitter.lib.php actually is in (obviously I guess). I untar’d the package both as root and without and as you point out, since Mac’s don’t have a root folder it gets unpacked in the user’s directory.