xMatters Connect app for Hipchat

The information in this article is the intellectual property of xMatters and is intended only for use with xMatters products by xMatters customers and their employees. Further, this intellectual property is proprietary and must not be reused or resold.



Configure xMatters

Configure HipChat

Test the integration


Download resources


This article provides installation, configuration, and implementation details when integrating xMatters On-Demand with Hipchat Cloud or On-Premise.

This integration between xMatters and Hipchat:

  • Allows a user to invite an xMatters on-call resource to a HipChat room.

How it works

This integration installs an xMatters add-on into your Hipchat account that automatically targets the xMatters connect application to pass information to the inbound integration.

Invite to room

Using the "+" button in a Hipchat room, a user can launch a dialog to target an xMatters user or a group and invite them to the room to deliver some text.  

Configure xMatters

The first step in setting up this integration is to configure xMatters.

Download the communication plan

To begin, download the communication plan attached to this article to a location on your local machine. You do not need to extract the contents.

Create an integration user

This integration requires a user who can authenticate REST web service calls when injecting events.

This user needs to be able to work with events, but does not need to update administrative settings. While you can use the default Company Supervisor role to authenticate REST web service calls, the best method is to create a user specifically for this integration with a dedicated "REST Web Service User" role that includes the permissions and capabilities.

Note: If you are installing this integration into an xMatters trial instance, you don't need to create a new user. Instead, locate the "Integration User" sample user that was automatically configured with the REST Web Service User role when your instance was created and assign them a new password. You can then skip ahead to the next section.

To create an integration user:

  1. Log in to the target xMatters system.
  2. On the Users tab, click Add.
  3. Enter the appropriate information for your new user. Because this user affects how messages appear for recipients and how events are displayed in the reports and Communication Center, you may want to identify the user as specific to Hipchat; for example:
    • First Name: Hipchat
    • Last Name: Integration
    • User ID: hipchat
  4. Assign the user to the REST Web Service User role.
  5. Make a note of the user credentials and details – you need them when configuring other parts of this integration.

Create users and groups to target

You can target users directly from an issue or supply a default recipients. 

You can create multiple groups and users at once using the EPIC feature. 

Import the communication plan

The next step is to import the communication plan.

To import the communication plan:

  1. In the target xMatters system, on the Developer tab, click Import Plan.
  2. Click Choose File, and then locate the downloaded communication plan (.zip file).
  3. Click Import Plan.
  4. Click the Edit drop-down list for the plan, and select Access Permissions.
  5. Add the integration user you created above, and then click Save Changes.
  6. In the Edit drop-down list, select Forms.
  7. For the Invite to Room form, click Web UI, Web Service drop-down list, click Sender Permissions.
  8. Enter the integration user you created above, and then click Save Changes.

Configure the inbound integration

You need to configure the authentication and retrieve the URLs for the inbound integration to configure Hipchat.

To configure an inbound integration:

  1. In the Integration Builder, expand the list of inbound integrations.
  2. Click the Invite to room integration to view its details.
  3. Under the Select authentication method step, select Basic Authentication from the drop-down list.
  4. Click Update Inbound Integration.
  5. Scroll down to the bottom of the page, and click Copy URL beside the field:


Configure Hipchat

Install the add-on

You can now configure Hipchat to integrate with xMatters.

To install the xMatters add-on in Hipchat:

  1. Log in to Hipchat as an administrator and navigate to the Integrations tab. 
  2. Scroll to the bottom, find xMatters, then click Install
  3. In the Install Integration dialog, select the room to install to, or select Global to make available to all rooms. Click Continue
  4. Review the actions xMatters will perform and click Approve

Configure the add-on

  1. On the xMatters Integration screen, select the Configure tab if it isn't already displayed.
  2. Enter the xMatters hostname and the username and password of the integration user created above.
  3. Click Test Authentication to verify the credentials are correct. 
    • After successfully validating the credentials, a new text box appears for the Invite to Room URL.
  4. Paste in the Invite to room inbound integration URL and click Save Settings


Test the integration

  1. To test the Invite to room function, open HipChat and navigate to the room selected for the xMatters integration to be installed to.
  2. Click the "+" button next to the chat window and select xMatters Invite To Room.
    • The first time the integration is used in a room, the dialog asks for authorization to allow the integration into the room. Click Authorize xMatters Integration.


    • An admin screen to confirm account access to the xMatters Integration is displayed. Click Grant access to xMatters Integration.


  1. After that, back in the room, the xMatters Invite to Room dialog is displayed. Type in the xMatters Recipient box to do a lookup of the xMatters account and retrieve Groups or Users in real-time.
  2. Enter a description and click Send Invite.


  1. On receiving the notification, click (or tap) Accept


The response is reflected in the Hipchat room:



General Troubleshooting

If the request successfully makes it to xMatters, then the Activity Stream for each of the inbound or outbound integrations is the best resource for troubleshooting.

Download resources


Have more questions? Submit a request


Please sign in to leave a comment.
Powered by Zendesk