Sending call notifications from Asterisk to HipChat

We run an Asterisk PBX with agents who take inbound phone calls from our various phone queues. We also use HipChat as our internal instant messaging and group chat system.

So that agents are aware a call may be headed their way, we have a room within HipChat where call notifications are sent automatically. They look like this:

To get started with this you will need:

• A functioning Asterisk PBX with access to install AGI scripts
• A functioning HipChat installation with administrative access
• PHPAGI installed and configured

Step 1- Setup HipChat

First you need to configure an integration within HipChat. This will provide you with an API endpoint and credentials that you’ll need in step 2.

From the HipChat web interface you need to select Integrations on the top menu and then Build your own integration.

Once done you need to select the room where notifications will be sent and a name for your integration. The name will appear as part of the notification so choose carefully.

The final step will show the API details. You’ll need to make note of the notification URL as you’ll need this in step 2

Click save and that’s the end of step 1.

Step 2 - Setup your AGI script

As mentioned in the pre-requisites you should have PHPAGI installed and configured. You’ll need to create an AGI script like the following. On my system this has been set to ==/var/lib/asterisk/agi-bin/hipchatnotify.php==.

You’ll need to replace YOURURL with the notification URL provided in step 1. You probably want to change the “From” field too, otherwise it’ll display “Ewing IT PBX”.

You may also notice a timeout of 3 seconds. This is to ensure that a timeout connecting to the HipChat API doesn’t prevent your calls from progressing.

Save and move on to step 3!

#!/usr/bin/env php
<?php
require 'phpagi.php';
$agi = new AGI();

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'YOURURL');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Create body
$body = array(
  "message" => "Incoming Call to ".$argv[1]." from ".$agi->request[agi_calleridname]." ".$agi->request[agi_callerid],
  "notify" => "1",
  "from" => "Ewing IT PBX",
  );
$body = http_build_query($body);

// Set body
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_TIMEOUT, 3);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);

// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

?>

Step 3 - Setup your dial plan

How you do this exactly will depend on your system setup, however you’ll need to insert a call to the AGI script before the call enters your queue.

A very basic example on extension 1501 might look like this:

exten => 1501,1,AGI(hipchatnotify.php,Support)
exten => 1501,2,Queue(yourqueue|tT|||300)

You’ll note that I have included “Support” as a parameter. This is so that the notification shows where the call is going and you could put arbitrary text here.

Step 4 - You’re done

Once you’ve done these steps and reloaded the system try a test call. If everything is working correctly, you should receive a notification in your room like this:

Did this work for you? Let me know how you went in the comments below!