Home » Technology » It’s TweedleD: Twitter & SMS Alerts with Every Asterisk Call

The Most Versatile VoIP Provider: FREE PORTING

It’s TweedleD: Twitter & SMS Alerts with Every Asterisk Call

Twitter Direct Messages and SMS Instant Messages are great ways to send yourself important notes that you want to keep track of... privately. Today, we'll show you how to harness the power of Twitter and SMS to announce every call on your Asterisk® server with the name and number of the caller as well as the DID of the incoming call. Reconfiguring your Asterisk server takes less than 10 minutes. We think you'll find this to be the perfect complement to our free Urang II desktop screenpop utility.

Prerequisites. You'll need one of the Asterisk aggregations to get all of this working quickly. At a minimum, you need Asterisk 1.4 or 1.6, FreePBX, Apache, PHP 5, PHP/AGI, and SendMail or an equivalent. You'll also need a service that provides CallerID name lookups such as CallerID Superfecta. We're assuming you already have all of these components working including outbound email which is necessary to deliver the SMS alerts.

Overview. The design strategy for TweedleD is pretty straight-forward. When a call comes into your server, FreePBX should catch the call in an inbound route that looks for incoming calls on a particular DID. A CallerID Lookup source will be used in the Inbound Route to look up the name of the caller based upon their CallerID number. Then we will use a Custom Destination to route the call to a special Asterisk context which will run the TweedleD AGI script. This script actually sends out the Twitter Direct Messages as well as the SMS messages to your cellphone. Once the script completes its work, the context will send the call along to its final destination, e.g. an extension, a ring group, a day/night control, or an IVR.

NOTE: There is a 100-150 API calls per hour per IP address limit with the Twitter API. If you also are using one or more Twitter clients at your site, this is something worth keeping in mind if you have a busy phone system.

1. FreePBX Custom Context. The trick with designing FreePBX dialplans is to build them in reverse. So we'll start with the custom context and work our way back to the inbound route. First, log into your server as root and edit extensions_custom.conf in /etc/asterisk. At the end of the file, we want to create a new context that looks like this. We've provided several sample destinations at s,5 to show you the syntax. The first routes a call to an extension or ring group number. The second routes the call to Day/Night Control #1. And the third routes the call to an IVR. To find the correct IVR number or day/night control for what you want to do, review the IVR and app-daynight contexts in extensions_additional.conf to find the one you need. Obviously, you only use one s,5 line. Comment out the remaining ones as shown below. For Asterisk 1.6, replace the vertical bars in line s,3 with commas.


2. Installing PHP/AGI Scripts. Next we need to install the script that actually generates the messages for Twitter and SMS. In addition, we'll install Justin Poliey's terrific twitter.lib.php which is a PHP implementation of the Twitter API that lets you do just about anything with Twitter that you could do with the Twitter API itself. For a good writeup on the capabilities of twitter.lib.php, see Antonio Lupetti's article. To install the necessary code, issue the following commands while still logged in as root:

cd /
wget http://bestof.nerdvittles.com/applications/TweedleD.tgz
tar zxvf TweedleD.tgz
rm TweedleD.tgz
cd /var/lib/asterisk/agi-bin

3. Configuring TweedleD. Now we need to configure the PHP script with your Twitter and SMS credentials so that TweedleD knows where to send the messages. Edit nv-twitter.php in the /var/lib/asterisk/agi-bin directory on your server: nano -w nv-twitter.php. You'll see a section of code near the top of the application that looks like this:

//-------- DON'T CHANGE ANYTHING ABOVE THIS LINE ----------------

$tweet = 0;
$username = "your-twitter-name";
$password = "your-twitter-password";
$user4msg = "recipients-twitter-name";

$sms = 0;
// $smsaddress = "1234567890@txt.att.net" ; // AT&T
// $smsaddress = "1234567890@message.alltel.com" ; // AllTel
// $smsaddress = "1234567890@messaging.nextel.com" ; // Nextel
// $smsaddress = "1234567890@messaging.sprintpcs.com" ; // Sprint
// $smsaddress = "1234567890@tmomail.net" ; // T-Mobile
// $smsaddress = "1234567890@vtext.com" ; // Verizon

$debug = 0;
$newlogeachdebug = 1;

$emaildebuglog = 0;
$email = "yourname@yourdomain" ;

