Amazon Interactive Slack App Starter Kit

This starter kit will help you started with building an interactive Slack app leveraging CDK. More details about why to use the solution in this repository may be found in this blog post.

This README will guide you to configure this solution with your own AWS account.

Table of Contents

• Architecture
• Prerequisites
• Deployment Instructions
  • 1. Request Slack App Token
  • 2. Clone this repository
  • 3. Bootstrap AWS Environment
  • 4. Build and deploy serverless resources
  • 5. Configure resources with Slack App secrets and Slack users
  • 6. Register slash command to invoke Slack App
  • 7. Register Interactivity URL (pointing to API Gateway)
• Testing Instructions
• Destroying Resources
• Useful Commands
• Security
• License

Architecture

Prerequisites

• AWS CDK version 2.19.0 or later
• Node version 16+
• Docker-cli
• Git
• A personal or company Slack account with permissions to create applications
• The Slack Channel ID of a channel in your Workspace for integration with the Slack App

  • To get the Channel ID, open the context menu on the Slack channel and select View channel details. The modal displays your Channel ID at the bottom:

    

    

    To learn more, visit Slack's Getting Started with Bolt for JavaScript page.

---

Deployment Instructions

1. Request Slack App Token

To create the Slack App within your Slack Workspace, navigate to Slack's Your Apps page and choose the Create New App button.

Select the From scratch option within the Create an app dialog:

Enter a name for your Slack App and your Workspace, then choose Create App:

You see the configuration page for your new Slack App.

To add permissions to your Slack App using OAuth scopes, navigate to the OAuth & Permissions sidebar and scroll to the Bot Token Scopes section. Choose Add an OAuth Scope and add the chat:write and commands OAuth scopes.

Install the Slack App to your Workspace to generate a Slack Bot token. Navigate to the Basic Information sidebar, then choose Install to Workspace.

From the Application installation verification page, choose Allow to complete the installation.

After installation, the configuration page for your Slack App shows a Success banner. Navigate back to the OAuth & Permissions sidebar to view your Slack App token.

To learn more about Token Types, visit Slack's Access tokens page.

2. Clone this repository

From a command prompt on your computer, clone this repository in a directory of your choice:

git clone https:/aws-samples/amazon-interactive-slack-app-starter-kit.git

Within the /lib directory, the app-stack.ts file outlines all the resources to be deployed. Additionally, using NodeJsFunction resources enables full TypeScript transpiling and bundling for a Lambda function.

Download the project dependencies using the NPM install command:

npm install

3. Bootstrap AWS Environment

Before you deploy the CDK resources to your AWS account, bootstrap the AWS environment in the AWS Region of your choice with this command:

cdk bootstrap

By running the preceding command, you prepare your AWS account and AWS Region with resources to perform deployments. You only need to bootstrap your AWS account and AWS Region once.

4. Build and deploy serverless resources

Now that you have the code base cloned and the AWS environment configured, it’s time to deploy the AWS resources.

You will run the following command from the root of the project to start the deployment. Ensure you have docker running as it will bundle your Lambda resources.

cdk deploy

Note: You may specify a target Region using the argument --region <region_name>

You must accept the security changes being made to your account because of the new resources being deployed.

Once the deployment completes, observe the output from cdk deploy which looks like:

AmazonInteractiveSlackAppStarterKitStack: creating CloudFormation changeset...

 ✅  AmazonInteractiveSlackAppStarterKitStack

✨  Deployment time: 158.28s

Outputs:
AmazonInteractiveSlackAppStarterKitStack.SlackAppApiEndpointXXXX = https://XXXXXXXX.execute-api.us-east-1.amazonaws.com/prod/
Stack ARN:
arn:aws:cloudformation:us-east-1:XXXXXXXXXX:stack/AmazonInteractiveSlackAppStarterKitStack/123e4567-e89b-12d3-a456-426652340000

✨  Total time: 173.81s

Note: Record the API Gateway URL generated from your deployment as it is needed for registration with the Slack App configuration later on.

5. Configure resources with Slack App secrets and Slack users

With the CDK resources deployed, you need to configure the newly generated SSM Parameter and Secrets Parameter with your specific application values.

To update the SSM Parameter containing the Slack channel ID, perform the following steps:

1. Go to the Parameter Store console for your Region

2. Choose the parameter with the name SlackChannelIdParameter

3. Choose the Edit button

4. Enter your Channel ID from the prerequisites section into the Value text field.

5. Choose the Save changes button

