Home » Technology » Asterisk CallerID Perfected: CallerID Superfecta 2.0

The Most Versatile VoIP Provider: FREE PORTING

Asterisk CallerID Perfected: CallerID Superfecta 2.0

If you’re new to VoIP and Internet Telephony, it may come as a shock when you discover that incoming calls no longer display the names of your callers unlike your POTS CallerID service. The problem is that most telephone providers deliver only a CallerID number when sending calls. Your DID service provider is responsible for looking up the incoming number in their directory and supplying a matching name. Simply stated, CallerID numbers are pushed to recipients, but CallerID names must be pulled from in-house databases. With Ma Bell and siblings, this was easy because they had a monopoly on all of the records. They’ve done their best to preserve that advantage. For example, Google provides very good CallerID information for people in the traditional phone book but provides no facility for adding numbers of those that don’t have a Ma Bell line. Coincidence? Probably not. With Internet Telephony Hosting Providers, CNAM lookups are few and far between. A few now will provide CallerID lookups but only on a per call fee basis.

A similar problem arises for outbound VoIP calls that you place. Even though you may provide a CallerID name and number, most telephone companies throw the supplied CallerID name in the bit bucket and do their own lookups. If you’re not in their directory, your number or nothing will be supplied instead of your actual name. Bottom line: This is one major piece of the telephone monopoly that Judge Greene forgot to address. And it’s only going to get worse now that more people own cellphones than Ma Bell landlines.

With Asterisk®, the simplest solution is to do your own CNAM lookups. And today we’re delighted to introduce CallerID Superfecta 2.0, a FreePBX module with incredible flexibility. It also serves as a living testament to how open source development actually should work.

The History Lesson. We originally wrote an AGI script for Asterisk@Home known as the CallerID Trifecta. As sources of CNAM lookups expanded, a number of other individuals contributed code to support those lookups. The original application morphed into the CallerID Superfecta when these new sources were added, but all the code still resided in a difficult-to-maintain PHP/AGI script. Tony Shiffer picked up the ball last year and converted the CallerID Trifecta into a FreePBX module which made it incredibly easy to install the application and configure the providers you wished to use. Fast forward to today, and now Jeremy Jacobs, with help from other members of the PBX in a Flash Forum community, has taken the original work of a number of PBX in a Flash Forum participants and released a real masterpiece, CallerID Superfecta 2.0. It’s not only easy to install and configure, but now it’s incredibly flexible and simple to expand as more and more people begin contributing lookup routines to this open source project. And Tony has put the icing on the cake with a new SVN development site to track bugs and feature requests for this project and others as we move forward.

The CallerID Superfecta Design. As originally implemented, CallerID Superfecta let you choose one or more lookup sources for incoming CallerID numbers. When an inbound call arrived, the sources were queried in a specified order, and the first source that provided a matching CallerID name won. The CNAM search result was returned to Asterisk for display on your phone instruments, and the lookup procedure ended. The problem with the original design was that newer and better lookup providers continued to appear, the hard-coded search order wasn’t necessarily ideal for every user or organization, and the providers kept changing formats to make lookups more challenging. CallerID Superfecta 2.0 fixes all of that!

What’s New. For openers there are a number of new lookup sources as well as some tweaks to older sources that stamped out a few bugs from our previous, sloppy code. 🙂 The web user interface (UI) for FreePBX also has been totally reworked. Now you can prioritize the lookups in the order that best meets your needs. And, as new CNAM lookup sources become available, they are automatically added to the new UI. The code also has been modularized with separate templates for each provider. This makes the addition of new lookup sources incredibly simple to implement. There’s also a new debug function built directly into the web user interface. By entering a telephone number in the new debug field and pressing the debug button on the form, the results from your selected lookup sources together with the latency of each enabled data source are displayed on the form for you to review. This new debug function greatly enhances troubleshooting while serving as a terrific tool to assist in fine tuning which providers to actually enable and in what order. Providers who can’t be reached, or who perform too slowly, or who provide lousy results can be turned off completely or moved to the bottom of the search order. Finally, CallerID Superfecta 2.0 introduces prefix code hooks. This gives developers the ability to trigger an additional outside process when the Caller ID function is initiated. For example, this feature might be used in a call center to allow the system to automatically perform an ODBC query and bring up a customer record for use by a customer service representative.

