Client-side installation

At a high level:

• An add-on installation is triggered, either from HipChat, or from your application (see Installation triggers)
• Once the add-on is installed in HipChat, HipChat redirects the user back to your application - to a URL you provide in the descriptor
• Your add-on can then fetch an OAuth ID and OAuth secret from HipChat
• And the rest is just the standard OAuth2 client credentials flow

Add-on descriptor

You need a descriptor to install your add-on in HipChat.

Example:

1
2
{
  "description": "description of your add-on", 
  "key": "your-addon-key", 
  "name": "Your addon name", 
  "vendor": {
    "name": "Your company name", 
    "url": "https://www.your-company.com"
  }
  "links": {
    "self": "https://your-addon-url/descriptor-url"
  }, 
  "capabilities": {
    "hipchatApiConsumer": {
      "scopes": [
        "send_notification"
      ]
    }, 
    "installable": {
      "allowGlobal": false, 
      "allowRoom": true, 
      "installedUrl": "https://your-addon-url/installed",
      "updatedUrl": "https://your-addon-url/updated"
    }
}

• description: description of your add-on, will be shown to users when they install your integration
• key: has to uniquely identify your add-on
• links/self: link to the descriptor document
• name: name of your add-on, will be shown to users when they install your integration
• vendor: description about your company (will also be shown to users)
• capabilities/hipchatApiConsumer/scopes: list of security scopes you need, which will dictate what REST APIs your add-on can call, as described in www.hipchat.com/docs/apiv2/auth
• installable: information about where/how the add-on should be installed in HipChat
  • allowGlobal: set to true if your addon can be installed globally (which makes it accessible in all rooms)
  • allowRoom: set to true if your addon can be installed in a room
  • installedUrl: the URL HipChat will redirect to post-installation
  • updatedUrl: the URL HipChat will redirect to post-re-installation (optional, the installedUrl will be used otherwise, see the section on updates below)

Installation in HipChat

Users are presented with a dialog asking them to approve the scopes your add-on requested. Once approved, the installation flow continues.

Retrieve the installation context

If the user approves the installation, HipChat redirects the user to the URL you specified in the descriptor, in capabilities.installable.installedUrl

HipChat will includes two query parameters: 

• installable_url: A URL pointing to a document with the installation details. Note: this document can only be fetched once.
• redirect_url: The URL to redirect to after you have processed the installation.

Your application then needs to do a GET on the installable_url. HipChat responds with a JSON document containing:

1
2
{
     "capabilitiesUrl":"https://api.hipchat.com/v2/capabilities",
     "oauthId":"abc",
     "oauthSecret": "xyz",
     "groupId": "123",
     "roomId": "1234"   
}

• A capabilities URL: link to document which lists the URLs for the HipChat REST endpoints.
• OAuth ID
• OAuth secret
• Group ID
• Room ID (optional): which room the add-on was installed in.

You need to save this. Next, do the following from your add-on:

1. Issue a GET for the capabilitiesUrl. Look for capabilities.oauth2Provider.tokenUrl in the returned JSON.

2. Issue a POST to capabilities.oauth2Provider.tokenUrl using the OAuth ID and secret you saved from above. Here's a sample curl:

   1
   2
   curl '<capabilities.oauth2Provider.tokenUrl>' -H 'Content-Type: application/x-www-form-urlencoded' -u <oauthid>:<oauthsecret> --data 'grant_type=client_credentials&scope=<list of scopes>'
   

   In return, you'll get the access_token details:

   1
   2
   { 
     access_token: '5236346233724572457245gdgreyt345yreg',
     expires_in: 431999999,
     group_id: 123,
     group_name: 'Example Company',
     scope: 'send_notification',
     token_type: 'bearer' 
   }
   

   Save this information in your database. You'll use this token to make authenticated requests against the HipChat API. Note that this token does expire. Use the expires_in (in seconds) property to determine when you should refresh the token. When the access_token expires, you can repeat step 2 to obtain a new token.

Configuration flow

If your add-on exposes a configuration page to users via configurable/url, the configuration page will be exposed to users in a dialog post installation. 

Handling add-on uninstallations

For the client-side flow, you register a separate URL in the descriptor:

1
2
"installedUrl": "${host}/installed",
"uninstalledUrl": "${host}/uninstalled"

The uninstalledUrl works the same way as the installedUrl (fetch installableUrl etc.).

Whether your application returns a 200 response or not, the uninstallation will be allowed to continue.

To verify the uninstallation request, you can again choose to attempt to request an OAuth token, which should be rejected due to the uninstallation already taking place on the HipChat server.

Handling add-on updates

When a HipChat administrator re-installs your integration, you would ordinarily receive a new installation request which supersedes the previous one. This means that your add-on will be issued a new OAuth ID and secret, and all existing OAuth tokens become invalid. You can choose to preserve the existing OAuth ID by registering an update endpoint using installable.updatedUrl. If this URL is specified in the descriptor, HipChat will redirect to this URL after a re-installation.

HipChat will includes two query parameters: 

• **installable_url: **A URL pointing to a document with the installation details. Note: this document can only be fetched once.
• redirect_url: The URL to redirect to after you have processed the installation.

Your application then needs to do a GET on the installable_url. HipChat responds with a JSON document containing the same payload as for uninstallations:

1
2
{
     "capabilitiesUrl":"https://api.hipchat.com/v2/capabilities",
     "oauthId":"abc",
     "roomId": "1234"   
}