[[configuring-hipchat]]
=== Configuring Watcher to Send Messages to HipChat

You can configure Watcher to use the HipChat APIs to send messages to HipChat rooms and users.
Watcher supports both the HipChat v2 and v1 APIs.

[[hipchat-account]]
==== Configuring HipChat Accounts
You configure the accounts Watcher can use to communicate with HipChat in your `elasticsearch.yml` 
configuration file. Each account configuration has a unique name and specifies a HipChat API profile
and the authentication information needed to access the APIs. You can also specify message defaults, 
such the default message text and color.

Watcher provides three HipChat API profiles:

<<hipchat-api-integration,integration>> :: Sends messages to a specific room using HipChat's 
v2 API https://www.hipchat.com/docs/apiv2/method/send_room_notification[Send room notification].
<<hipchat-api-user, user>> :: Sends messages as a particular user through the HipChat v2 API. 
Enables you to send messages to arbitrary rooms or users. 
<<hipchat-api-v1, v1>> :: Sends messages to rooms using HipChat's v1 API  
https://www.hipchat.com/docs/api/method/rooms/message[rooms/message]. 

NOTE: The `v1` profile is provided because it is simple to set up and the HipChat v1 API is familiar  
to many users. However, HipChat has deprecated the v1 API and is encouraging users to migrate to 
v2. Both the `integration` and `user` profiles are based on the HipChat v2 API.

If you configure multiple HipChat accounts, you either need to configure a default HipChat account
or specify which account the notification should be sent with in the <<actions-hipchat, hipchat>> 
action. You set `default_account` in `watcher.actions.hipchat.service` to specify a default account.

To configure HipChat accounts, set the `watcher.actions.hipchat.service` property in 
`elasticsearch.yml`. For example:

[source,yaml]
--------------------------------------------------
watcher.actions.hipchat.service:
  default_account: hipchat-account1
  account:
    hipchat-account1:
      profile: v1
      auth_token: 3eLB803Nyp7UBmegJwP1rMdUmzk5HqnzJCgflrhv
      message_defaults:
        color: purple
        format: text
    hipchat-account2:
      profile: integration
      auth_token: 3eLB803Nyp7UBmegJwP1rMdUmzk5HqnzJCgflrhv
      room: mission-control
      message_defaults:
        color: gray
        format: text
--------------------------------------------------

See the following sections information about using each profile type.

[[hipchat-api-integration]]
===== Using the HipChat Integration Profile

You can use the `integration` profile to send messages to specific rooms. When you set an 
account's profile to `integration`, Watcher sends the messages through HipChat's v2 
https://www.hipchat.com/docs/apiv2/method/send_room_notification[Send room notification] API.

When you use the `integration` profile, you need to configure a separate HipChat account in 
Watcher for each room you want to send messages--the account configuration contains a 
room-specific authentication token. Alternatively, you can use the  <<hipchat-api-user, `user`>> 
or <<hipchat-api-v1, `v1`>> profile to send messages to multiple rooms.

NOTE: The `integration` profile only supports sending messages to rooms, it does not 
support sending private messages. To notify a particular HipChat user, create an account
that uses the <<hipchat-api-user, `user`>> profile.

Before you can configure an account that uses the `integration` profile, you need to generate a 
room-specific authentication token through the HipChat admin console:

. Log in to http://hipchat.com[hipchat.com] or your HipChat server as a group administrator.
. Go to *Group admin > Rooms*.
. Click the name of the room you want to send messages to.
. Click the *Tokens* link.
. Enter a name for the token in the *Label* field.
+
image::images/hipchat-generate-room-token.jpg[]
. Select the *Send Notification* scope.
. Click *Create*.
. Copy the generated token so you can paste it into your HipChat account configuration in 
`elasticsearch.yml`. 
+
image::images/hipchat-copy-room-token.jpg[]

To configure a HipChat account that uses the `integration` profile, you must:

. Set the `type` to `integration`.
. Set `room` to the name of the room you want to send messages to.
. Set `auth_token` to the room-specific authentication token.

For example, the following snippet configures an account called `notify-monitoring` that
sends messages to the `monitoring` room.

[source,yaml]
--------------------------------------------------
watcher.actions.hipchat.service:
  account:
    notify-monitoring: 
      profile: integration
      auth_token: 3eLB803Nyp7UBmegJwP1rMdUmzk5HqnzJCgflrhv
      room: monitoring
--------------------------------------------------

You can also specify defaults for the notification messages. For the complete list of attributes,
see <<hipchat-account-attributes, HipChat Account Attributes>>.

