This repo creates a Slack Chat App/bot that responds to messages when the app is mentioned (i.e. @<app-name>
) and sends the response to the corresponding thread.
If you want to use Slack Commands, see another repo kyhau/slack-command-app-cdk.
This Slack App can handle requests triggered from a app_mentions:read
event, which will take longer than 3 seconds to process, and posts the details back to the user using chat:write
API.
All notable changes to this project will be documented in CHANGELOG.
This repo provides the source code for building
-
A Slack Chat App/Bot with AWS API Gateway, Lambda Functions, and DynamoDB table, being deployed with CDK v2 and tested wth SAM CLI (sam-beta-cdk).
-
An OAuth 2.0 authorization flow service for sharing the Slack App with other Workspaces without registering in the public Slack App Directory. For details see "Apps distributed to multiple workspaces" in Distributing Slack apps. This stack includes an AWS API Gateway, and a Lambda Function with AWS WAF (optional).
- An API Gateway to provide an endpoint to be invoked from a Slack Command.
- A Lambda Function lambda/ImmediateResponse.py to perform authentication, some basic checks and send an intermediate response to Slack within 3 seconds (Slack requirement). This function invokes another Lambda function to to the request tasks (synchronously invocation for quick task; asynchronous invocation for long tasks).
- A Lambda Function lambda/AsyncWorker.py to perform actual operation that may take more than 3 seconds to finish.
- A Lambda Function lambda/SyncWorker.py to perform actual operation that takes less than 3 seconds to finish.
- A DynamoDB table for storing the oauth tokens of all app installations.
- CloudWatch Loggroup for API Gateway and Lambda Functions.
- An API Gateway to provide an endpoint as the Sharable URL in Slack.
- A Lambda Function lambda/OAuth.py to perform OAuth 2.0 flow and turn the auth code into access token then store it in a DynamoDB table.
- CloudWatch Loggroup for API Gateway and Lambda Functions.
To create a Slack App in Slack
- Navigate to https://api.slack.com/apps.
- Select Create New App
- Go to and go to OAuth & Permissions and at Bot Token Scopes, choose
app_mentions:read
chat:write
- Go to Event Subscriptions and enable it.
- Enter the provided API Gateway endpoint URL in the Request URL field to verify.
-
Use scripts/create_ssm_parameters.py to set up AWS SSM Parameter SecureString for storing the required secrets.
verification_token
: Verification Token from Settings | Basic Informationclient_id
: Client ID from Settings | Basic Informationclient_secret
: Client Secret from Settings | Basic Information
Prerequisites
- Install CDK v2:
npm install -g aws-cdk@next
- Install Python 3.8 or above.
- Update env_dev.json with you AWS account number and region that the Slack App is being deployed to.
- Update settings_dev.json to include the Slack domains, team IDs and channel IDs that the Slack App serves.
# Create and activate virtual env (optional)
# Install requirements
pip install -r requirements.txt
# First time
cdk bootstrap
# Or
cdk ls
cdk synth
# Deploy the stack
cdk deploy K-CDK-SlackChatApp
# Add the bot token details of the Workspace that owns the Slack Bot to the DynamoDB table.
# Only need to do this once, or whenever the bot token is changed.
export BOT_TOKEN= # <Bot User OAuth Token from Settings | OAuth & Permissions>
export ENV_STAGE=dev
./scripts/put_default_workspace_bot_token.py
# Clean up
rm -rf cdk.out package */__pycache__ */*.egg-info */out.json
- Run
@<app_name> async
- Run
@<app_name> sync
- Add
AWS::WAFv2::RuleGroup
to protect the Slack App API Gateway by specifying rules such as- ByteMatchStatement: SearchString: Slackbot 1.0 (+https://api.slack.com/robots)
- ByteMatchStatement: SearchString: team_id=TODO-slack-team-id
In order to share a Slack App with other Slack Workspaces without registering in the public Slack App Directory, you will need to deploy also the following stack of the OAuth 2.0 authorization flow service.
For details see "Apps distributed to multiple workspaces" in Distributing Slack apps.
For details of Slack OAuth 2.0 v2 see
lambda/OAuth.py also performs further authorization check with app_id
and team_id
.
-
You will need to deploy also the following stack, which will create another service for for performing the OAuth 2.0 flow and turn the auth code into access token then store the details in a AWS DynamoDB table.
cdk deploy K-CDK-SlackChatAppSharing
-
Go to api.slack.com, select your app, then
- Go to Settings | OAuth & Permissions | Redirect URLs, add the API Gateway URL of the K-CDK-SlackChatAppSharing stack. For example:
https://<api-gateway-id>.execute-api.ap-southeast-2.amazonaws.com/v1/oauth2
- Go to Settings | Manage Distribution | Activate Public Distribution
- Go to Settings | OAuth & Permissions | Redirect URLs, add the API Gateway URL of the K-CDK-SlackChatAppSharing stack. For example:
-
Ask the potential user to provide
team_id
(aka. Workspace ID)channel_id
-
Add to settings_dev.json
-
Deploy the stacks again.
-
Provide the users the Sharable URL. You can obtain this by going to Settings | Manage Distribution | Sharable URL.
-
Log in to your Slack Workspace in a browser.
-
Open the Sharable URL in the browser. You will be asked to allow the access "Add shortcuts and/or slash commands that people can use". Click Allow.
-
On success of authenticating your request with the
app_id
andteam_id
, you should see -
Then in the channel you specified in previous step, you should see
added an integration to this channel: (you-app-name)
You should be able to see this Slack App under App as well.
-
You can try
@<app_name> async
Note that your Slack Workspace may have additional restriction and require Approval from Admin on installing new Slack App. In this case, you need to talk to your Slack Workspace Admin.
python lambda/ImmediateResponse.test.py
python lambda/AsyncWorker.test.py
python lambda/SyncWorker.test.py
python lambda/OAuth.test.py
flake8 --ignore E501,F541,W605 lambda/ slack_app_constructs_cdk/ scripts/*.py
Prerequisites:
- Install sam-beta-cdk
- Start Docker
# Prepare the deployment artifacts
sam-beta-cdk build
# Invoke the function STACK_NAME/FUNCTION_IDENTIFIER
sam-beta-cdk local invoke K-CDK-SlackChatApp/K-CDK-SlackChatApp-ImmediateResponse -e tests/event_async.json
sam-beta-cdk local invoke K-CDK-SlackChatApp/K-CDK-SlackChatApp-ImmediateResponse -e tests/event_sync.json
# To start the API declared in the AWS CDK application
sam-beta-cdk local start-api
# To start a local endpoint that emulates AWS Lambda
sam-beta-cdk local start-lambda
For details of sam-beta-cdk, see https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-cdk-testing.html.
- KeyError when running
sam-beta-cdk ...
KeyError: '/home/.../lambda' Failed to execute script __main__
- Known bug: aws/aws-sam-cli#2849
- Workaround:
- Add
"@aws-cdk/core:newStyleStackSynthesis": false
into cdk.json - Add an empty requirements.txt to lambda/.
- Add