OpenSearch/docs/en/watcher/actions/hipchat.asciidoc

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

Use the `hipchat` action to send messages to https://www.hipchat.com[HipChat]
rooms or users. To send HipChat messages, you must
<<configuring-hipchat, configure at least one HipChat account>> in `elasticsearch.yml`. 

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

You configure HipChat actions in a `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 specific room, the only required
attribute is the message itself:

[source,js]
--------------------------------------------------
"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,js]
--------------------------------------------------
"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,js]
--------------------------------------------------
"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

[cols=",^,,", options="header"]
|======
| Name              |Required | Default         | Description

| `account`         | no      | Default account | The HipChat account to use to send the message.

| `proxy.host`      | no      | -               | The proxy host to use (only in combination with `proxy.port`)

| `proxy.port`      | no      | -               | The proxy port to use (only in combination with `proxy.host`)

| `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.
|======


[[configuring-hipchat]]
==== Configuring HipChat Accounts

You configure the accounts {watcher} can use to communicate with HipChat in the
`xpack.notification.hipchat` namespace in `elasticsearch.yml`. Both
https://www.hipchat.com/docs/api[v1] and
https://www.hipchat.com/docs/apiv2[v2] HipChat APIs are supported.

{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 this API
      is familiar to many users. That said, 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 set a default
HipChat account or specify which account the notification should be sent with
in the <<actions-hipchat, hipchat>> action.

[source,yaml]
--------------------------------------------------
xpack.notification.hipchat:
  default_account: team1
  account:
    team1:
      ...
    team2:
      ...
--------------------------------------------------


[[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`, the messages are sent 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 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. Use the <<hipchat-api-user, `user`>>
      profile to notify a particular HipChat user.

You need a room-specific authentication token to configure an `integration`
account. To generate an authentication token:

. 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:

. 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]
--------------------------------------------------
xpack.notification.hipchat:
  account:
    notify-monitoring:
      profile: integration
      auth_token: 3eLB803Nyp7UBmegJwP1rMdUmzk5HqnzJCgflrhv
      room: monitoring
--------------------------------------------------

You can also specify defaults for the <<hipchat-account-attributes,
message attributes>>:

[source,yaml]
--------------------------------------------------
xpack.notification.hipchat:
  account:
    notify-monitoring:
      profile: integration
      auth_token: 3eLB803Nyp7UBmegJwP1rMdUmzk5HqnzJCgflrhv
      room: monitoring
      message:
        format: text
        color: blue
        notify: true
--------------------------------------------------


[[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 a `user` account, you need to:

. Add a HipChat user for {watcher}. When setting the user name, keep in mind that
  the messages are sent on behalf of this user.
. 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:

. 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 configuration creates an account called
`notify-monitoring` that sends messages to the `monitoring` room:

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

You can also specify defaults for the <<hipchat-account-attributes,
message attributes>>:

[source,yaml]
--------------------------------------------------
xpack.notification.hipchat:
  account:
    notify-monitoring:
      profile: user
      user: watcher-user@example.com
      auth_token: 3eLB803Nyp7UBmegJwP1rMdUmzk5HqnzJCgflrhv
      message:
        format: text
        color: blue
        notify: true
--------------------------------------------------


[[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`, messages are sent 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. Use the <<hipchat-api-user, `user`>> profile to send
private messages to HipChat users.

Before you can configure a `v1` account, 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 `v1` profile:

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

For example, the following configuration creates an account called
`notify-monitoring`:

[source,yaml]
--------------------------------------------------
xpack.notification.hipchat:
  account:
    notify-monitoring:
      profile: v1
      auth_token: 3eLB803Nyp7UBmegJwP1rMdUmzk5HqnzJCgflrhv
--------------------------------------------------

You can also specify defaults for the <<hipchat-account-attributes,
message attributes>>.

[source,yaml]
--------------------------------------------------
xpack.notification.hipchat:
  account:
    notify-monitoring:
      profile: v1
      auth_token: 3eLB803Nyp7UBmegJwP1rMdUmzk5HqnzJCgflrhv
      message:
        format: text
        color: blue
        notify: true
--------------------------------------------------