[[actions-slack]]
==== Slack Action

A watch <<actions, action>> that sends messages to a https://slack.com/[Slack] team's channels or
users. To use the Slack action, you need to configure at least one 
Slack account in Watcher. For information about configuring accounts, see <<configuring-slack, 
Configuring Watcher to Send Notifications to Slack>>.

[[configuring-slack-actions]]
===== Configuring Slack Actions

You configure Slack actions in a watch's `actions` array. Action-specific attributes are
specified using the `slack` keyword.

The following snippet shows a simple slack action definition:

[source,json]
--------------------------------------------------
"actions" : {
  "notify-slack" : { 
    "transform" : { ... }, 
    "throttle_period" : "5m", 
    "slack" : {
      "to" : [ "#admins", "@chief-admin" ], <1>
      "message" : {
        "text" : "Encountered  {{ctx.payload.hits.total}} errors in the last 5 minutes (facepalm)" <2>
      }
    }
  }
}
--------------------------------------------------

<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 watch payload. 

The following snippet shows a standard message attachment.

[source,json]
--------------------------------------------------
"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"
          }
        ]
      }
    }
  }
}
--------------------------------------------------

[[slack-dynamic-attachment]]

To define an attachment template that is dynamically populated from the watch 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 
 (good or danger).
 . Defines an attachment template that references items in the list generated by the transform.

[source,json]
--------------------------------------------------
"input" : {
  "search" : {
    "request" : {
      "body" : {
        "aggs" : {
          "users_per_month" : {
            "date_histogram" : {
              "field" : "@timestamp",
              "interval" : "1m"
            }
          }
        }
      }
    }
  }
},
...
"actions" : {
  "notify-slack" : {
    "throttle_period" : "5m",
    "transform" : { 
      "script" : "return [ items : ctx.payload.hits.aggs.users_per_month.buckets.collect { [ month : it.key_as_string, count : it.doc_count, color : it.doc_count < 100 ? 'danger' : 'good' ] }]"
    },
    "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}}"
          }
        }
      }
    }
  }
}
--------------------------------------------------
<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
[options="header"]
|======
| Name                    |Required   | Description
| `from`                  | no        | The sender name to display in the 
                                        Slack message. Overrides the incoming 
                                        webhook's configured name.
| `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. 
| `icon`                  | no        | The icon to display in the Slack messages. 
                                        Overrides the incoming webhook's configured
                                        icon. Accepts a public URL to an image.
| `text`                  | yes       | The message content. 
| `attachments`           | no        | Slack message attachments. Message 
                                        attachments enable you to create more
                                        richly-formatted messages. Specified as
                                        as array as defined in the 
                                        https://api.slack.com/docs/attachments[Slack 
                                        attachments documentation].
| `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>>.

|======