How to use xMatters API inside of Inbound Integration

Not Yet Reviewed

Hi Travis and team

Related to this article 

How can I use the REST API within an inbound integration script to retrieve data so that I can push it back to a user.

Example:  As a hipchat user I'd like to use my slash command for something like /xm_config OnCall and get back a list of the folks who are on call today or this week.





Date Votes

Please sign in to leave a comment.


    Hello again Kirk! Lemme dig into this and get back to you. 

  • Hey Kirk,

       Ok, so I think it is better to add a new slash command because otherwise parsing out the OnCall and the group was getting hairy.

    So, we'll create a new slash command, and you can enter this:

    /xm_oncall Group Name

    To get the on call schedule for the group "Group Name". 

    To set this all up:

    1. Cruise over to xMatters and create a new Inbound Integration and select "Run a script". Copy the script below and paste it into the integration script. (You can remove the template script that is there.)
    2. Copy the Integration Url and note it for later. 
    3. Cruise over to Hipchat and create a new slash command for `xm_oncall` and in the "We will POST to this URL" paste in the url from step 2. 

    The script below uses the "Hipchat" endpoint, but depending on your set up, we might need to create a new endpoint. 

    There could definitely be improvements to how the schedules are displayed, so feel free to tweak as needed. There is more data we could display, it just depends on exactly what you want to see. 

    The script:

    // If your data is posted as JSON
    hipchatData = JSON.parse( request.body );

    // Parse the text from the user. Everything after the slash
    // command will be the group name.
    var re = new RegExp( /\/xm_oncall (.*)/ );
    var match = re.exec( hipchatData.item.message.message );

    // If they didn't put a group in then exit
    var groupName = '';
    if( match.length === 0 ) {
    console.log( "No group entered. Exiting" );

    groupName = match[1];

    var getOnCall = http.request({
    'endpoint': 'xMatters',
    'method': 'GET',
    'path': '/api/xm/1/groups/' + groupName + '/calendar'

    // Submit the request and capture the response
    var response = getOnCall.write();
    var calendarData = JSON.parse( response.body );

    buildMsg( calendarData, groupName );

    * buildMsg - Build the message to send to hipchat
    * calendarData - The result of a GET to /groups/GROUPNAME/calendar
    * groupName - The name of the group we got the schedule for
    function buildMsg( calendarData, groupName ) {

    var data =;
    var msg = 'On call schedule for ' + groupName + '<br/>';
    var getShift;

    // Loop through each item in data and
    // retrieve the rest of the details from
    // the shift.
    for( var d in data ) {

    getShift = http.request({
    'endpoint': 'xMatters',
    'method': 'GET',
    'path': data[d].shift.links.self

    shiftResponse = getShift.write();
    shift = JSON.parse( shiftResponse.body );

    msg += '&nbsp;&nbsp;Shift ' + + '. Start ' + data[d].start + '. End: ' + data[d].end + '<br/>';
    msg += '&nbsp;&nbsp;&nbsp;&nbsp;Members: <br/>';

    members = data[d];
    for( var m in members ) {
    msg += '&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;' + members[m].position + ':' +
    members[m].member.firstName + ' ' + members[m].member.lastName + ' (' + members[m].member.targetName + ') delay: ' + members[m].delay + '<br/>';

    console.log( 'MSG: ' + msg );
    sendToHipchat( msg );



    * sendToHipchat - send a message to hipchat
    * msg - The text to send
    function sendToHipchat( msg ) {

    // Prepare the HTTP request
    var request = http.request({
    'endpoint': 'Hipchat',
    'method': 'POST',
    'headers': {
    'Content-Type': 'application/json'

    var color = "gray";

    var payload = {
    "message": msg,
    "message_format": "html",
    "color": color,
    "notify": false

    // Submit the request and capture the response
    var response = request.write( payload );


  • Hi Travis,

    That works with one caveat:  The hipchat user doing the request must have 'Full Access User' role added.  Otherwise you get an access error.



  • Bah. Good catch. We are working on coming out with a new Web Services User role that will help allieviate those kinds of things. 

    Glad it worked for you though! 

    I hope you don't mind, but I wrote this up as my latest GIG article. Check it out: 


Didn't find what you were looking for?

New post