Installation flow

If you are using one of the HipChat libraries supported by the HipChat team, the installation flow is taken care of for you.

The HipChat API treats the installation of integrations/add-ons differently to other chat applications: instead of having one OAuth client/shared secret for the add-on that works across all installations, HipChat creates one OAuth client per installation.

General concepts

Global versus room installations

A HipChat group represents a team in HipChat, for example in HipChat Cloud, the following represent 2 HipChat groups:

Each 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. It can be installed in multiple rooms in the same group (each installation will be a different OAuth client)

One OAuth client per installation

Anytime your add-on is installed by a user, HipChat creates an OAuth client, and sends information about the installation to your add-on via the method you declared in the "installable" section of the capability descriptor. You need to save this information, as it will be required to make calls to the HipChat REST API.

1
2
{ oauthId: 'cba74fbc-1b26-407e-811d-b9e377e4c440',
  capabilitiesUrl: 'https://api.hipchat.com/v2/capabilities',
  roomId: 100,
  groupId: 1,
  oauthSecret: 'NothWQ2HtSdsidQKxxxmMUzsACNzPSR' }

oauthId: OAuth client ID
oauthSecret: OAuth shared secret
roomId (optional, for room installations only): ID for the room the add-on was installed in
groupId: ID for the HipChat group the add-on was installed in
capabilitiesUrl: URL for a capabilities document which lists the URL for endpoints you can use to make REST calls to this installation

The following sections provide more details on how to implement the installation process:

Installation triggers

The installation of an add-on can be triggered:

In the HipChat administration screen for integrations, from a listing in the Atlassian Marketplace or a descriptor URL
From your application, by redirecting the user to HipChat

Learn more

Installation triggers

Installation process

Once the installation is triggered, the following installation flows are available:

Installation flow	Description
Server-side installation	This is the most commonly used installation flow. Once the installation is completed in HipChat, HipChat makes a REST POST to your add-on containing the installation and security context for the tenant. This installation flow works well when HipChat can contact your add-on, for example if it is a publicly available service.
Client-side installation	If your add-on is hosted in an application behind a firewall, HipChat cannot contact your add-on directly to send the installation and security context for the tenant. In this case, you need to implement the client-side installation flow: post installation, HipChat redirects the user's browser to your application, with information about how to retrieve the installation and security context.

Server-side installation

This is the most commonly used installation flow.

Once the installation is completed in HipChat, HipChat makes a REST POST to your add-on containing the installation and security context for the tenant.

This installation flow works well when HipChat can contact your add-on, for example if it is a publicly available service.

Client-side installation

If your add-on is hosted in an application behind a firewall, HipChat cannot contact your add-on directly to send the installation and security context for the tenant.

In this case, you need to implement the client-side installation flow: post installation, HipChat redirects the user's browser to your application, with information about how to retrieve the installation and security context.

Learn more

Server-side installation

Client-side installation