Getting Started

Would you rather build some code?

Once you understand the concepts, follow one of the Tutorials to get started.

And if you have any questions or suggestions, contact us on The Ecosystem Developer Portal

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:

Learn more

 HipChat REST API

Cards 

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

Examples of Cards:

Learn more

Sending Sending Messages

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. 

Learn more

 Webhooks

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. 

API Description
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 integrations@hipchat.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 

Learn more

 HipChat REST API

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

 

 

Learn more

Working with Glances

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)

Learn more

Extending the Sidebar

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". 

Learn more

Opening a Dialog

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.

Learn more

Contributing Actions

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.

Learn more

Installation flow

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: 

Learn more

Configuration Page

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. 

Learn more

Listing an add-on

 

 

 

 

 

Was this page helpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport