HipChat Integration

Atlassian HiptChat is a popular team chat service with desktop, mobile & web applications. OpsGenie is an alert and notification management solution that is highly complementary to HipChat.

What does OpsGenie offer HipChat users?

OpsGenie provides a powerful two-way integration with HipChat. Notifications of OpsGenie's robust alerts go right into HipChat rooms, and in turn, users can acknowledge, close, or assign these alerts from the chat room as easily as entering a command like /genie ack 12.

Add a HipChat integration in OpsGenie and OpsGenie alert notifications are automatically forwarded to your HipChat room. Execute actions on the alert just by typing a /genie command into the chat.

The integration works with on-premise HipChat servers as well.

Adding HipChat (API v2) integration to OpsGenie

  1. In HipChat, create a user with the full name "OpsGenie", with User role.
  2. Log in with the user OpsGenie; go to Account Settings / API Access (https://<your account name>.hipchat.com/account/api).
  3. Populate token name as "ognotification" and choose "Send Notification" and "Administer Room" scopes for the token.
  1. Click Create to generate a V2 API token.
  2. Copy the generated API token.
  3. Please create an OpsGenie account if you haven't done so already.
  4. Go to OpsGenie HipChat (API v2) Integration page.
  5. Paste the HipChat V2 API Token you copied before into "V2 Access Token" field.
  6. Enter the names of the rooms you want to post messages to into the "Rooms" field. Make sure "OpsGenie" user is the owner of the rooms. Otherwise you will get 403 response. Access room data from "https://<your account name>.hipchat.com/rooms".
  7. Populate expressions in the "Rooms" field to send alert messages to dynamic rooms. Get detailed information by referring to: Sending OpsGenie alerts to HipChat Rooms Dynamically section.
  8. Click Save Integration.

All set! Now when an OpsGenie alert is created, acknowledged, etc., the notification is automatically forwarded to HipChat rooms as messages.

Sending OpsGenie alerts to HipChat Rooms Dynamically

In integration configuration, populate the "Rooms" field with expressions. This gives you the opportunity to send the chat message to a dynamic room according to the expression.

If the "Rooms" field is populated with {{entity}} and saved, then an alert is created with the entity field "test room". Chat message are sent to "test room" if the room exists.

To execute /genie commands in a Dynamically configured HipChat room, create a Webhook. To get more information about "Create Webhook" in HipChat, you can refer to HipChat API Documentation.

Sample Request

Make sure the auth_token is generated with admin_room scope.

curl -XPOST -H "Content-Type:application/json" 'https://api.hipchat.com/v2/room/room_id_or_name/webhook?auth_token=your_auth_token' -d '
{
    "name": "Webhook Name",
    "pattern": "/genie",
    "url": "https://api.opsgenie.com/v1/json/hipchat?apiKey=4aa8b...",
    "event": "room_message"
}'

Using /genie Command

Easily execute actions on OpsGenie alerts by entering a command with the tinyId of the alert into your HipChat room. Note that it is possible to execute a single command on multiple alerts.

Use the alert command to create an alert in OpsGenie, right from the HipChat room.

Acknowledge Alert :
/genie ack [tinyID tinyID2..]

Close Alert :
/genie close [tinyID tinyID2..]

Add Note to Alert :
/genie note [note] to [tinyID tinyID2..]

Acknowledge All Open Alerts :
/genie ackall

Add Tag to Alert :
/genie addtag [tag1,tag2] to [tinyID tinyID2..]

Close All Open Alerts :
/genie closeall

Assign Alert :
/genie assign [tinyID tinyID2..] to [user]

Take Ownership of Alert :
/genie own [tinyID tinyID2..]

Execute Action :
/genie exec [action] on [tinyID tinyID2..]

Create Alert :
/genie alert [alert message] for [team1,team2,user1..]

Get Alert :
/genie get [tinyID]

List Alerts :
Lists all open alerts.
/genie list

Lists all open alerts of specified team.
/genie list alerts of team1

List Integrations :
/genie list integrations

List Policies :
/genie list policies

List Teams :
/genie list teams
/genie list teams contains [search query]
/genie list teams starts with [search query]

Enable Integration/Policy :
/genie enable [name]

Disable Integration/Policy :
/genie disable [name]

Take On-call :
Takes on-call for the specified amount of time for the team or schedule. Default amount of time is 1h. If no schedule/team is specified, the user will take on-call for his team's schedule, or a single schedule he's participant in.
/genie oncall [me/user] [h/m/d] for [team/schedule/all]

Sample uses are:

/genie oncall me 2h for weekend_schedule
/genie oncall john.smith@acme.com 1d for ops_team
/genie oncall me 2h for all
/genie oncall me 45m
/genie oncall me

Who is oncall :
Retrieves oncall user information from all schedules
/genie whoisoncall

Mute :
Mutes notifications for the user. Mutes for 5 minutes if not given.
/genie mute [me/username] [minutes(optional)]

Unmute :
Clears mute setting.
/genie unmute [me/username]

Help :
/genie help

OpsGenie matches users with HipChat

OpsGenie matches HipChat users who have executed a command from HipChat with the user registered in OpsGenie. OpsGenie does this by matching the full names of the users. As long as users use the same full names in HipChat and OpsGenie, the commands executed from HipChat are attributed to their OpsGenie accounts as well. For example, a user sends a close alert command from HipChat and the same user is automatically recognized in OpsGenie as the closer of the alert.

Please note that the maximum rate OpsGenie can post messages to HipChat is subject to HipChat's API Rate Limiting.