Next, you must update the Secrets Parameter containing the OAuth token and signing secret for your Slack app using the following steps:

1. Go to the Secrets Manager console for your Region

2. Choose the secret starting with SlackSecretsXXXXXXXX

3. Select the Retrieve secret value button to reveal the secret’s details

4. Choose the Edit button

5. Select the Plaintext tab, and enter the following value. Be sure to substitute your own values where appropriate

   {"signingSecret":"<your_signing_secret>","botToken":"<your_bot_token>"}

6. Choose the Save button after finishing with your changes

Lastly, configure your slack user to have permissions to invoke the Slack App.

To configure your Slack user, proceed with the following steps:

1. Navigate to your account settings for your organization’s Slack account. The URL will look like:

   https://<your-organization>.slack.com/account/settings#username

2. Copy the value under Username as this is needed in the next few steps

3. Go to DynamoDB Tables console and be sure to choose the correct Region to which you deployed your resources.

4. Choose the AmazonInteractiveSlackAppStarterKitStack-BotUsersTableXXXXXXX

5. Select the Explore table items button

6. Select the Create item button

7. Choose the JSON view option in the top right corner

8. In the Attributes text entry, provide the following. Be sure to substitute your own values where appropriate.

   {
     "slackUserName": "<your_slack_username>",
     "permittedActions": [
       "sample-lambda",
       "sample-sm"
     ]
   }

9. To save, choose the Create item button

Your Slack user now has the permissions to run commands to invoke the Slack App.

6. Register slash command to invoke Slack App

Now, you must create an entry point for your Slack App by registering a Slash Command for your Slack App. The Slash Command is a keyword which informs Slack to invoke a specific function of your backend application. For this exercise, register the Slash Command, /my-slack-bot.

To register the /my-slack-bot Slash Command, navigate to the Application Configuration page for your Slack App:

https://api.slack.com/apps > My Slack Bot.

Go to the Slash Commands sidebar, then choose the Create New Command button:

Complete the Create New Command registration form. For the text field labeled Request URL, enter the API Gateway URL created from the deployment of your serverless resources from the preceding section. Note that this URL must follow the pattern https://<apigw-id>.execute-api.<aws-region>.amazonaws.com/<stage>/slack/events, as the Slack Bolt SDK binds to the /slack/events endpoint:

Once completed, select the Save button. Upon creation, your browser is returned to the Slash Commands configuration page for your Slack App with a Success banner at the top of the page:

To learn more about Slash Commands, visit Slack's Enabling interactivity with Slash Commands page.

7. Register Interactivity URL (pointing to API Gateway)

With the entry point for your Slack App configured, you must now configure your Slack workspace to interact with your backend application. Since your Slack App supports actions beyond the invocation stage, you need to inform Slack to direct subsequent interactivity to the backend. You must register your backend API with your Slack App's Interactivity & Shortcuts configuration.

Navigate to the Application Configuration page for your Slack App:

https://api.slack.com/apps > My Slack Bot.

Go to the Interactivity & Shortcuts sidebar and enable interactivity by choosing the Interactivity toggle:

For the text field labeled Request URL, enter the API Gateway URL created from the deployment of your serverless resources. Note that this URL must follow the pattern https://<apigw-id>.execute-api.<aws-region>.amazonaws.com/<stage>/slack/events, as the Slack Bolt SDK binds to the /slack/events endpoint:

Once entered, choose the Save Changes button. Upon creation, a Success banner appears at the top of the page.

Testing Instructions

1. Start the Slack App by invoking the /my-slack-bot slash command

   

2. From the My Slack Bot action menu, select Sample Lambda

   

3. Enter command input, select Submit button, then observe the response (this input value applies to the sample Lambda function)

   

4. Observe the execution output posted to the Slack channel

   

Note: You can test the State Machine execution by selecting Sample State Machine in step #2

Destroying Resources

To avoid additional charges to your account, run the following command from the project’s root directory:

cdk destroy

CDK prompts you to confirm if you want to delete the resources. Enter “y” to confirm. The process removes all the resources created.

---

Useful Commands

• npm run build compile typescript to js
• npm run watch watch for changes and compile
• npm run test perform the jest unit tests
• cdk deploy deploy this stack to your default AWS account/region
• cdk diff compare deployed stack with current state
• cdk synth emits the synthesized CloudFormation template
• cdk destroy removes all stack resources

Security

See CONTRIBUTING for more information.

License

This library is licensed under the MIT-0 License. See the LICENSE file.