//-------- DON'T CHANGE ANYTHING BELOW THIS LINE ----------------

There are four things you can enable and, depending upon what choices you make, you need to add your credentials for the various options. Let's go through them in the order they appear.

To enable Twitter Direct Messages, change $tweet=0 to $tweet=1. $username and $password are used to set your Twitter login credentials for your Twitter account. You must have one! $user4msg is the Twitter account name where the DMs should be delivered. They do not necessarily have to be delivered to your Twitter account although they can be. Be sure to preserve the quotes! And, remember, you can only send direct messages to people on Twitter that you are following, and they must be following you as well. If in doubt, attempt to send a direct message in Twitter to the desired recipient. Then you'll know for sure. TweedleD provides no error messages if things don't work. 🙁

To enable delivery of SMS messages to your cellphone, set $sms=1. TweedleD actually delivers SMS messages using email. Virtually all of the carriers provide an SMS-Email Gateway for this purpose. The trick is knowing the email domain for your desired carrier. The full list is available here. And here is an even newer Email to SMS Gateway list. In the script, we've provided samples for the major U.S. carriers so, if yours is in the list, just uncomment the appropriate line by removing the leading // on the line and replace 1234567890 with your 10-digit cellphone number.

If you want a debug log generated for each call, set $debug=1. The default is to overwrite the previous log (/var/log/asterisk/nv-twitter.txt) with each new call. If you'd prefer an ever-growing log, set $newlogeachdebug=0.

The debug log also can be emailed to you. Set $emaildebuglog=1 and enter your email address in $email.

When you've completed the configuration, save the file (Ctrl-X, Y, Enter) and reload the Asterisk dialplan: asterisk -rx "dialplan reload".

4. FreePBX Setup. Finally, we need to configure FreePBX to support TweedleD. We'll add a Custom Destination and then adjust our inbound route(s) to support the custom context we added in Step 1. Open FreePBX with a web browser and choose Admin, Tools, Custom Destinations, Add Custom Destination. For the Description, call it TweedleD. For the Custom Destination, enter the following: custom-twitter,s,1. Then click Submit. Now edit your Inbound Routes for the DIDs for which you wish to activate TweedleD. For each inbound route, make sure you have activated a CallerID lookup source and then set the destination to: Custom Destination: TweedleD. Save your changes and reload the dialplan.

Trying Out TweedleD. Now you're ready to place a test call. Just call into your system on one of the DIDs that has been configured for TweedleD. On the Asterisk CLI, you should see an entry that identifies the CallerID name and number of the caller. And, if you've activated delivery of notifications to Twitter and/or SMS, the messages will magically appear within seconds. Enjoy!

Tips of the Week. If you hurry, you can get 25GB of free, password-protected online storage with the new Microsoft SkyDrive offering. Or, for a free incoming call number for your Skype account, check this service out. A new precompiled version of Asterisk 1.6 for Mac OS X Leopard has been released. You can download it here. Finally, Sprint is offering a Netbook for 99¢ with any 2-year EVDO contract at Best Buy stores this week. Regular price for the Compaq Mini is $389.99. Add your cell phone or Asterisk DID to the DO NOT CALL Registry. Just call 888-382-1222 using the CallerID of the number to wish to block.

Sign of the Times. Before you get too comfortable with all your free Google apps, you might want to read this article. Despite assurances to the contrary from Google's President of Enterprise, it seems that the free version of Google Apps has quietly disappeared.

Update: Google Apps team invokes Brain Fart defense saying they momentarily forgot about "free" but it won't happen again. Heh, heh. Official Blog Posting.

VoIP Users Conference. Come join the fun. The VoIP Users Conference is held every Friday at noon, Eastern time. ISN: 8647*1061 (Hint: 8647 spells VOIP on your phone).

The World According to Twitter. Be on the lookout for David Pogue's new book, The World According to Twitter. It goes to press today! Incidentally, Pogue's books are just about the only reasonably priced tech books available for the Kindle, and they're all excellent.

Tomorrow's the Big Day. The last time this happened, it was a pretty quiet year. Just after noon tomorrow comes your once-in-a-lifetime moment when the time will officially be 12:34:56 7/8/9. The last time we had this much fun in our lifetime was... uh, about a year ago: 01:23:45 6/7/8. Can't wait for next year's thriller: 23:45:67 8/9/10. Ooops! That won't work on most clocks. Will it? Amazing what you can learn on Twitter. Isn't it? Thanks, @ejovi and @ev.

