API Reference version 2

Capabilities Descriptor

At a bare minimum, the integration must expose an HTTP-accessible "capabilities descriptor", a JSON-encoded document that describes the integration and what its capabilities are. The minimal descriptor looks like this:

{
  "name": "My Integration",
  "description": "An integration that does wonderful things",
  "key": "com.example.myintegration",
  "links": {
    "homepage": "https://example.com/myintegration",
    "self": "https://example.com/myintegration/capabilities"
  },
  "capabilities": {
    "hipchatApiConsumer": {
      "scopes": [
        "send_notification"
      ]
    }
  }
}

This descriptor describes an integration that wants to be able to send room notifications using the HipChat API.

Some of the capabilities are documented separately and are linked from the table below.

Descriptor Validation

You can test whether your descriptor conforms to the schema using the Atlassian Connect Validator.

Attribute Reference

Type Property Description Required?
string apiVersion

The HipChat Connect API version used by this integration. Defaults to 1:1

object capabilities

The set of capabilities this application supports.

array action

Please see the action detail page

object adminPage

The ability to be user configurable via an admin page in the menu

string url

The URL to embed into a configure dialog via an iframe

Required
object configurable

Please see the configurable detail page

array dialog

Please see the dialog detail page

array externalPage

The ability to specify an external web page that can be targeted by an action

An array of the following objects.

string key

Unique key (in the context of the integration) to identify this external page.

Valid length range: 1 - 40.

Required
object name

The display name of the external page.

string i18n

The optional localization key, used to look up the localized value.

Valid length range: 1 - 40.

string value

The default text.

Valid length range: 1 - 100.

Required
string url

The URL of the external page.

Required
array glance

Please see the glance detail page

object hipchatApiConsumer

The ability to consume the HipChat API

str | obj avatar

An image used by the HipChat client when showing messages from this addon

object [avatar, object 2]

An object with the following properties.

Required
string url

The url where the icon is

Valid length range: 1 - unlimited.

Required
string url@2x

The url for the icon to be used on high dpi screens.

Valid length range: 1 - unlimited.

string fromName

The name that messages should be from when sent from the integration itself.

array scopes

An array of scopes that are required to consume the HipChat API

Required
object installable

The capability of receiving a synchronous installation callback during integration installation.

boolean allowGlobal

Whether the integration can be installed globally or not

Defaults to true.

boolean allowRoom

Whether the integration can be installed in a room or not

Defaults to true.

string callbackUrl

The URL to receive a confirmation of an integration installation. The message will be an HTTP POST with the following fields in a JSON-encoded body: 'capabilitiesUrl', 'oauthId', 'oauthSecret', and optionally 'roomId'. The installation of the integration will only succeed if the POST response is a 200.

string installedUrl

The URL to redirect the browser to after the integration has been installed. The redirected URL will also contain the query parameters 'redirecturl' and 'installableurl' for the integration configuration page and REST resource for installable information, respectively.

string uninstalledUrl

The URL to redirect the browser to after the integration has been uninstalled. The redirected URL will also contain the query parameters 'redirecturl' and 'installableurl' for the integration management page and REST resource for installable information, respectively.

string updateCallbackUrl

The URL to receive a confirmation of an add-on update. The message will be an HTTP POST with the following fields in a JSON-encoded body: 'capabilitiesUrl', 'oauthId', and optionally 'roomId'.

string updatedUrl

The URL to redirect the browser to after the add-on has been updated. The redirected URL will also contain the query parameters 'redirecturl' and 'installableurl' for the add-on management page and REST resource for installable information, respectively.

object oauth2Consumer

The capability of using OAuth 2 to authenticate to a remote application

array redirectionUrls

An array of URLs to allow for redirection after the remote system has generated an authorization code

Required
object oauth2Provider

The capability of providing and accepting OAuth 2 tokens for authentication

string authorizationUrl

The OAuth 2 endpoint to direct browsers to in order to receive an authorization code that can be later exchanged using the token URL for an access token

string tokenUrl

The OAuth 2 token endpoint for retrieving an access token

array webPanel

Please see the webPanel detail page

array webhook

Please see the webhook detail page

string description

A short description of this application

Required
string key

The marketplace integration key that uniquely identifies the application, if registered

Required
object links

URLs to retrieve this and related integration information

Required
string homepage

The URL to human-viewable home page of this integration

string self

The URL to this descriptor.

Required
string name

The display name of this application

Required
object vendor

The vendor that maintains this application

string name

The vendor display name

Required
string url

The vendor's home page URL

Required