HipChat (API v2) Integration

 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 to 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 will automatically be forwarded to your HipChat room. You can 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.
  4. Click "Create" to generate a V2 API token.
  5. Copy the generated API token.
  6. Please create an OpsGenie account if you haven't done already.
  7. Go to OpsGenie HipChat (API v2) Integration page, 
  8. Paste the HipChat V2 API Token you copied before into "V2 Access Token" field.
  9. 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". You can access room data from "https://<your account name>.hipchat.com/rooms"
  10. You can populate expressions in Rooms field to send alert messages to dynamic rooms. You can get detailed information by referring Sending OpsGenie alerts to HipChat Rooms Dynamically section.
  11. Click on "Save Integration"

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

Sending OpsGenie alerts to HipChat Rooms Dynamically

In integration configuration, you can populate Rooms field with expressions. This will give you the opportunity to send the chat message to a dynamic room according to the expression.
If you populate rooms field with {{entity}} and save, then create an alert with the entity field "test room". Chat message will be sent to "test room" if the room exists.

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

Sample Request

Make sure your 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

You can easily execute actions on OpsGenie alerts, just by entering a command with the tinyId of the alert into your HipChat room. Note that you can execute a single command on multiple alerts.

You can create an alert, too. Use the alert command to create an alert in OpsGenie, right from your 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 [user team]
  • Get Alert :
    /genie get [tinyID]
  • List Alerts :

    Lists all open alerts.

    /genie list
  • List Integrations :
    /genie list integrations
  • List Policies :
    /genie list policies
  • 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 as well

OpsGenie can match the HipChat user who has 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 your users use the same full names in HipChat and OpsGenie, the commands they execute from HipChat will be attributed to their OpsGenie accounts as well. For example, a user can send a close alert command from HipChat and the same user will be 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.