New

The executive guide to generative AI

Read more
About usPartnersSupport|Login
IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.
« Logging action Slack action »
Elastic Docs ›Elasticsearch Guide [6.4] ›Alerting on Cluster and Index Events ›Actions

HipChat action

edit

HipChat action

edit

Use the hipchat action to send messages to HipChat rooms or users. To send HipChat messages, you must configure at least one HipChat account in elasticsearch.yml.

Configuring HipChat actions

edit

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 integration profile. Because this type of account can only send messages to a specific room, the only required attribute is the message itself:

"actions" : {
  "notify-hipchat" : {
    "transform" : { ... },
    "throttle_period" : "5m",
    "hipchat" : {
      "account" : "integration-account", 
      "message" : {
        "body" : "Encountered  {{ctx.payload.hits.total}} errors in the last 5 minutes (facepalm)", 
        "format" : "text",
        "color" : "red",
        "notify" : true
      }
    }
  }
}

The name of a HipChat account configured in elasticsearch.yml.

The message you want to send to HipChat.

To send messages with a HipChat account that uses the 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):

"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 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.)

"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

edit
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 accounts

edit

You configure the accounts Watcher can use to communicate with HipChat in the xpack.notification.hipchat namespace in elasticsearch.yml. Both v1 and v2 HipChat APIs are supported.

Watcher provides three HipChat API profiles:

integration
Sends messages to a specific room using HipChat’s v2 API Send room notification.
user
Sends messages as a particular user through the HipChat v2 API. Enables you to send messages to arbitrary rooms or users.
v1

Sends messages to rooms using HipChat’s v1 API rooms/message.

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 hipchat action.

Storing the auth_token in the configuration file or using via updating the settings now is still supported, but you should use the keystore for this, see Secure settings.

xpack.notification.hipchat:
  default_account: team1
  account:
    team1:
      ...
    team2:
      ...

Using the Hipchat integration profile

edit

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 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 user or v1 profile to send messages to multiple rooms.

The integration profile only supports sending messages to rooms, it does not support sending private messages. Use the 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:

  1. Log in to hipchat.com or your HipChat server as a group administrator.
  2. Go to Group admin > Rooms.
  3. Click the name of the room you want to send messages to.
  4. Click the Tokens link.

  5. Enter a name for the token in the Label field.

    hipchat generate room token
  6. Select the Send Notification scope.
  7. Click Create.

  8. Copy the generated token so you can paste it into your HipChat account configuration in elasticsearch.yml.

    hipchat copy room token

To configure a HipChat account that uses the integration profile:

  1. Set the type to integration.
  2. Set room to the name of the room you want to send messages to.
  3. 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:

bin/elasticsearch-keystore add xpack.notification.hipchat.account.notify-monitoring.secure_auth_token
xpack.notification.hipchat:
  account:
    notify-monitoring:
      profile: integration
      room: monitoring

You can also specify defaults for the message attributes:

xpack.notification.hipchat:
  account:
    notify-monitoring:
      profile: integration
      room: monitoring
      message:
        format: text
        color: blue
        notify: true

Using the HipChat user profile

edit

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:

  1. Add a HipChat user for Watcher. When setting the user name, keep in mind that the messages are sent on behalf of this user.

  2. Create an API token for the Watcher user:

    1. Log in to HipChat as the Watcher user.
    2. Go to https://<hipchat-server>/account/api. For example, https://www.hipchat.com/account/api.
    3. Confirm the user password.

    4. Enter a name for the token in the Label field.

      hipchat generate user token
  3. Select the Send Notification and Send Message scopes.
  4. Click Create.

  5. Copy the generated token so you can paste it into your HipChat account configuration in elasticsearch.yml.

    hipchat copy room token

To configure a HipChat account that uses the user profile:

  1. Set the type to user.
  2. Set user to the email address associated with the Watcher user.
  3. 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:

bin/elasticsearch-keystore add xpack.notification.hipchat.account.notify-monitoring.secure_auth_token
xpack.notification.hipchat:
  account:
    notify-monitoring:
      profile: user

You can also specify defaults for the message attributes:

bin/elasticsearch-keystore add xpack.notification.hipchat.account.notify-monitoring.secure_auth_token
xpack.notification.hipchat:
  account:
    notify-monitoring:
      profile: user
      message:
        format: text
        color: blue
        notify: true

Using the HipChat v1 profile

edit

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 rooms/message API.

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 user profile to send private messages to HipChat users.

Before you can configure a v1 account, you need to generate a v1 API token:

  1. Log in to your HipChat server as a group admin.
  2. Go to https://<hipchat-server>/admin/api. For example, https://hipchat.com/admin/api.
  3. Confirm your admin password.

  4. Select the Notification type.

    hipchat generate v1 token
  5. Enter a name for the token in the Label field.
  6. Click Create.

  7. Copy the generated token so you can paste it into your HipChat account configuration in elasticsearch.yml.

    hipchat copy v1 token

To configure a HipChat account that uses the v1 profile:

  1. Set the type to v1.
  2. Set auth_token to the v1 authentication token you generated.

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

bin/elasticsearch-keystore add xpack.notification.hipchat.account.notify-monitoring.secure_auth_token
xpack.notification.hipchat:
  account:
    notify-monitoring:
      profile: v1

You can also specify defaults for the message attributes.

xpack.notification.hipchat:
  account:
    notify-monitoring:
      profile: v1
      message:
        format: text
        color: blue
        notify: true
« Logging action Slack action »