Add-on capability descriptor
An add-on must expose an HTTP-accessible "capabilities descriptor", a JSON document that describes the add-on and what its capabilities are. For example, here is a simplified descriptor for an add-on that wants to be able to call the HipChat REST API to send notification messages.
The content of this descriptor depends on how your add-on plans to extend HipChat. At a bare minimum, you need to declare the following capabilities:
- installable: to make sure your add-on can be installed by users
- hipchatApiConsumer: to make sure your add-on can call the HipChat REST API (with a number of security scopes)
HipChat add-on installations
A HipChat group represents a team in HipChat, for example in HipChat Cloud:
Each team/group has its own user base, rooms, configuration, etc.
You can choose for your add-on to be installable by users globally for their HipChat group, on a per-room basis, or both.
- If the add-on is installed globally, it works in all rooms in the HipChat group
- If the add-on is installed in a HipChat room, it only works in this room.
Anytime your add-on is installed by a user, and the user accepts the security scopes, HipChat creates an OAuth client / shared secret, and sends it to your add-on via a REST endpoint you declared in your add-on capability descriptor.
Integrate with, and extend HipChat
Once installed, add-ons have access to the full features of the HipChat API. For more information, read the sections below:
|Foundation||HipChat REST API||
Explains how to make calls to the HipChat REST API, and in particular:
|JWT token||Explains how JWT (JSON Web Tokens) are used for HipChat to send signed contextual information to your add-on for each call, and how to make use of it|
|Integrating with HipChat via messages||Sending Messages||Explains in more details how to send messages to HipChat using the REST API|
|Webhooks||Explains how to use webhooks to listen and respond to messages in HipChat rooms, e.g. to implement slash commands|
|Extending the HipChat Apps||Glances||Explains how to add a status glance to the HipChat right sidebar (e.g. "5 tasks")|
Explains how to add actions to HipChat messages and HipChat rooms (e.g. "create a task"). Actions can:
|Dialog||Explains how to add a custom dialog in the HipChat App, and load HTML/JS/CSS from your add-on|
|Sidebar||Explains how to add a custom sidebar in the HipChat App, and load HTML/JS/CSS from your add-on|
|Configuration Page||Explains how to add a custom configuration page for your add-on in the HipChat administration page, and load HTML/JS/CSS from your add-on|
List your add-on in HipChat
Once your add-on is ready, you can make it available to all HipChat users by listing it in the Atlassian Marketplace. Just follow instructions from Listing an add-on.
Other ways to create a simple add-on
There are simpler (albeit more limited) ways you can build an add-on with HipChat today:
To make things even easier, we have built a simple wizard to build an add-on that can send notification messages to a room, and listen to a slash command.
You can access this wizard from the HipChat administration screen for integrations.
Using this method, you can quickly build an add-on that allows you to send notifications to a HipChat room.
To install your add-on in a room, users have to generate tokens from the HipChat web administration screens and paste them in your application, as demonstrated in this video:
In your application, you need to ask users:
- For a token that users generate in HipChat
- For a room ID, which they also get from HipChat, so you know where to post the notification messages
- If you plan to support HipChat Server, you should also ask users for the base URL of their HipChat instance, e.g. myhipchat.company.com. Note: your integration will only work if the HipChat instance is addressable. If it is protected by a firewall without inbound access, it won't work. Make sure to highlight that in your documentation/troubleshooting guide.
You can then use these tokens to post notifications to the room the add-on was installed in, using the send_notification REST endpoint:
HipChat currently supports plain text and HTML notifications (the HTML is curated).
Depending on what method you choose, parts of the API are available to your add-on:
Add-on built using the build-your-own wizard
|Install the integration in a room|
|Install the integration globally|
Send notification messages to HipChat rooms
|Use the HipChat REST API|
|Listen to events via Webhooks||Partial: only one "slash command"|
|Expose configuration pages in HipChat|
|Listing your add-on in the Atlassian Marketplace|
|Support HipChat Cloud and HipChat Server|