Scopes

The HipChat REST API endpoints are safeguarded by API scopes.

Your add-on must declare the scopes it requires based on which API endpoints it needs to use, via its descriptor. For example, an add-on with the following descriptor will be able to use the REST API endpoints to send notification messages to HipChat rooms, and create/archive/manage HipChat rooms:

1
2
3
4
5
6
7
8
"capabilities": {
    "hipchatApiConsumer": {
      "scopes": [
        "send_notification",
        "manage_rooms"
      ]
    }
}

When installing your add-on, users are presented with a dialog listing the scopes your add-on requested, and must accept these scopes before the installation continues.

Available scopes

ScopeAccess
admin_groupPerform group administrative tasks
admin_roomPerform room administrative tasks
manage_roomsCreate, update, and remove rooms
send_messageSend private one-on-one messages
send_notificationSend room notifications
view_groupView users, rooms, and other group information
view_messagesView messages from chat rooms and private chats you have access to
view_roomView room information and participants, but not history