Configuring Watcher to Send Messages to HipChat
editConfiguring Watcher to Send Messages to HipChat
editYou 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.
Configuring HipChat Accounts
editYou 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:
- 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 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 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:
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.
Using the HipChat Integration Profile
editYou 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
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 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. To notify a particular HipChat user, create an account
that uses the 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 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.
- Select the Send Notification scope.
- Click Create.
-
Copy the generated token so you can paste it into your HipChat account configuration in
elasticsearch.yml
.
To configure a HipChat account that uses the integration
profile, you must:
-
Set the
type
tointegration
. -
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.
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.
Using the HipChat User Profile
editYou 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.
- 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
.
To configure a HipChat account that uses the user
profile, you must:
-
Set the
type
touser
. -
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.
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.
Using the HipChat v1 Profile
editYou 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
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. To notify a particular HipChat user, create an account
that uses the 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.
- 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
.
To configure a HipChat account that uses the user
profile, you simply:
-
Set the
type
tov1
. -
Set
auth_token
to the v1 authentication token you generated.
For example, the following snippet configures an account called notify-monitoring
:
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
editName |
Required |
Default |
Description |
|
yes |
- |
The HipChat account profile to use:
|
|
yes |
- |
The authentiation token to use to access the HipChat API. |
|
no |
api.hipchat.com |
The HipChat server hostname. |
|
no |
443 |
The HipChat server port number. |
|
no |
_ |
The room you want to send messages to.
Must be specified if the |
`user ` |
no |
- |
The HipChat user account to use to send
messages. Specified as an email
address. Must be specified if the
|
|
no |
|
The format of the message: |
|
no |
|
The background color of the notification in the room |
|
no |
|
Indicates whether people in the room should be actively notified |