blob: e35ac6a8a7b250fda50274663cfc8cd87fcad019 [file] [log] [blame] [view]
<!--
#
# Licensed to the Apache Software Foundation (ASF) under one or more
# contributor license agreements. See the NOTICE file distributed with
# this work for additional information regarding copyright ownership.
# The ASF licenses this file to You under the Apache License, Version 2.0
# (the "License"); you may not use this file except in compliance with
# the License. You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#
-->
# Using the Slack package
The `/whisk.system/slack` package offers a convenient way to use the [Slack APIs](https://api.slack.com/).
The package includes the following actions:
| Entity | Type | Parameters | Description |
| --- | --- | --- | --- |
| `/whisk.system/slack` | package | url, channel, username | Interact with the Slack API |
| `/whisk.system/slack/post` | action | text, url, channel, username | Posts a message to a Slack channel |
Creating a package binding with the `username`, `url`, and `channel` values is suggested. With binding, you don't need to specify the values each time that you invoke the action in the package.
## Posting a message to a Slack channel
The `/whisk.system/slack/post` action posts a message to a specified Slack channel. The parameters are as follows:
- `url`: The Slack webhook URL.
- `channel`: (optional) The Slack channel to post the message to.
- `username`: The name to post the message as.
- `text`: A message to post.
- `token`: (optional) A Slack [access token](https://api.slack.com/tokens). See [below](./catalog.md#using-the-slack-token-based-api) for more detail on the use of the Slack access tokens.
The following is an example of configuring Slack, creating a package binding, and posting a message to a channel.
1. Configure a Slack [incoming webhook](https://api.slack.com/incoming-webhooks) for your team.
After Slack is configured, you get a webhook URL that looks like `https://hooks.slack.com/services/aaaaaaaaa/bbbbbbbbb/cccccccccccccccccccccccc`. You'll need this in the next step.
2. Create a package binding with your Slack credentials, the channel that you want to post to, and the user name to post as.
```
wsk package bind /whisk.system/slack mySlack \
--param url "https://hooks.slack.com/services/..." \
--param username "Bob" \
--param channel "#MySlackChannel"
```
3. Invoke the `post` action in your package binding to post a message to your Slack channel.
```
wsk action invoke mySlack/post --blocking --result \
--param text "Hello from OpenWhisk!"
```
## Using the Slack token-based API
If you prefer, you may optionally choose to use Slack's token-based API, rather than the webhook API. If you so choose, then pass in a `token` parameter that contains your Slack [access token](https://api.slack.com/tokens). You may then use any of the [Slack API methods](https://api.slack.com/methods) as your `url` parameter. For example, to post a message, you would use a `url` parameter value of [slack.postMessage](https://api.slack.com/methods/chat.postMessage).