[[hipchat-api-user]]
===== Using the HipChat User Profile

You can use the `user` profile to send messages to rooms as well as individual HipChat users. 
When you set an account's profile to `user`, Watcher sends messages as a particular user 
through the HipChat v2 API.

Before you can configure an account that uses the `user` profile, you need to:

. Add a HipChat user for Watcher. Watcher sends messages via this HipChat user account, so
keep that in mind when setting the user name. 
. Create an API token for the Watcher user:
.. Log in to HipChat as the Watcher user.
.. Go to `https://<hipchat-server>/account/api`. For example, `https://www.hipchat.com/account/api`.
.. Confirm the user password.
.. Enter a name for the token in the *Label* field.
+
image::images/hipchat-generate-user-token.jpg[]
. Select the *Send Notification* and *Send Message* scopes.
. Click *Create*.
. Copy the generated token so you can paste it into your HipChat account configuration in 
`elasticsearch.yml`. 
+
image::images/hipchat-copy-room-token.jpg[]

To configure a HipChat account that uses the `user` profile, you must:

. Set the `type` to `user`.
. Set `user` to the email address associated with the Watcher user.
. Set `auth_token` to the Watcher user's authentication token.

For example, the following snippet configures an account called `notify-monitoring` that
sends messages to the `monitoring` room.

[source,yaml]
--------------------------------------------------
watcher.actions.hipchat.service:
  account:
    notify-monitoring: 
      profile: user
      user: watcher-user@example.com
      auth_token: 3eLB803Nyp7UBmegJwP1rMdUmzk5HqnzJCgflrhv
--------------------------------------------------

You can also specify defaults for the notification messages. For the complete list of attributes,
see <<hipchat-account-attributes, HipChat Account Attributes>>.

[[hipchat-api-v1]]
===== Using the HipChat v1 Profile

You can use the `v1` profile to send messages to particular rooms. 
When you set an account's profile to `v1`, Watcher sends the messages through HipChat's v1 
https://www.hipchat.com/docs/api/method/rooms/message[rooms/message] API.

WARNING: The `v1` profile uses a deprecated API that is expected to be removed by HipChat in the 
future.

The `v1` profile only supports sending messages to rooms, it does not 
support sending private messages. To notify a particular HipChat user, create an account
that uses the <<hipchat-api-user, `user`>> profile.

Before you can configure an account that uses the `v1` profile, you need to generate a `v1` API 
token:

. Log in to your HipChat server as a group admin. 
. Go to `https://<hipchat-server>/admin/api`. For example, `https://hipchat.com/admin/api`.
. Confirm your admin password.
. Select the *Notification* type.
+
image::images/hipchat-generate-v1-token.jpg[]
. Enter a name for the token in the *Label* field.
. Click *Create*.
. Copy the generated token so you can paste it into your HipChat account configuration in 
`elasticsearch.yml`. 
+
image::images/hipchat-copy-v1-token.jpg[]

To configure a HipChat account that uses the `user` profile, you simply:

. Set the `type` to `v1`.
. Set `auth_token` to the v1 authentication token you generated.

For example, the following snippet configures an account called `notify-monitoring`:

[source,yaml]
--------------------------------------------------
watcher.actions.hipchat.service:
  account:
    notify-monitoring:
      profile: v1
      auth_token: 3eLB803Nyp7UBmegJwP1rMdUmzk5HqnzJCgflrhv
--------------------------------------------------

You can also specify defaults for the notification messages. For the complete list of attributes,
see <<hipchat-account-attributes, HipChat Account Attributes>>.

[[hipchat-account-attributes]]
==== HipChat Account Attributes

|======
| Name                     |Required | Default         | Description
| `profile`                | yes     | -               | The HipChat account profile to use: 
                                                        `integration`, `user`, or `v1`.
| `auth_token`             | yes     | -               | The authentiation token to use to access 
                                                         the HipChat API. 
| `host`                   | no      | api.hipchat.com | The HipChat server hostname. 
| `port`                   | no      | 443             | The HipChat server port number.
| `room`                   | no      | _               | The room you want to send messages to. 
                                                         Must be specified if the `profile` is set 
                                                         to `integration`. Not valid for  the 
                                                         `user` or `vi` profiles.
| `user   `                | no      | -               | The HipChat user account to use to send 
                                                         messages. Specified as an email 
                                                         address. Must be specified if the 
                                                         `profile` is set to `user`. Not valid for  
                                                         the `integration` or `v1` profiles.
| `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
| `message.notify`         | no      | `false`         | Indicates whether people in the room should be 
                                                         actively notified
|======