[[actions-hipchat]]
==== HipChat Action

A watch <<actions, action>> that sends messages to https://www.hipchat.com[HipChat] 
rooms or users. To use the HipChat action, you need to configure at least one 
HipChat account in Watcher. For information about configuring accounts, see <<configuring-hipchat, 
Configuring Watcher to Send Notifications to HipChat>>.

[[configuring-hipchat-actions]]
===== Configuring HipChat Actions

You configure HipChat actions in a watch's `actions` array. Action-specific attributes are
specified using the `hipchat` keyword. You must specify the `message` attribute for all
`hipchat` actions. If you omit the `account` attribute, the message is sent
using the default HipChat account configured in `elasticsearch.yml`. 

For example, the following action is configured to send messages using a HipChat account that
uses the <<hipchat-api-integration, integration>> profile. Because this type of account can
only send messages to a particular room, the only required attribute is the message itself.

[source,json]
--------------------------------------------------
"actions" : {
  "notify-hipchat" : {
    "transform" : { ... },
    "throttle_period" : "5m",
    "hipchat" : {
      "account" : "integration-account", <1>
      "message" : {
        "body" : "Encountered  {{ctx.payload.hits.total}} errors in the last 5 minutes (facepalm)", <2>
        "format" : "text",
        "color" : "red",
        "notify" : true
      }
    }
  }
}
--------------------------------------------------
<1> The name of a HipChat account configured in `elasticsearch.yml`.
<2> The message you want to send to HipChat.

To send messages with a HipChat account that uses the <<hipchat-api-user, user>> profile, you need
to specify what rooms and users you want to send the message to. For example, the following action 
is configured to send messages to the `mission-control` and `devops` rooms 
as well as the user `website-admin@example.com`. (To send to multiple users or rooms, specify an 
array of strings.)

[source,json]
--------------------------------------------------
"actions" : {
  "notify-hipchat" : {
    "transform" : { ... },
    "throttle_period" : "5m",
    "hipchat" : {
      "account" : "user-account",
      "message" : {
        "room" : [ "mission-control", "devops" ], 
        "user" : "website-admin@example.com",
        "body" : "Encountered  {{ctx.payload.hits.total}} errors in the last 5 minutes (facepalm)",
        "format" : "text",
        "color" : "red",
        "notify" : true
      }
    }
  }
}
--------------------------------------------------

To send messages with a HipChat account that uses the <<hipchat-api-v1, v1>> profile, you need
to specify what room or rooms you want to send the message to. For example, the following action 
is configured to send messages to the `server-status` room. (To send to multiple 
rooms, specify an array of strings.)

[source,json]
--------------------------------------------------
"actions" : {
  "notify-hipchat" : {
    "transform" : { ... },
    "throttle_period" : "5m",
    "hipchat" : {
      "account" : "v1-account",
      "message" : {
        "from" : "Watcher",
        "room" : [ "server-status", "infra-team" ],
        "body" : "Encountered  {{ctx.payload.hits.total}} errors in the last 5 minutes (facepalm)",
        "format" : "text",
        "color" : "red",
        "notify" : true
      }
    }
  }
}
--------------------------------------------------

[[hipchat-action-attributes]]
===== HipChat Action Attributes

The following table lists the attributes you can set for `hipchat` actions.

[[hipchat-api-integration-action-attributes]]
|======
| Name                     |Required | Default              | Description
| `account`                | no      | Default account      | The HipChat account to use to send the
                                                              message.
| `message.body   `        | yes     | -                    | The message content. Can contain up to  
                                                              1000 characters. 
| `message.format`         | no      | html                 | The format of the message: `text` or `html`.
| `message.color`          | no      | yellow               | The background color of the notification in the 
                                                              room: `gray`, `green`, `purple`, `red`, `yellow`.
| `message.notify`         | no      | false                | Indicates whether people in the room should  
                                                              be actively notified
| `message.from`           | no      | the watch ID         | The name that appears as the notification sender.
                                                              Only valid for accounts that use the v1 profile.
| `message.room`           | no      | -                    | The rooms that the notification should go to. 
                                                              Accepts a string value or an array of string 
                                                              values. Must be specified when using the 
                                                              v1 profile. At least one room or user must
                                                              be specified when using the `user` profile.
                                                              Not valid for the `integration` profile.
| `message.user`           | no      | -                    | The users that the notification should go to. 
                                                              Accepts a string value or an array of string 
                                                              values. At least one room or user must
                                                              be specified when using the `user` profile.
                                                              Not valid for the `integration` or `v1`
                                                              profiles.
                                                    
|======