HipChat REST API

Authentication

Security scopes

Scopes ensure the token can only be used for what the add-on was authorised to do.

Your add-on declares the scopes required to be able to use REST API endpoints via its descriptor.

Learn more

To view the list of scopes and understand how to request scopes, read API scopes

Requesting an API access token

To make a call to the HipChat REST API for a tenant, your add-on must first programmatically request a temporary token.

There are four types of tokens:

Token type Makes the REST call as Example scenario
Add-on token The add-on Your add-on sends a notification message to a HipChat room for an event in your application.
User token A HipChat user

A user pastes a link to a file, with a URL that matches a webhook your add-on is listening to.

Your add-on then retrieves the content of the file, and post it as an attachment to a HipChat room on behalf of the user.

Personal access token Your HipChat user account

You want to test the REST API (this is the easiest way to generate a token).

Room notification token

The add-on (access limited to a room)

Your add-on is a notification-only add-on (see Guide for more details)

Learn more

To learn how to generate tokens, read API access tokens

Including the token in the request

The token can be used to make REST calls to HipChat, for example to send a notification message to a room. 

You have the choice of providing your access token either as:

  • The 'auth_token' query parameter
  • The Authorization HTTP request header, which is more secure as you risk your access token showing up in server logs

Testing a token

To test if an auth token is valid and has access to a given method, include auth_test=true. The method's normal actions (messaging a room, listing users, etc) will not be performed. So, given the request:

  • If the token is valid a HTTP 202 response will be returned.
  • If the token does not have access to the method, a standard HTTP 401 error will be returned.

Example: sending a notification message

To send a notification message, an add-on uses the HipChat REST API. HipChat currently supports plain text and HTML notifications. 

REST API endpoints

API reference

For a comprehensive documentation of the HipChat REST API, visit the API reference documentation.

Throughout the API documentation, you'll see a list of client types that may access a given resource operation. Each API access token has a logically associated client type, depending on how the token was generated. The possible client types are as follows:

Client type Description
Group client
  • An add-on that has been installed globally in a HipChat group is granted group client tokens
Room client
  • An add-on that has been installed in a HipChat room is granted room client tokens
  • A room notification token
User
  • A user token
  • A personal access token
OAuth client Any of the above client types

Learn more

For a comprehensive documentation of the HipChat REST API, visit the API reference documentation.

API rate limits

Authentication tokens generated by add-ons are limited to a maximum number of calls executed in a particular time window. 

Learn more

To learn more about API rate limits, read API rate limits

API title expansion

In order to be minimise network traffic and help avoid API rate limits, the HipChat API provides title expansion. 

Learn more

To learn more about API title expansion, read API title expansion

Was this page helpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport