Slack gateway for for Amazon Q Business

⚡ If you have created a new Amazon Q Business application on or after April 30th, 2024, you will not be able to set up a Slack or Microsoft Teams gateway using the instructions provided below. This is because new Amazon Q Business applications require integration with IAM Identity Center. We are currently working on updating the CloudFormation (CFN) template and the necessary steps to accommodate the setup of these gateways for new applications created since April 30th, 2024 with an expected completion date by May 30th, 2024.

See AWS Blog post: Deploy a Slack gateway for Amazon Q, your business expert

Amazon Q is a new generative AI-powered application that helps users get work done. Amazon Q can become your tailored business expert and let you discover content, brainstorm ideas, or create summaries using your company’s data safely and securely. For more information see: Introducing Amazon Q, a new generative AI-powered assistant (preview)

In this repo we share a project which lets you use Amazon Q's generative AI to enable Slack channel members to access your organizations data and knowledge sources via conversational question-answering. You can connect to your organization data via data source connectors and integrate it with Slack Gateway for Amazon Q to enable access to your Slack channel members. It allows your users to:

• Converse with Amazon Q using Slack Direct Message (DM) to ask questions and get answers based on company data, get help creating new content such as emails, and performing tasks.
• You can also invite it to participate in your team channels.
  • In a channel users can ask it questions in a new message, or tag it in a thread at any point. Get it to provide additional data points, resolve a debate, or summarize the conversation and capture next steps.

It's amazingly powerful. Here's a demo - seeing is believing!

AmazonQSlackGatewayDemo.mp4

It's easy to deploy in your own AWS Account, and add to your own Slack Workspace. We show you how below.

Features

• In DMs it responds to all messages
• In channels it responds only to @mentions, and always replies in thread
• Renders answers containing markdown - e.g. headings, lists, bold, italics, tables, etc.
• Provides thumbs up / down buttons to track user sentiment and help improve performance over time
• Provides Source Attribution - see references to sources used by Amazon Q
• Aware of conversation context - it tracks the conversation and applies context
• Aware of multiple users - when it's tagged in a thread, it knows who said what, and when - so it can contribute in context and accurately summarize the thread when asked.
• Process up to 5 attached files for document question answering, summaries, etc.
• Reset and start new conversation in DM channel by using /new_conversation

This sample Amazon Q slack application is provided as open source — use it as a starting point for your own solution, and help us make it better by contributing back fixes and features via GitHub pull requests. Explore the code, choose Watch to be notified of new releases, and check back for the latest updates.

Follow the instructions below to deploy the project to your own AWS account and Slack workspace, and start experimenting!

Deploy the solution

Prerequisites

You need to have an AWS account and an IAM Role/User with permissions to create and manage the necessary resources and components for this application. (If you do not have an AWS account, please see How do I create and activate a new Amazon Web Services account?)

You also need to have an existing, working Amazon Q application. If you haven't set one up yet, see Creating an Amazon Q application

1. Deploy the stack

We've made this easy by providing pre-built AWS CloudFormation templates that deploy everything you need in your AWS account.

If you are a developer, and you want to build, deploy and/or publish the solution from code, we've made that easy too! See Developer README

1. Log into the AWS console if you are not already.
2. Choose one of the Launch Stack buttons below for your desired AWS region to open the AWS CloudFormation console and create a new stack.
3. Enter the following parameters:
   1. Stack Name: Name your App, e.g. AMAZON-Q-SLACK-GATEWAY.
   2. AmazonQAppId: Your existing Amazon Q Application ID (copy from Amazon Q console).
   3. AmazonQRegion: Choose the region where you created your Amazon Q Application.
   4. AmazonQUserId: (Optional) Amazon Q User ID email address (leave empty to use Slack users email as user Id)
   5. ContextDaysToLive: Just leave this as the default (90 days)

Region	Easy Deploy Button	Template URL - use to upgrade existing stack to a new release
N. Virginia (us-east-1)		https://s3.us-east-1.amazonaws.com/aws-ml-blog-us-east-1/artifacts/amazon-q-slack-gateway/AmazonQSlackGateway.json
Oregon (us-west-2)		https://s3.us-west-2.amazonaws.com/aws-ml-blog-us-west-2/artifacts/amazon-q-slack-gateway/AmazonQSlackGateway.json

When your CloudFormation stack status is CREATE_COMPLETE, choose the Outputs tab, and keep it open - you'll need it below.

2. Configure your Slack application

2.2 Create your app

Now you can create your new app in Slack!
NOTE: If you have deployed the Slack data source connector for Amazon Q you may already have an existing Slack app installed. Do not attempt to modify that data source connector app - create a new app instead.

1. Create a Slack app: https://api.slack.com/apps from the generated manifest - copy / paste from the stack output: SlackAppManifest.
2. Go to App Home, scroll down to the section Show Tabs and enable Message Tab then check the box Allow users to send Slash commands and messages from the messages tab - This is a required step to enable your user to send messages to your app

2.3 Add your app in your workspace

Let's now add your app into your workspace, this is required to generate the Bot User OAuth Token value that will be needed in the next step

1. Go to OAuth & Permissions (in api.slack.com) and click Install to Workspace, this will generate the OAuth token
2. In Slack, go to your workspace
3. Click on your workspace name > Tools and settings > Manage apps
4. Click on your newly created app
5. In the right pane, click on "Open in App Directory"
6. Click "Open in Slack"

3. Configure your Secrets in AWS

Let's configure your Slack secrets in order to (1) verify the signature of each request, (2) post on behalf of your bot

IMPORTANT In this example we are not enabling Slack token rotation. Enable it for a production app by implementing rotation via AWS Secrets Manager. Please create an issue (or, better yet, a pull request!) in this repo if you want this feature added to a future version.

1. Login to your AWS console
2. In your AWS account go to Secret manager, using the URL shown in the stack output: SlackSecretConsoleUrl.
3. Choose Retrieve secret value
4. Choose Edit
5. Replace the value of Signing Secret^* and Bot User OAuth Token, you will find those values in the Slack application configuration under Basic Information and OAuth & Permissions. ^*(Pro tip: Be careful you don't accidentally copy 'Client Secret' (wrong) instead of 'Signing Secret' (right)!)

Say hello

Time to say Hi!

1. Go to Slack
2. Under Apps > Manage, add your new Amazon Q app
3. Optionally add your app to team channels
4. In the app DM channel, say Hello. In a team channel, ask it for help with an @mention.
5. Enjoy.

Contributing, and reporting issues

We welcome your contributions to our project. Whether it's a bug report, new feature, correction, or additional documentation, we greatly value feedback and contributions from our community.

See CONTRIBUTING for more information.

Security

See Security issue notifications for more information.

License

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