OpenSearch/x-pack/docs/en/watcher/actions/slack.asciidoc

[[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 
<<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.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
                                    <<slack-dynamic-attachment, Using Attachments to Format Slack Messages>>.

| `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 {ref}/secure-settings.html[keystore] method instead.
======

You can specify defaults for the {ref}/notification-settings.html#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"
--------------------------------------------------

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