Integration Guidelines to Support HipChat Server

Issues/questions/comments? Please reach out to us at atlassian-connect-dev@atlassian.com.

Because HipChat Server can be installed on-premise, connectivity with your integration will be different from the Cloud version of HipChat (*.hipchat.com).

This guide will take you through the changes required to make your integration compatible with HipChat Server.

Making your integration compatible with HipChat Server

Instructional add-ons (API V1)

Note: API V1 is deprecated, so we recommend switching to API V2

Don't hardcode the HipChat API endpoint (https://api.hipchat.com/) in your implementation, but allow users to specify, when configuring the integration:

  • The API base URL and the token, or

  • The full API URL including the token

For example:

https://my.hipch.at/v1/rooms/message?format=json&auth_token={token}

Instructional add-ons (API V2)

Don't hardcode the HipChat API endpoint (https://api.hipchat.com/) in your implementation, but allow users to specify when configuring the integration:

  • The API base URL and the token, or

  • The full API URL including the token. The HipChat admin UI will soon allow to just copy and paste this URL, so this is the recommended approach.

For example:

https://my.hipch.at/v2/room/{id_or_name}/notification?auth_token={token} 

Connect Add-ons

Keep in mind that both inbound and outbound connectivity is not granted for installations in HC Server: Your add-on may or may not be able to send and receive messages from HipChat.

You will also need to support (or at least gracefully handle) older versions of HipChat server as time progresses.

The number one rule to follow: drive your implementation through HipChat's capability document. If you use one of the Atlassian Connect frameworks, this is handled for you. If you implement an add-on without using any of the Atlassian frameworks, please follow this approach:

When an add-on is installed into HipChat, your add-on service is invoked with a link to the HipChat capability document. Here's what that looks like:

A. You specify the endpoint that handles installation in your add-on capability descriptor:

"installable": {
  "callbackUrl": "https://example.com/myaddon/installable"
}

B. HipChat calls this URL with the installation payload:

{
  "capabilitiesUrl": "https://my.hipch.at/v2/capabilities",
  "oauthId:" "...",
  "oauthSecret": "..."
}

C. You then GET the capabilities document that HipChat points you to, which looks like this:

{
    "capabilities": {
        "hipchatApiProvider": {
            "availableScopes": {
              ...
            },
            "url": "https://my.hipch.at/v2"
        },
        "oauth2Provider": {
            "authorizationUrl": "https://my.hipch.at/users/authorize",
            "tokenUrl": "https://my.hipch.at/v2/oauth/token"
        }
    },
    "description": "Group chat and IM built for teams",
    "key": "hipchat",
    "links": {
        "api": "https://my.hipch.at/v2",
        "homepage": "https://www.hipchat.com",
        "self": "https://my.hipch.at/v2/capabilities"
    },
    "name": "HipChat",
    "vendor": {
        "name": "Atlassian",
        "url": "http://atlassian.com"
    }
}

D. You then extract the URLs that you need to call the API and to do the installation validation check as described in https://www.hipchat.com/docs/apiv2/addons:

apiEndpoint = doc['capabilities']['hipchatApiProvider']['url']
authorizationUrl = doc['capabilities']['oauth2Provider']['authorizationUrl']
tokenUrl = doc['capabilities']['oauth2Provider']['tokenUrl']

By following these steps, you avoid making any assumptions about where the HipChat API lives and if any of these URLs should ever point to a different endpoint, your add-on will continue to work.

Marking a Connect compatible with HipChat Server

By default, HipChat add-ons in the Marketplace don't show up in HipChat server. If your add-on is HC Server compatible, please let us now when you publish a new version of your Marketplace listing and we'll tick the necessary flag.

Documentation changes

If you make your integration compatible with HipChat Server, make sure to update the installation instructions that are linked from HipChat.

Make sure to list the connectivity requirements for your integration:

  • HipChat inbound connectivity requirements: if your integration makes use of HipChat APIs
  • HipChat outbound connectivity requirements: if your integration makes use of webhooks (make sure to list the hosts and ports)

Was this helpful?

Thanks for your feedback!

Why was this unhelpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport