How to write and host a HipChat addon?

I'm not quite sure I understand the whole process of writing addons for HipChat. Assuming that I would like to implement a notifier addon (something similar to what is described here: https://issues.jenkins-ci.org/browse/JENKINS-41976), do I need to host that addon somewhere in order to have the capabilities url available?

Whilst searching around, I could find a HipChat integration in the marketplace that I could add globally to a HipChat deployment, but it is not really clear whether the token generated was a v1 API token, or if it was an OAuth2 access token for that addon? I'm guessing that addons would have client_id and client_secret associated with them instead and the oauth2 tokens would need to be retrieved by the addon itself.

Additionally, I can't really tell whether this addon thing is something that everybody can host on their own if they'd like, or whether the addon needs to be implemented as if it was a SaaS ready application and hosted by the author of the addon.

 

Any help on these subjects would be greatly appreciated. smile

2 answers

1 vote
Nick Turskyi Atlassian Team Mar 03, 2017

Hi Peter,

For a simple functionality like posting notifications to HipChat room, you may also use the "BYO Integration" in the room integrations list:

Screenshot 2017-03-03 12.00.44.png

It will generate an API token with the necessary scope and provide instructions for sending notifications to the room.

While Chris' answer is a lot more comprehensive, I hope this could also be helpful for somebody!

Nick

Just to clarify:

would this mean that anyone who wants to send notifications to multiple rooms would need to use their own BYO extension with the associated credentials? Or would it be possible to just create an addon without any backend whatsoever and have access to a proper OAuth2 access token (or client credentials)?

The Jenkins integration on the marketplace seems to expose a token on the interface, but it's difficult to tell if that's an OAuth2 access token or a v1 API token.

Nick Turskyi Atlassian Team Mar 03, 2017

@Peter Major, once you configure a BYO integration for a room, it generates an "add-on" APIv2 token, which can be used to send messages to this room (token scope is limited to send_notification and view_room for this particular room). This token can also be created manually on the the Room -> Tokens page.

You may also want to generate a personal access token, which may have any permission your user has and does not expire.

None of the above requires you to run the actual infrastructure for the addon, you may just use the token against HipChat API from any code.

Further reading on API tokens: https://developer.atlassian.com/hipchat/guide/hipchat-rest-api/api-access-tokens

Jenkins for HipChat is a 3rd party integration, but their documentation states it supports both v1 and v2 with the former being deprecated in future versions.

 

Thanks for the note. I'm aware of the Jenkins integration since I'm the maintainer of the Jenkins plugin, but I have not been involved with the Jenkins add-on on the Marketplace in any shape or form.

I wasn't really able to add BYO addon to all rooms, it looks like that adding BYO is limited to particular rooms - well that kind of prevents people from using those access tokens to notify multiple rooms at the same time.

Nick Turskyi Atlassian Team Mar 03, 2017

Yeah, the BYO is limited to the room it's installed to.

For this kind of tasks I would recommend creating a user token with the proper scope - it will have access to all the room this user is a part of.

As of the Marketplace question, can you provide a link to the plugin so I could check?

 

0 votes

It sounds like you've already looked through some of the documentation, but just in case... a good place to start would be https://developer.atlassian.com/hipchat/getting-started. If you're looking to build an addon yourself, it indeed would need to be hosted somewhere public so that the client can load the appropriate data and the server can communicate back to the addon for stuff like webhooks.

None of the addons in marketplace use v1 API tokens (the v1 API is deprecated and we don't recommend building anything on top of it). All tokens made via the v2 API and going forward and done via oauth. When the clients make requests to your addon, they will include a JWT identifying themselves (including some group and user information) which your addon can use to pull and server appropriate data back to the user.

The best way to get familiar is probably going through the step-by-step guide at https://developer.atlassian.com/hipchat/tutorials/getting-started-with-atlassian-connect-express-node-js. It will explain how to setup a local node server and a tunnel via ngrok so you can play with things.

Hopefully that helps clear things up and get you started building something that makes your HipChat experience better!

Suggest an answer

Log in or Sign up to answer
Community showcase
Published Aug 10, 2018 in Hipchat

What should I think about when migrating HipChat to Slack?

...from the beginning. We have built up a lot of content in HipChat, with it being a core tool in our distributed company model. While it is true that we didn’t need to move to Slack immediately, we felt it...

490 views 1 10
Read article

Atlassian User Groups

Connect with like-minded Atlassian users at free events near you!

Find a group

Connect with like-minded Atlassian users at free events near you!

Find my local user group

Unfortunately there are no AUG chapters near you at the moment.

Start an AUG

You're one step closer to meeting fellow Atlassian users at your local meet up. Learn more about AUGs

Groups near you