Installing CallerID Superfecta 2.0. Installation and setup should be a snap on any of the FreePBX-based Asterisk aggregations including PBX in a Flash. First, using a browser on your desktop PC, download CallerID Superfecta 2.0 from the Superfecta repository. Do not decompress the .tgz archive. Second, open FreePBX with your browser and choose Admin, Module Admin, Upload Module. Browse and select the superfecta-2.x.x.tgz module from your desktop and click the Upload button. When the upload completes, click local module administration. Scroll down and click CID Superfecta. Click the Install or Upgrade radio button depending upon whether you have previously installed the Superfecta FreePBX module. Click Process, Confirm, Return to install the new module. Reload the Asterisk dialplan when prompted.

Configuring CallerID Superfecta 2.0. There really are only two steps to bring CallerID Superfecta on line. First , we’ll configure the lookup sources and search order of the lookups. And then, for each inbound route on your Asterisk system, we’ll tell FreePBX to use CallerID Superfecta as the CallerID lookup source.

To configure CallerID Superfecta, click Admin, Setup, CID Superfecta in FreePBX. If you’re using PBX in a Flash or trixbox, be sure to insert the UserName maint and your FreePBX maint password in the fields provided under General Options. Then choose the Services you’d like to use for queries by clicking on the corresponding Enabled buttons. If you’re unfamiliar with previous versions of the product, we’d recommend you start with Addresses, White Pages, Yellow Pages, Any Who, and Telco Data. If you use the Asterisk Phonebook, AsteriDex, or SugarCRM, enable those options as well. Our rule of thumb in prioritizing the searches is to move your personal directories (Asterisk Phonebook, AsteriDex, and SugarCRM) to the top of the list. For the remaining choices, we recommend you start with the following search order: Addresses, White Pages, Yellow Pages, Any Who, and then Telco Data. Telco Data normally returns only the city and state of the caller, not the caller’s name. Who Called requires registration. Once you get everything squared away, click the Save button. Then key in a few known phone numbers in the Debug section of the form and click the Debug button to make sure everything is working as you expected. Take note of the retrieval times and the results and adjust the search order to meet your needs. Remember, the first match on a name using the search sources from top to bottom wins. The other search sources are never consulted for this number.

For additional configuration options and tips on configuring SugarCRM, see this thread on the PBX in a Flash Forum.

Once you’re satisfied with your lookup sources and the search order, the only remaining step is to designate CID Superfecta as the CallerID lookup source in your inbound routes. For each inbound route on which you want CallerID lookups performed, click Admin, Setup, Inbound Routes and choose the desired route from the column of routes on the right margin. Scroll to the CID Lookup Source section of the form and choose CID Superfecta from the dropdown box. Click Submit, Apply Config Changes, Continue to save your entry. Enjoy!

Good Things Are Coming. Sometimes you can just sense that something really terrific is about to happen with a project that’s been properly nurtured. So it is with PBX in a Flash. Many of us invested countless hours in the Asterisk@Home project, but it just never quite took off in terms of fostering independent development. And that is what open source is all about. When we started the PBX in a Flash project with Tom King and Joe Roper, we wanted something different, a participatory platform that could get folks excited about Internet telephony and open source development. As long time readers of this column know, we’ve pumped lots of applications into PBX in a Flash in hopes of encouraging others to catch the spark. Well, we’ve made it. CallerID Superfecta 2.0 is a perfect example of a creation from a developer who hasn’t previously contributed to any open source project. And there now are many more in the works. So we’re excited for the Asterisk community. Seeing your baby grow up is quite a thrill. We’re quickly building a network of application developers and contributors of many varieties, and it is starting to transform a really good telephony toolbox into a really spectacular application platform. Have a look at this new project to get a glimpse of what lies ahead.

This isn’t a private club. If you’d like to participate in a big or a small way, please visit our new, non-denominational Development Site and kick the tires. The objective is to create applications that can run on any of the FreePBX-based Asterisk distributions. So, while we’re a little biased, you don’t have to be to join in on the fun. Just click the Register link at the top of the form. Welcome!!!

Other Coming Attractions. Well, we got distracted again this week because CallerID Superfecta 2.0 was such as terrific new product. We’ll wrap up the Orgasmatron Installer tutorial in our next column. Stay tuned!

Security Alert. Secunia has published some security vulnerabilities in FreePBX. Upgrade all of your FreePBX modules at your earliest convenience.

