Integrating with Hipchat

HipChat Connect is HipChat's API that lets you build add-ons extending the HipChat apps. It is based on the same Atlassian Connect framework you already use to build add-ons for JIRA, Confluence, and Bitbucket. You can build HipChat add-ons in any language, and run them on any platform: all you need is for your add-on to talk to HipChat over open Web protocols (HTTPS, REST, OAuth, JWT).

Using HipChat Connect, your add-on can:

Send notification messages to HipChat rooms

An add-on sends notification messages to HipChat rooms to notify users of important events, using the HipChat REST API.

When sending a notification message, you can send the following type of messages:

Plain text, custom HTML

For example:

Cards

Your add-on sends data in a specific JSON format, HipChat displays it as a Card.

Examples of Cards:

Listen to HipChat events via webhooks

Add-ons can listen to HipChat events via Webhooks, for example to take action when a message is posted into a room, a users enters or exits a room, or the room topic is changed. The most common use case is for add-ons to watch messages in HipChat rooms for particular regex patterns:

• Slash commands, which is a way for power users to use HipChat as a command centre:

  

• Handle the rendering of links/objects. For example the JIRA integration provides more details about JIRA issues when a link to an issue is pasted into a room:

  

• Watch conversations for particular patterns and offer suggestions / images in response. 

Call the HipChat REST API

Add-ons can make calls to the HipChat REST API, for example to create a room, access a room's message history, post a message, or register to a Webhook. 

Add status to HipChat rooms via Glances

Glances are a means of displaying important information about an integration to a HipChat room. They are useful to show aggregate information and to prevent spamming a room with a million separate messages. This is the one place where the team goes to figure out a status for what is connected to the room, e.g.

• There are 5 open pull requests for projects the team in this room is working on
• There are 3 open incidents
• There are 2 blocker bugs impacting the current sprint
• The project you're working on has been mentioned 50 times in Twitter in the past hour

 

Add custom Views to the HipChat sidebar 

Add-ons can contribute custom HTML Views inside the HipChat sidebar. It is typically used to:

• Display a list of important objects (e.g. the list of open incidents currently managed by this room's team members)
• Display more information about an object (e.g. more detail about an incident which was sent to the room as a HipChat Card).
• Allow users to take specialised actions (e.g. acknowledge an incident)

Open a custom modal dialog in HipChat 

Add-ons can contribute Views in HipChat modal Dialogs. Dialogs are typically used for interrupt flows, e.g. "select and post a meme". 

Add custom actions to HipChat 

Your add-on can contribute specialised actions in multiple locations in HipChat. These actions can be used by users to act on rooms, messages, or objects.

Be installed globally or in specific rooms

You can make your add-on installable by end users in a room, globally, or both. 

• A global add-on is installed in every room by default. 
• A room add-on is installed on a per-room basis

Users can install your add-on by finding it and configuring it in the HipChat administration pages.

Expose configuration pages in HipChat

An add-on can expose a configuration page in the HipChat administration section, so users can configure the add-on in the context of the room/team they have installed it. For example, users can watch Tweets matching specific search terms in a HipChat room using a configuration page exposed by the Twitter integration: 

Be registered in the Atlassian Marketplace

An add-on can be registered in the Atlassian Marketplace. This makes it available to all HipChat users. 

With over 2000 add-ons, the Atlassian Marketplace is the place to get noticed. Marketplace lists add-ons for JIRA, Confluence, Bitbucket and HipChat.