Slack Responder user guide - snowplow-archive/sauna GitHub Wiki

HOME > GUIDE FOR ANALYSTS > RESPONDERS > SLACK RESPONDER USER GUIDE

This responder has not yet been implemented.

See also: Slack Responder setup guide

• 1. Overview
• 2. Responder actions
  • 2.1 Send message (real-time)
    • 2.1.1 Overview
    • 2.1.2 Command format
    • 2.1.3 Example commands
    • 2.1.4 Response algorithm
    • 2.1.5 Usage examples
      • 2.1.5.1 Kinesis stream

This responder lets you communicate with your team via the Slack messaging platform.

Currently this responder only supports one action:

This responder command lets you send a message to a Slack channel or user. The command uses Slack's message format for webhooks and supports optional message attachments.

Like all real-time responder actions, this action is triggered by a well-structured JSON command being received by a compatible observer.

The command must be configured using a self-describing JSON Schema which validates against this schema:

iglu:com.slack.sauna.commands/send_message/jsonschema/1-0-0

Here is a simple example command:

{
  "schema": "iglu:com.slack.sauna.commands/send_message/jsonschema/1-0-0",

  "data": {
    "channel": "#devops",
    "username": "sauna-bot",
    "icon_emoji": ":rocket:",
    "text": "This message appears in #devops and comes from *sauna-bot*!"
  }
}

Where:

• channel is the channel to send the message to - if set, this overrides the default channel set in the webhook's configuration. Users are also considered channels, i.e. "channel": "@TheUser" will send a direct message to TheUser
• username is the username used by the webhook. If set, this also overrides the default setting
• icon_emoji is an emoji used as the webhook's avatar. If set, this also overrides the default setting. Alternatively, icon_url can be used to link to an external image
• text is the body of the message. Slack messages support various formatting options

The responder also supports Slack attachments - optional footers containing richly formatted text, links and images. To add an attachment to your message, simply add an attachments array to your command's data containing one or more attachments - for instance,

{
  "schema": "iglu:com.slack.sauna.commands/send_message/jsonschema/1-0-0",

  "data": {
    "username": "sauna-bot",
    "icon_emoji": ":rocket:",
    "attachments": [
      {
        "fallback": "Awesome Project build failing! [ReferenceError - UI is not defined]",
        "color": "danger",
        "title": "Build failing!",
        "text": "<https://example.com|ReferenceError> - UI is not defined",
        "fields": [
          {
            "title": "Project",
            "value": "Awesome Project",
            "short": true
          },
          {
            "title": "Changeset",
            "value": "<https://example.com|d190bf4>", 
            "short": true
          }
        ]
      }
    ]
  }
}

Where:

• fallback is required alt text to be shown in clients that don't support attachments.
• color is the color of the border along the left side of the message attachment - this can be one of good/warning/danger or any hex color code.
• text is the attachment's contents - these can be formatted using Markdown-like syntax, similar to message bodies.
• title is the attachment's title - larger, bold text displayed in the message's header.
• fields is an array of small key/value pairs that will be displayed as a table in the attachment. These pairs can contain three fields:
  • title - the field's heading; automatically bolded, does not support markup.
  • value - the field's value; can contain standard markup.
  • short - an optional flag; if set to true, a field will be displayed inline alongside other fields.

This message will look as follows:

Sauna will take each command and:

1. Validate it as a valid send message command
2. If it is not valid, this will be reported to any configured Sauna loggers
3. If it is valid, Sauna will attempt to send the notification using a Slack webhook specified in the responder's configuration
4. If the API reports success, this will be reported to any configured Sauna loggers
5. If the API reports failure, this will be reported to any configured Sauna loggers but no retry will be attempted

In the case of failure, we do not attempt retry, even in the case of us temporarily exceeding API rate limits, because this could block other non-Slack-related commands in the observed stream from executing.

Assuming that the Amazon Kinesis Observer receives the following command:

{
  "schema": "iglu:com.snowplowanalytics.sauna.commands/command/jsonschema/1-0-0",

  "data": {
    "envelope": {
      "schema": "iglu:com.snowplowanalytics.sauna.commands/envelope/jsonschema/1-0-0",
      "data": {
        "commandId": "9dadfc92-9311-43c7-9cee-61ab590a6e81",
        "whenCreated": "2017-01-02T19:14:42Z",
        "execution": {
          "semantics": "AT_LEAST_ONCE",
          "timeToLive": null
        },
        "tags": {}
      }
    },
    "command": {
      "schema": "iglu:com.slack.sauna.commands/send_message/jsonschema/1-0-0",
      "data": {
        "channel": "#devops",
        "username": "sauna-bot",
        "icon_url": "https://slack-assets2.s3-us-west-2.amazonaws.com/f5d6f/img/emoji_2016_06_08/apple/1f680.png",
        "text": "This message appears in #devops and comes from *sauna-bot*!"
      }
    }
  }
}

And assuming that the current time is within 20 minutes (1,200,000 ms) of 2017-01-02T19:14:42Z, then:

• Sauna will use a Slack webhook to send a message to #devops that will look as follows:

• Whether or not the notification was successfully sent by Slack wil be reported to any configured Sauna loggers.