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!


4 thoughts on “Screen Pops with Asterisk and XMPP

  1. I will say that one major difference between doing screen pops in CCXML (via Prophecy) and doing them in Asterisk is that in CCXML I can issue the HTTP request that will launch my screen pop asynchronously from the logic that handles the incoming call.

    The logic that handles the incoming call is not blocked while waiting for the outcome of the screen pop (in fact, it doesn’t care one bit about the outcome of the screen pop).

    In Asterisk, dial plan commands are executed in order (according to a priority). This could be a problem if the AGI script that is invoked to launch the screen pop gets hung. I don’t want the logic that handles the inbound call to be stopped just because something goes wrong with the screen pop — the screen pop is nice to have, but the inbound call is probably more important.

    One thing I could do is run the AGI script in the background:

    curl http://ip_address_to_your_web_server/screen_pop.php?ani=“$1” &

    This should keep it from hanging the logic handling the rest of the inbound call. I’m not really sure this will achieve the same level of “asynchronousity” that I have in CCXML but it’s probably nor a bad thing to do anyway.

  2. In the latest versions of Asterisk (notably in 1.6 but I think this app in 1.4) there is a command that will natively transmit XMPP messages from within the dialplan. I’ve never seen it block, though I suppose it is possible. Typically I get my messages sent in un-noticably short delays to my XMPP server.

    I created a “dummy” user called “phonebot” on my jabber server, and then set it up in jabber.conf. Now, I can send messages from that account to any user I want, based on call events coming into the system. Here’s a three line example that notifies my primary XMPP account with the caller ID name and number and timestamp of when calls come in. It’s quite simple, and really useful for knowing what’s going on in the system.

    exten => 6083,1,JabberSend(phonebot,,”6083: Incoming call from ${CALLERID(all)} at ${STRFTIME(${EPOCH},GMT+8,%B %d %X Pacific)}”)
    exten => 6083,n,Dial(SIP/2001&SIP/2003,25)
    exten => 6083,n,Hangup

    Last note: there is a branch in TRUNK right now that allows inbound messages to be sent to Asterisk systems, so the communication can be bi-directional. One of our clever community members (Philippe Sultan) is working on more sophisticated XMPP interactions with Asterisk. See or for details and you can test it out.

  3. Thanks, John! That’s a great tip. I’m currently running — I’m going to play around with this a bit and see if I can get it working. (If I can’t, I might upgrade to 1.6.)

    I can still see some instances where using a custom AGI script to act as the “go between” for Asterisk and my XMPP server might still make sense.

    For example, if I wanted to do a lookup in a data source using the caller’s ANI — i.e., to query a database or do a lookup in a CRM system — and then add the details to my screen pop, I still might need to go outside the dialplan to do that.

    Not sure if there is a way to do something like that from within the dialplan itself. If anyone knows of a way to do this, please feel free to leave the details in a comment.

  4. Pingback: ….::: VOX POPULI :::…. » Blog Archive » Customizing Caller ID with CiviCRM and trixbox

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s