Twitter Magic. If you haven’t noticed the right margin of Nerd Vittles lately, we’ve added a new link to our Twitter feed. If you explore a little, you’ll discover that the user interface now brings you instant access to every Twitter feed from the convenience of the Nerd Vittles desktop. Enjoy!

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. Looks great. Should be noted that you will need to have mod_auth_mysql installed in order for this to work though!

  2. Under PBIAF v1.2 enabling this on the inbound route causes all extensions to report caller is on the line & drop to voicemail – disabling returns to normal.

    Any ideas why? Is the apache mod listed above something built-in to PBIAF v1.3+ that us laggerds are missing (even if we’ve done the updates from the command line)?

    Thanks, slick little toy!


    [WM: Try deleting /var/www/html/admin/modules/superfecta/bin/.htaccess. It’s not necessary.]

  3. Since the asterisk phonebook is the first on the list, is there an easy way to get numbers into it without having to retype them? Say a new number calls me, it doesn’t find the number in the phonebook, but then does find it in the White Pages. It’d be convenient if maybe the reports page had a link to click to add to the phonebook.

  4. thanks a lot for your great work!

    im located in switzerland and using trixboxCE.
    superfecta doesn’t work on my system! i have activated asterisk phonebook and asteridex4.

    when a call arrives nothing will be displayed. just an empty screen!
    if i test a number agaist the sources the outout will be korrect.

    any idea?
    regards remo

    [WM: Visit the PBX in a Flash forum. That’s the best place to get first-class, free tech support.]

  5. Off topic: Is the Atomic Flash: 15-Minute Turnkey Asterisk Install still available?

    [WM: We have about a half dozen of the second wave left under the same donation offer as originally outlined.]

  6. Off topic again: I am thinking of using PIAF in our office but our DSL upspeed is not so great (250). I am considering T1 because the price is very close to cable, but I am not sure if I need a special card for T1 (I am also considering using an atom notebook, but I don’t have to). The T1 will come in and go to a router with cat 5 or cat 6 cables out, so I don’t see why I would need a special card, but there seems to be some indication I might.

    Thanks for your help. I tried searching on the forum but it wouldn’t let me search T1, had to be longer than 2 letters search.

    [WM: 2-letter searches are easily accomplished on Google: T1 site:pbxinaflash.com 🙂 ]

  7. Help? I tried to order through making a paypal donation: The Atomic Flash: 15-Minute Turnkey Asterisk Install.

    But received this message. The seller requires confirmed address, please add credit card below, but there was no form to input anything. In addition I am fairly sure my address is already confirmed.

    [WM: Try this link.]

  8. This thing is driving me nutso. Have mod_auth_mysql installed and enabled but still not working right. I get the password box but won’t authenticate. If I change the mysql server to something fictional in .htaccess I get the same thing so tells me it isn’t even making it to the database. This in on Ubuntu 7.10. HELLLP!

    [WM: Head to the forums. Hard to do tech support on a blog.]

  9. This article, along with the previous ODBC connectivity article got me to thinking about the requirements to connect pbx-in-a-flash to http://www.CiviCRM.org (which can run well within Drupal, and the sum is worth more than parts; I’m a developer, under-employed too btw if you care to leave a comment). But I didn’t have to think too long or hard, because google brought me to this CallerID CRM-Db related article: http://www.voiceingov.org/blog/?p=544

    And for extra credit, the author added this about incoming call PC-screen pop-up displays: http://www.voiceingov.org/blog/?p=326

    For easy dialling from within CiviCRM, just follow the instructions in this article: http://nerdvittles.com/?p=234

    Just thought I’d pass along what I found. Thanks folks! I’m excited to get this working now.

    (civicrm is very mature, and has enjoyed well-funded development, because the political parties use it a lot. Imagine how CiviCRM scales, just imagine. Try the demo on civicrm’s site too)

  10. I found that paying attention to this paragraph was the resolution to about 4 days of head scratching over this ABSOLUTELY WONDERFUL GODSEND of a module (yes I realize I’m yelling, that’s how happy I am to have this finally installed and working):

    Once you’re satisfied with your lookup sources and the search order, the only remaining step is to designate CID Superfecta as the CallerID lookup source in your inbound routes. For each inbound route on which you want CallerID lookups performed, click Admin, Setup, Inbound Routes and choose the desired route from the column of routes on the right margin. Scroll to the CID Lookup Source section of the form and choose CID Superfecta from the dropdown box. Click Submit, Apply Config Changes, Continue to save your entry.

  11. I set this all up .. went very smooth. For me in the US here and using the recommended sources it doesnt find and names for not matter what number I try in the debug

  12. The format returned by whitepages.com has been heavily modified since the module was last updated. I’m currently hacking together a replacement. A better plan would be to register the app with whitepages.com and use the API so that XML results can be returned and parsed.

  13. This thing works GREAT! I can now have the servver send names or even nicknames I give my frends and family if the phoneset loses its memory. I set it to pull up originally from other databases, then if I want to add them to my asterisk phonebook, I do that with the name that I know them by or a nickname. I really like this programme.

Comments are closed.