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
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.
|Rooms API||The most commonly used API: manage rooms and room history, manage members, upload files, post messages/notifications, manage webhooks, etc.|
|Capabilities API||Retrieve capabilities for an integration|
|Emoticons API||Retrieve information about emoticons installed in a group|
|Groups API||Retrieve information about a group: avatars, statistics, etc.|
|Imports API||Import room history, private chat history, etc. The imports API is only made available to specific integrations, you can request access by contacting email@example.com|
|Integrations API||Utility API to manage integration links|
|Invites API||Invite users to a group|
|OAuth Sessions API||Create and manage sessions|
|Users API||Manage users|
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.