[role="xpack"] [[actions-slack]] === Slack Action Use the `slack` action to send messages to a https://slack.com/[Slack] team's channels or users. To send Slack messages, you need to <> in `elasticsearch.yml`. [[configuring-slack-actions]] ==== Configuring Slack actions You configure Slack actions in the `actions` array. Action-specific attributes are specified using the `slack` keyword. The following snippet shows a simple slack action definition: [source,js] -------------------------------------------------- "actions" : { "notify-slack" : { "transform" : { ... }, "throttle_period" : "5m", "slack" : { "message" : { "to" : [ "#admins", "@chief-admin" ], <1> "text" : "Encountered {{ctx.payload.hits.total.value}} errors in the last 5 minutes (facepalm)" <2> } } } } -------------------------------------------------- // NOTCONSOLE <1> The channels and users you want to send the message to. <2> The content of the message. [[formatting-slack-messages]] ==== Using attachments to format Slack messages In addition to sending simple text-based messages, you can use the Slack https://api.slack.com/docs/attachments[attachment] mechanism to send formatted messages. {watcher} leverages Slack attachments to enable you to dynamically populate templated messages from the execution context payload. The following snippet shows a standard message attachment: [source,js] -------------------------------------------------- "actions" : { "notify-slack" : { "throttle_period" : "5m", "slack" : { "account" : "team1", "message" : { "from" : "watcher", "to" : [ "#admins", "@chief-admin" ], "text" : "System X Monitoring", "attachments" : [ { "title" : "Errors Found", "text" : "Encountered {{ctx.payload.hits.total.value}} errors in the last 5 minutes (facepalm)", "color" : "danger" } ] } } } } -------------------------------------------------- // NOTCONSOLE [[slack-dynamic-attachment]] To define an attachment template that is dynamically populated from the payload, you specify `dynamic_attachments` in the watch action. For example, a dynamic attachment could reference histogram buckets in the payload and build an attachment per bucket. In the following example, the watch input executes a search with a date histogram aggregation and the Slack action: . Transforms the payload to a list where each item in the list holds the month, the user count for that month, and the color that represents the sentiment associated with that count (danger or bad). . Defines an attachment template that references items in the list generated by the transform. [source,js] -------------------------------------------------- "input" : { "search" : { "request" : { "body" : { "aggs" : { "users_per_month" : { "date_histogram" : { "field" : "@timestamp", "interval" : "month" } } } } } } }, ... "actions" : { "notify-slack" : { "throttle_period" : "5m", "transform" : { "script" : { "source" : "['items': ctx.payload.aggregations.users_per_month.buckets.collect(bucket -> ['count': bucket.doc_count, 'name': bucket.key_as_string, 'color': bucket.doc_count < 100 ? 'danger' : 'good'])]", "lang" : "painless" } }, "slack" : { "account" : "team1", "message" : { "from" : "watcher", "to" : [ "#admins", "@chief-admin" ], "text" : "System X Monitoring", "dynamic_attachments" : { "list_path" : "ctx.payload.items" <1> "attachment_template" : { "title" : "{{month}}", <2> "text" : "Users Count: {{count}}", "color" : "{{color}}" } } } } } } -------------------------------------------------- // NOTCONSOLE <1> The list generated by the action's transform. <2> The parameter placeholders refer to attributes in each item of the list generated by the transform. [[slack-action-attributes]] ==== Slack action attributes [cols=",^,", options="header"] |====== | Name |Required | Description | `message.from` | no | The sender name to display in the Slack message. Overrides the incoming webhook's configured name. | `message.to` | yes | The channels and users you want to send the message to. Channel names must start with `#` and user names must start with `@`. Accepts a string value or an array of string values. | `message.icon` | no | The icon to display in the Slack messages. Overrides the incoming webhook's configured icon. Accepts a public URL to an image. | `message.text` | yes | The message content. | `message.attachments` | no | Slack message attachments. Message attachments enable you to create more richly-formatted messages. Specified array as defined in the https://api.slack.com/docs/attachments[Slack attachments documentation]. | `message.dynamic_attachments` | no | Slack message attachments that can be populated dynamically based on the current watch payload. For more information, see <>. | `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`) |====== [[configuring-slack]] ==== Configuring Slack Accounts You configure the accounts {watcher} can use to communicate with Slack in the `xpack.notification.slack` namespace in `elasticsearch.yml`. You need a https://api.slack.com/incoming-webhooks[Slack webhook URL] to configure a Slack account. To create a webhook URL, set up an an _Incoming Webhook Integration_ through the Slack console: . Log in to http://slack.com[slack.com] as a team administrator. . Go to https://my.slack.com/services/new/incoming-webhook. . Select a default channel for the integration. + image::images/slack-add-webhook-integration.jpg[] . Click *Add Incoming Webhook Integration*. . Copy the generated webhook URL so you can paste it into your Slack account configuration in `elasticsearch.yml`. + image::images/slack-copy-webhook-url.jpg[] To configure a Slack account, at a minimum you need to specify the account name and webhook URL in the {es} keystore (see {ref}/secure-settings.html[secure settings]): [source,shell] -------------------------------------------------- bin/elasticsearch-keystore add xpack.notification.slack.account.monitoring.secure_url -------------------------------------------------- [WARNING] ====== You can no longer configure Slack accounts using `elasticsearch.yml` settings. Please use {es}'s secure <> method instead. ====== You can specify defaults for the <>: [source,yaml] -------------------------------------------------- xpack.notification.slack: account: monitoring: message_defaults: from: x-pack to: notifications icon: http://example.com/images/watcher-icon.jpg attachment: fallback: "X-Pack Notification" color: "#36a64f" title: "X-Pack Notification" title_link: "https://www.elastic.co/guide/en/x-pack/current/index.html" text: "One of your watches generated this notification." mrkdwn_in: "pretext, text" -------------------------------------------------- If you configure multiple Slack accounts, you either need to configure a default account or specify which account the notification should be sent with in the <> action. [source,yaml] -------------------------------------------------- xpack.notification.slack: default_account: team1 account: team1: ... team2: ... --------------------------------------------------