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

Advanced Setup

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 a REST API user

This integration requires a REST API user to authenticate REST web service calls when injecting events.

This user needs to be able to work with events, but not update administrative settings. The best way to create a user for this integration is to use the "REST Web Service User" role that includes the permissions and capabilities. (If this role does not exist in your deployment, contact your Client Success Manager to have it enabled.)

To create a REST API user:

  1. Log in to the target xMatters system.
  2. On the Users tab, click the Add New User icon.
  3. Enter the appropriate information for your new user. Because this user will affect how messages appear for recipients and how events will be 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. In the Roles area, add the REST Web Service User role.
  5. Click Save.
  6. On the next page, set the web login ID and password. 
Make a note of these details; you will need them when configuring other parts of this integration.

Create users and groups

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

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 Browse, and then locate the downloaded HipChatConnect-CommPlan.zip file.
  3. Click Import Plan.
  4. On the communication plan has been imported, in the Edit drop-down list, select Forms.
  5. In the Web UI and Web Service drop-down list, click Sender Permissions.
  6. Enter the REST API user you created above, and then click Save Changes.

Access integration URLs

The web service calls from HipChat are sent to inbound integration endpoints. These can be found by expanding the list of inbound integrations in the Integration Builder. Click the gear icon next to each integration, and then select Integration URL. Copy the URL displayed in the Integration URL dialog box.

When configuring HipChat, you will need the URL for the Invite to room inbound integration.

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

On the xMatters Integration screen, select the Configure tab if it isn't already displayed. Enter the xMatters hostname and the username and password of the HipChat user created above. 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. Paste in the Invite to room inbound integration URL and click Save Settings




Test the integration

To test the Invite to room function, open HipChat and navigate to the room selected for the xMatters integration to be installed to. 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.


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. Enter a description and click Send Invite.



On receiving the notification, click (or tap) Accept

The response will be 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.

Advanced Setup


Download resources


Have more questions? Submit a request


Please sign in to leave a comment.
Powered by Zendesk