Customizing Caller ID with CiviCRM and trixbox

Recently, I had an opportunity to set up a CiviCRM site for a client to use to track contributors.

I think CiviCRM is a great piece of software that can be enormously useful to non-profit organizations, and I’m actually surprised that more don’t opt to use it. It’s powerful, robust, extensible and open source.

The site I set up is running a Red Hat-based LAMP stack with Drupal, CiviCRM and the CiviContribute module. I have the same set up mirrored in a local development environment that lets me test tweaks and upgrades to the site before they get pushed out into production. I also have an instance of trixbox CE running locally, and I decided to try and see if I could set up a trixbox PBX that uses CiviCRM as the data source for looking up caller information on inbound calls. This way, if a non-profit is using both CiviCRM and trixbox they could set their PBX to look up information about clients, donors, volunteers, etc. that call their offices and display this information in either a SIP client or in a screen pop.

The process of setting up trixbox to use CiviCRM as the data source for caller ID lookups couldn’t be easier (note, I used these steps on trixbox version

  1. Log into your trixbox and enter admin mode.
  2. From the toolbar, select PBX >> PBX Settings.
  3. From the FreePBX left-hand side menu (under “Inbound Call Control”), select CallerID Lookup Sources
  4. In the section entitled “Add Source”, enter the Source Description (CiviCRM), and Source Type (MySQL). Using Cache Results will cache the CID lookup in AstDB. Depending on your own set up, you may or may not feel the need to enable this setting.
  5. In the section entitled “MySQL” (appears after you designate the Source Type), enter the Host, Database, Username and Password to access your CiviCRM database.
  6. The section entitled Query is where you will enter the SQL query that will return the information you want to display about on incoming calls. I used the following SQL (you can modify this as you like to alter your display information – note, the special token ‘[NUMBER]’ is replaced with the caller ID of the incoming call):

  7. SELECT CONCAT('CiviCRM: ',display_name) FROM civicrm_contact WHERE id = (SELECT id FROM civicrm_phone WHERE REPLACE(phone, '-', '') = SUBSTRING('[NUMBER]',-10))

  8. Click Submit Changes.
  9. Navigate to Inbound Routes (also under the “Inbound Call Control” section of the FreePBX menu).
  10. Select the route that you would like to use CiviCRM as the data source for.
  11. In the section entitled “CID Lookup Source”, select CiviCRM from the drop down menu.
  12. Click Submit.
  13. Scroll to the top of the page and click on the orange bar that says Apply Configuration Changes and reload the settings.

Thats it!

Now on an inbound call, the name of the CiviCRM contributor in the format CiviCRM: John Doe is displayed in my SIP client whenever a successful lookup occurs. There are all sorts of options that can now be used to display the caller information to non-profit staff, send a screen pop, route the call to a specific destination, etc.

CiviCRM and trixbox are a potent combination. I hope this brief explanation of how to use the two together gets more non-profits excited about using them.


Screen Pops with Asterisk and XMPP

A few weeks ago, I wrote a post on using CCXML and PHP to do screen pops with the Voxeo Prophecy platform. The task was made incredibly easy with a nifty PHP class library designed specifically to interact with XMPP servers.

After getting screen pops working in Prophecy, I decided to try my hand at getting them to work in Asterisk (this is, after all, how the majority of phone calls to me are handled). It turns out, the PHP script I developed to do screen pops in Prophecy can be reused to do the very same thing in Asterisk. If you’d like to give this a try on your own, here is what you will need:

  1. A working Asterisk instance. (This example assumes you know how to modify Asterisk config files.)
  2. A copy of the very cool XMPPHP library from Google Code. (This example assumes that the PHP code used to interact with XMPP servers is running on a separate server than the one housing Asterisk. More on this below.)
  3. An XMPP server and a client, or simply use your Google account.

There are three components to this example. First, you’ll need a PHP script to interact with an XMPP server. You can use the same script employed in my previous screen pop example:

$conn->message('', 'You are receiving a call from: $ani');

Next, you’ll need a simple AGI script for Asterisk to interact with. This script will send an HTTP request to the PHP script above:

# Contents of screen_pop.agi
# It don't get any easier than this...
curl http://ip_address_to_your_web_server/screen_pop.php?ani="$1"

On your Asterisk server, place this script in /var/lib/asterisk/agi-bin/ and ensure that it is executable. You’ll need to specify the IP address to the server running this script. Note — there isn’t any reason that these two scripts can’t run on the same machine (you can run PHP scripts on an Asterisk server), or even be consolidated into one single script (just make sure to include the XMPPHP library). In fact, you could even run the XMPP server used to send screen pops on the same machine running Asterisk.

The mechanics of this specific example were influenced by the set up for my previous screen pop example, and I am (at heart) a lazy basterd. But I digress…

The last piece to be put in place is to modify extensions.conf to ensure that our AGI script is invoked. You’ll want to add something like the following to the appropriate dial plan context (your specific Asterisk set up will influence this heavily):

exten => 123,1,AGI(screen_pop.agi|${CALLERID(num)})

This will pass the caller ID to our AGI script, which will then invoke the PHP script and send the details of the call to the XMPP account of our choice. I’ve noticed in practice that adding this to my dial plan causes the IM to be sent to my Google Talk account a good 2-3 seconds before the phone rings. Plenty of time to give someone a heads up about who is on the other end of an incoming call.

Obviously there are lots of options for looking up information on the caller, once you have their caller ID, that you can use to augment the information in your screen pop.

Just goes to show you, there isn’t much you can’t do with open source / open standards.

Viva screen pop!