Need help with Asterisk? Visit the PBX in a Flash Forum.
Or Try the New, Free PBX in a Flash Conference Bridge.

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: ClearlyIP, Skyetel, Vitelity, DigitalOcean, Vultr, VoIP.ms, 3CX, Sangoma, TelecomsXchange and VitalPBX have provided financial support to Nerd Vittles and our open source projects through advertising, referral revenue, and/or merchandise. As an Amazon Associate and Best Buy Affiliate, we also earn from qualifying purchases. We’ve chosen these providers not the other way around. Our decisions are based upon their corporate reputation and the quality of their offerings and pricing. Our recommendations regarding technology are reached without regard to financial compensation 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.

BOGO Bonaza: Enjoy state-of-the-art VoIP service with a $10 credit and half-price SIP service on up to $500 of Skyetel trunking with free number porting when you fund your Skyetel account. No limits on number of simultaneous calls. Quadruple data center redundancy. $25 monthly minimum spend required. Tutorial and sign up details are here.

The lynchpin of Incredible PBX 2020 and beyond is ClearlyIP components which bring management of FreePBX modules and SIP phone integration to a level never before available with any other Asterisk distribution. And now you can configure and reconfigure your new Incredible PBX phones from the convenience of the Incredible PBX GUI.

VitalPBX is perhaps the fastest-growing PBX offering based upon Asterisk with an installed presence in more than 100 countries worldwide. VitalPBX has generously provided a customized White Label version of Incredible PBX tailored for use with all Incredible PBX and VitalPBX custom applications. Follow this link for a free test drive!

Special Thanks to Vitelity. Vitelity is now Voyant Communications and has halted new registrations for the time being. Our special thanks to Vitelity for their unwavering financial support over many years and to the many Nerd Vittles readers who continue to enjoy the benefits of their service offerings. We will keep everyone posted on further developments.

