A Comprehensive Guide to Building Hipchat Connect Integrations

At Cloudo we are working hard to help people focus on their work without switching context for small tasks. With the HipChat Connect API we are building an integration inside the HipChat app that enables you to quickly find and share content from your cloud applications. We wanted to share our experiences building with the HipChat Connect API. We recommend following the tutorial by writing the integration from scratch, but if you prefer you can grab the code from Bitbucket instead. After a few minutes you should have very basic but fully functional integration like this:

If you are not familiar with HipChat Connect API this is a good place to start. We will cover only the basics of adding actions, glances, dialogs and sidebars. If you decide to write your own integration we strongly recommend you read the entire documentation and API reference.

Let’s get started. Hipchat servers need to speak to your integration so we will be using ngrok during the development. First thing we need is a publicly available descriptor json of your integration with all the information about your integration. Create a new folder with the package.json file inside with the following content:

Install the integration dependencies with:

npm install

Next create server.js like this:

Now is a good time to start a ngrok tunnel on port 8000. To test our server copy the ngrok url and start the server with the following command line:

babel-node server.js — ngrok=https://your-ngrok.ngrok.io

Notice that we are using babel to compile ES6 code. If you open https://your-ngrok.ngrok.io you should see the “Hey Ho Let’s Go” message. Let’s add the actual descriptor endpoint. First check if you have Hipchat Connect enabled in Hipchat Admin and edit server.js file to look like this:

To install your integration go to the Addon Page and at the bottom of the page click on “Install an integration from a descriptor URL” and paste your descriptor url there. You should see something like this:

OK now we are ready do add some features. First lets add the install callback endpoint. After adding the integration HipChat makes a post request to our endpoint with the authorisation data.

If you restart server and reinstall integration you should see authorisation data in terminal. You should definitely store these data for later use. Next lets add a glance. Make sure your endpoints accept CORS requests.

Adding actions, dialogs and sidebars is very straightforward. Check out our example integration in Bitbucket.

And that’s it. We now have a complete, functioning integration. We recommend you read the documentation to learn about security best practices and the entire Connect API in more detail. If you want to see the Cloudo integration in action, just add our descriptor url.