[role="xpack"]
[[actions-slack]]
=== {watcher} Slack Action
++++
<titleabbrev>Slack action</titleabbrev>
++++

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 
<<configuring-slack,configure at least one Slack account>> 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}} 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}} 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
                                    <<slack-dynamic-attachment>>.

| `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 Slack App with the https://api.slack.com/messaging/webhooks[Incoming Webhooks feature] 
to configure a Slack account. Use the generated webhook URL to set up your Slack account in {es}.

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 <<secure-settings,keystore>> method instead.
======

You can specify defaults for the
<<slack-account-attributes,Slack notification attributes>>:

[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"
--------------------------------------------------

To notify multiple channels, create a webhook URL for each channel in Slack 
and multiple Slack accounts in {es} (one for each webhook URL).

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
<<actions-slack,`slack`>> action. 

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