Some Recent Nerd Vittles Articles of Interest...


  1. Worked first time I tried it, after going through the install steps even without the lookup stuff in place. I fuly expected to have to use the dubug parts, but although that worked a treat as well it was just not required! All I need now is to work out how to integrate better into FreePBX so that I don’t need to create a custom context for each inward route (I have many), each of which ends up doing something different. Great add-in, thanks very much.

  2. Hi Ward… Interesting thing to do with Asterisk and Twitter… never thought of mixing the two LOL. I just wrote to thank you for the deal with Vitelity, it works great and very affordable, funny thing though, I got a Puerto Rico DID, but could not make calls to Puerto Rico until I sent them ID and CC copy by fax… Odd!!! Even Vonage knows Puerto Rico is US! Anyway, it’s working great now.

  3. Hey, This is so cool. Here is how i use it. In denmark the cellular providers have closed the xxx@provider.com so i can’t get SMS BUT i have an iPhone and i can use Push Notifications together with a IM+ which sends me the Push Notification when there is a new DM on my new account. Now i know the numbers who calls in.

    There is some nice to have things :

    1. Show the trunks name instead of the number that the user was calling into.
    2. Support for 24h time.
    3. Easy editable text
    4. As mentioned Nicholas better way to integrate this into many trunks, i also have many.


  4. The problem with your first step is that it answers the line, which may not be desirable on a DID trunk (doesn’t matter so much if the call came through an IVR), and also it doesn’t "play well" with the FreePBX way of doing things (by using a dial statement to go directly to an extension, which bypasses all sorts of internal FreePBX routines, which may cause certain features to not work as expected).

    I used to use your Urang II utility until I got a Mac and discovered you don’t have a Mac version – then I switched to using the technique shown on this page:


    There’s actually a couple of methods there, but the one I use is the "Alternate Method" shown starting about a third of the way down the page. I believe that method could be easily altered to replace your first step in these instructions. You wouldn’t need the perl script there (though you could still use it if you also want the Growl notifications), instead when you go into etc/asterisk/extensions_custom.conf, in place of (or in addition to) the line

    exten => ****525,1,AGI(growlsend.agi,,GrowlPassWord,525)

    You’d use a line of the form
    exten => ****525,1,AGI(nv-twitter.php|${CALLERID(name)}|${CALLERID(num)})

    Of course you’d have to read the article for this to make sense, but the point is that by doing it using their method you don’t answer the line prior to sending the notification, and you don’t go outside the normal FreePBX call processing to actually complete the call to the extension.

    One other thought: Although the Twitter notifications are a nice touch, I’ve found that Twitter is not nearly as reliable as some of the more venerable Instant Messaging applications such as AIM, or Google’s Jabber-based instant messaging. Since there are even AIM clients available for many phones (and since you don’t incur SMS charges when using IM services, and since you aren’t limited to a specific number of characters and could therefore include additional information such as the date and time of the call), I wish there were a method as easy as this to send an AIM message whenever when a call comes in.

    One other issue with TweedleD at present is that each copy on nv-twitter.php can only handle calls for a single user, due to the fact that the recipients Twitter ID and/or SMS address are hardcoded into the start of the file. Of course it’s easy to create multiple copies of nv-twitter.php (with slightly different names) to handle multiple users, but that’s not exactly the most elegant way to handle it. I wish this functionality could be placed in a module that would then add appropriate fields to each extension’s setup page (for Twitter ID, SMS address, and possibly AIM account name, etc. if you can possibly finagle that) and then if one or more of those fields are filled in, it would send the appropriate notifications when a call comes in. Still, this is great added functionality as it is, so thanks for your work on this.

    [WM: Good suggestions. We’ll have a look. Thanks, Mike.]

  5. A cursory review of the article above raises a number of issues. First, the suggested code monitors extensions as opposed to DIDs. We wanted DIDs, but others may be just as happy with extension monitoring. Second, one of the recommended approaches requires the addition of an Asterisk module which would be difficult to support as new versions of Asterisk are released. The other approach uses Perl and Growl, neither of which are in our bag of tricks. We made the mistake of using some else’s Perl code once before, and it caused us nothing but headaches when fixes were necessary (that we didn’t know how to make). So… it would be an interesting project for someone but probably not for us.

  6. I wanted to respond separately to a couple of other comments in your post. First, the suggestion that we answer an incoming DID call is incorrect. The call already has been answered in the FreePBX call flow before we intercept it. That was the purpose for placing the custom context as the destination of inbound routes. In fact, the procedure you recommended also occurs after a call is answered. Indeed, with calls from outside your PBX, it would be impossible to decipher the destination extension without first answering the call. Second, I don’t share your view that TweedleD "bypasses all sorts of internal FreePBX routines, which may cause certain features to not work as expected." Specifically, what routines do you believe are bypassed? We chose the design we did so that FreePBX processing would not be affected. An inbound call is passed to our custom context only after all FreePBX processing has occurred… with the exception of routing the call to its ultimate destination. We’ve shown how to handle the three most common destination scenarios in the article, and we’d be happy to address other options if anyone has a need.

  7. Ward, sorry if my comments upset you in any way. I had assumed that a notification would be sent when a particular extension (or ring group, etc) was rang, I guess it just didn’t occur to me that anyone would want a notification that a call was coming in on a DID that could be routed to multiple places (such as through an IVR) until the final destination of the call is determined – after all, if Joe and I can receive calls from the same DID (with the caller making an IVR selection to determine which of us gets the call), I don’t want to get notifications of Joe’s calls. Not to say that no one would want that, but I wouldn’t.

    You say that "Indeed, with calls from outside your PBX, it would be impossible to decipher the destination extension without first answering the call." But that’s not true in the specific case where a DID is associated with a single extension. And in that case, where you are in fact talking about a DID that normally goes direct to an extension, then the "Answer" statement on line 1 would assure that the call gets answered (possibly resulting in a toll charge for some callers) even if the destination extension is busy or never answers.

    So either way there’s an issue – if the call (from a DID) goes to an IVR first, then the "Answer" statement doesn’t matter because the IVR has (or will) answer the call, but then you have the issue of whether the party that is supposed to get the call also gets the notification. On the other hand, if a DID is associated with a single extension then, unless I’m totally missing something here, that "Answer" statement guarantees the line will "supervise" whether the extension associated with the DID ever answers or not.

    Regrading the Perl code, I thought I had specifically said that you wouldn’t use that when using your PHP code – your PHP code would replace the Perl code in the article I mentioned. Sorry if I didn’t make that clear enough. So, really, I was simply suggesting a different way of calling your code, that would not result in the call being answered (unless that happened in some other part of the call flow) and that would let you send a notification based on extension (or ring group) called.

    My comment about the code bypassing internal FreePBX stuff was based on the line that includes "Dial(local/701@from-internal)" – I assumed that 701 was the destination extension (since I see no indication anywhere in the article that it references anything else). Perhaps 701 is some kind of special destination on a PiaF system and you forgot to mention that? But if not, then my comment was simply to reflect the fact that you normally don’t include a "Dial" statement to go directly to an extension in a custom context because it could bypass all sort of things such as checking the status of the extension (with regard to Do Not Disturb and similar features), or whether there’s a follow-me applicable to that extension that should be observed, and things of that nature. Again, I may be missing something here and if so I apologize, but personally I just wouldn’t ever feel comfortable about using a "Dial" statement to go directly to an extension in a FreePBX custom context.

    Now having said all that, I saw your FreePBX feature request (that was my first clue that I might have upset you, for which I gain apologize) and I personally thought it was a very valid request and something that many of us have wanted. And it frustrates me no end that the FreePBX developers’ standard answer to everything is that all will be fixed when version 3.0 comes out, when if it were up to me I’d prefer they stop doing any work on a new version and just document the existing one. Frankly I think they are going in the wrong direction and that if they ever do come out with this mythical 3.0, a lot of users are not even going to want it because it will be what one person wants (the leader of the FreePBX development team, who can be kind of an arrogant knucklehead at times) and not something that the users or even many of the would-be developers want. Lord knows they’ve managed to offend enough people who’d like to help develop modules and such for FreePBX, but I probably shouldn’t say any more about that. But anyway, I thought your request was very valid and I wish it hadn’t been just waved off at it was.

    I suppose I shouldn’t ask, but have you ever considered using anything other than FreePBX as the GUI in PBX in a Flash? Does anything similar even exist? I’d love to see something similar but that was more of a community-developed project, and not the "baby" of (at most) a small handful of people (but primarily one person) who just don’t seem to care about being inclusive, whether it be toward existing users or potential new developers. I love FreePBX to death for the functionality it provides, but just really don’t like the way they are so dismissive of feature requests, many module contributions and patches, and even some bug reports, and always seem to be on a quest for the magical but elusive version 3.0.

    [WM: Not offended at all. I really appreciate your comments and apologize if my response came across as harsh. I also didn’t know my FreePBX request already had been rejected. Sorry to hear that. 🙁

  8. Replying to Mike’s comment:

    first off I will mention that I saw the ticket get closed and immediately reopened it (before ever seeing this comment here which was just pointed out to me). Feel free to read the ticket and my comment.

    As far as your comment "…something similar but that was more of a community-developed project, and not the “baby” of (at most) a small handful of people (but primarily one person) who just don’t seem to care about being inclusive, whether it be toward existing users or potential new developers."

    I guess all I can say is that you must be smoking something. Go look through the history of FreePBX and it’s SVN. And that doesn’t tell the whole story given the huge number of checkins that I or others have done on behalf of more casual contributors who have provided their contributions in tickets and forum posts. I seem to recall counting recently, if my memory serves me, there were like 2 dozen people who had svn write access and typcially 6 or so active developers at any given point of time these days?

    The issues of inconsistencies, low on documentation, etc are the very results of an extremely community driven effort and it’s heritage of how it has grown up very ‘un-disciplined’ (which isn’t a good thing per se but is also what has made it so popular)

    As far as v3, it’s being done very hands off. I wish I had WAY more time to spend on it. But at the same time, I am enjoying the fact that there are new developers with new perspectives who are getting involved becasue for all the good things in FreePBX, we don’t also want to go through a rewrite and end up with some of the same baggage that we have today. But anyhow, there will be more information coming shortly on that front, but I can assure you that the work going on is following the legacy of FreePBX, strong community driven development by some great developers!

    So in closing, everyone has the right to their opinion, long live Freedom of Speech. But you may want to consider ‘checking your facts’ when writing strong opinions like that.

  9. Is there anyway that i could out this inside a FreePBX system so i get notified of an missed call instead of all calls ? I think that could be cool to do. I am often not home and i would like to know if somebody made a call to me and i missed it.


  10. Beginning shortly, Twitter will require OAuth authentication to use the Twitter API. This will temporarily break the Twitter component of this application, but we’re working on it.

Comments are closed.