Home

Awesome

Slack Integration Pack

Pack which allows integration with Slack service.

Configuration

Copy the example configuration in slack.yaml.example to /opt/stackstorm/configs/slack.yaml and edit as required. Note: Actions post_message and post_attachment use the same post_message_action configuration.

Note : When modifying the configuration in /opt/stackstorm/configs/ please remember to tell StackStorm to load these new values by running st2ctl reload --register-configs

Obtaining a Webhook URL

To configure a webhook and obtain a URL, go to https://[your company].slack.com/services/new/incoming-webhook, select a channel you would like the messages to be posted to and click on "Add Incoming WebHooks Integration" button.

Step 1

On the next page you will find an automatically generated webhook URL.

Step 2

Obtaining Auth Token

To obtain a token for a production use, you should follow the instructions on the following page - OAuth - User Authentication.

For testing purposes, you can use the same token as your browser based client uses.

This is a lot simpler than going through the whole oAuth flow, but because of the obvious security reasons and a temporary natural of the token, you should only use that token for testing and debugging

To do that, navigate to your Slack instance (e.g. mycompany.slack.com), open Chrome developer console, go to Network tab, filter on XHR requests and refresh the page. Find a request to file.list or a similar endpoint and in the right page, under the Requests Payload section you will see an item identified as Content-Disposition: form-data; name="token". This will contain the token that your client uses to authenticate.

Chrome developer console

Sensors

SlackSensor

Slack sensor monitors Slack for activity and dispatches a trigger for each message which is posted to a channel.

slack.message trigger

Example trigger payload:

{
    "user": {
        "first_name": "Tomaz",
        "last_name": "Muraus",
        "is_owner": false,
        "name": "kami",
        "real_name": "Tomaz Muraus",
        "is_admin": false,
        "id": "U0CCCCC"
    },
    "channel": {
        "topic": "",
        "id": "C0CCCCCC",
        "name": "test"
    },
    "timestamp": 1419164091,
    "timestamp_raw": "1419164091.00005",
    "text": "This is a test message."
}

Actions

The following actions are provided by the Slack pack.

All other actions are as documented on the Slack API Methods page.

Let's consider the chat.postMessage method. You'll notice that it lists 14 parameters. Three of the 14 parameters are required, and the remainder are optional.

You can also list the actions available in st2 using st2 action list -p slack, and get help on each action using st2 action get slack.<action>, where <action> is the name of an action. Given our above example action:

root@c603fc2f139a:/opt/stackstorm/packs.dev/slack# st2 action list -p slack
+-------------------------------+-------+--------------------------------------------------------------+
| ref                           | pack  | description                                                  |
+-------------------------------+-------+--------------------------------------------------------------+
...
| slack.chat.meMessage          | slack | This method sends a me message to a channel from the calling |
|                               |       | user.                                                        |
| slack.chat.postMessage        | slack | This method posts a message to a public channel, private     |
|                               |       | channel, or direct message/IM channel (Allows posting to any |
|                               |       | slack channel using the unique webhook url).                       |
| slack.chat.unfurl             | slack | This method attaches Slack app unfurl behavior to a          |
|                               |       | specified and relevant message.                              |
...
+-------------------------------+-------+--------------------------------------------------------------+
root@c603fc2f139a:/opt/stackstorm/packs.dev/slack# st2 action get slack.chat.postMessage
+-------------+--------------------------------------------------------------+
| Property    | Value                                                        |
+-------------+--------------------------------------------------------------+
| id          | 596d3f26cf8580020317b9ca                                     |
| uid         | action:slack:chat.postMessage                                |
| ref         | slack.chat.postMessage                                       |
| pack        | slack                                                        |
| name        | chat.postMessage                                             |
| description | This method posts a message to a public channel, private     |
|             | channel, or direct message/IM channel.                       |
| enabled     | True                                                         |
| entry_point | run.py                                                       |
| runner_type | python-script                                                |
| parameters  | {                                                            |
|             |     "username": {                                            |
|             |         "required": false,                                   |
|             |         "type": "string"                                     |
|             |     },                                                       |
|             |     "thread_ts": {                                           |
|             |         "required": false,                                   |
|             |         "type": "string"                                     |
|             |     },                                                       |
|             |     "attachments": {                                         |
|             |         "required": false,                                   |
|             |         "type": "string"                                     |
|             |     },                                                       |
|             |     "unfurl_links": {                                        |
|             |         "required": false,                                   |
|             |         "type": "string"                                     |
|             |     },                                                       |
|             |     "end_point": {                                           |
|             |         "default": "chat.postMessage",                       |
|             |         "type": "string",                                    |
|             |         "immutable": true                                    |
|             |     },                                                       |
|             |     "link_names": {                                          |
|             |         "required": false,                                   |
|             |         "type": "string"                                     |
|             |     },                                                       |
|             |     "unfurl_media": {                                        |
|             |         "required": false,                                   |
|             |         "type": "string"                                     |
|             |     },                                                       |
|             |     "parse": {                                               |
|             |         "required": false,                                   |
|             |         "type": "string"                                     |
|             |     },                                                       |
|             |     "token": {                                               |
|             |         "required": false,                                   |
|             |         "type": "string"                                     |
|             |     },                                                       |
|             |     "text": {                                                |
|             |         "required": true,                                    |
|             |         "type": "string"                                     |
|             |     },                                                       |
|             |     "icon_emoji": {                                          |
|             |         "required": false,                                   |
|             |         "type": "string"                                     |
|             |     },                                                       |
|             |     "as_user": {                                             |
|             |         "required": false,                                   |
|             |         "type": "string"                                     |
|             |     },                                                       |
|             |     "icon_url": {                                            |
|             |         "required": false,                                   |
|             |         "type": "string"                                     |
|             |     },                                                       |
|             |     "channel": {                                             |
|             |         "required": true,                                    |
|             |         "type": "string"                                     |
|             |     },                                                       |
|             |     "reply_broadcast": {                                     |
|             |         "required": false,                                   |
|             |         "type": "string"                                     |
|             |     }                                                        |
|             | }                                                            |
| notify      |                                                              |
| tags        |                                                              |
+-------------+--------------------------------------------------------------+

Notice how there are 15 parameters. The extra one is "end_point", which is used by run.py to construct the end point URL.

Uploading files with slack.files.upload

The action slack.files.upload is able to upload files to slack, such as pictures. This action works a bit different than other actions in that the file_path parameter accepts a path to a file on the local filesystem. This path must be accessible from the the st2actionrunner executing the action. The st2actionrunner will open up the file path, read the contents and then upload this data to Slack as part of the action run.

Example:

st2 run slack.files.upload file_path=/opt/data/mycoolimage.png filename=mycoolimage.png

If this is not desirabile and you would rather read the file or pass the data yourself, this can be accomplished using the file or content parameters which both accept raw data that will be uploaded.

Developer Reference

How to auto-generate actions

If you're a pack developer working on this pack and want to auto-generate / update the actions here, please see bin/README.md