{"id":24334298,"url":"https://github.com/aws-samples/multi-interface-chatbot-using-amazon-q-and-slack-with-cloudfront-clickable-references","last_synced_at":"2025-07-31T05:09:18.820Z","repository":{"id":271942077,"uuid":"904448432","full_name":"aws-samples/Multi-Interface-Chatbot-using-Amazon-Q-and-Slack-with-CloudFront-Clickable-References","owner":"aws-samples","description":"This app is a RAG (Retrieval Augmented Generation) chatbot that uses Amazon Q and Slack as it interface. It also provides a CloudFront links whenever it provides a source.","archived":false,"fork":false,"pushed_at":"2025-01-10T21:39:45.000Z","size":950,"stargazers_count":9,"open_issues_count":1,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-06-05T08:20:15.683Z","etag":null,"topics":["amazon-q","amazon-q-business","amazon-web-services","api-gateway","aws","bedrock","cdk","chatbot","cloudfront","kendra","lambda","rag","retrieval-augmented-generation","slack","spack"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit-0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aws-samples.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-12-16T22:59:52.000Z","updated_at":"2025-05-30T16:22:27.000Z","dependencies_parsed_at":"2025-01-10T22:39:01.123Z","dependency_job_id":"c2a1bcec-8dd8-438c-b6d4-15fa77b995cf","html_url":"https://github.com/aws-samples/Multi-Interface-Chatbot-using-Amazon-Q-and-Slack-with-CloudFront-Clickable-References","commit_stats":null,"previous_names":["aws-samples/multi-interface-chatbot-using-amazon-q-and-slack-with-cloudfront-clickable-references"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/aws-samples/Multi-Interface-Chatbot-using-Amazon-Q-and-Slack-with-CloudFront-Clickable-References","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws-samples%2FMulti-Interface-Chatbot-using-Amazon-Q-and-Slack-with-CloudFront-Clickable-References","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws-samples%2FMulti-Interface-Chatbot-using-Amazon-Q-and-Slack-with-CloudFront-Clickable-References/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws-samples%2FMulti-Interface-Chatbot-using-Amazon-Q-and-Slack-with-CloudFront-Clickable-References/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws-samples%2FMulti-Interface-Chatbot-using-Amazon-Q-and-Slack-with-CloudFront-Clickable-References/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aws-samples","download_url":"https://codeload.github.com/aws-samples/Multi-Interface-Chatbot-using-Amazon-Q-and-Slack-with-CloudFront-Clickable-References/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws-samples%2FMulti-Interface-Chatbot-using-Amazon-Q-and-Slack-with-CloudFront-Clickable-References/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267989018,"owners_count":24177020,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-31T02:00:08.723Z","response_time":66,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["amazon-q","amazon-q-business","amazon-web-services","api-gateway","aws","bedrock","cdk","chatbot","cloudfront","kendra","lambda","rag","retrieval-augmented-generation","slack","spack"],"created_at":"2025-01-18T04:15:19.728Z","updated_at":"2025-07-31T05:09:18.791Z","avatar_url":"https://github.com/aws-samples.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Multi-interface chatbot using Amazon Q and Slack with CloudFront clickable sources \n\n## Introduction:\nThis application is an AI-powered chatbot designed to help users navigate and utilize the [Spack package manager tool](https://spack.io/). \nThis innovative chatbot that employs Retrieval-Augmented Generation (RAG) technology to provide responses \nto user queries and can be interacted with both in Slack and Amazon Q. This solution can be applied to a variety of \nuse cases that require knowledge integration to a chatbot. The two main selling points of this solution is: \n(1) having the ability to interact with the chatbot in two mediums and (2) being able to show sources in websites and \ndocuments in an S3 bucket via CloudFront.\n\n## Notable Features:\n* Slackbot and Amazon Q both share the same vector database reducing solution complexity and cost.\n* Both Slackbot and Amazon Q bot provides clickable links to its sources for generating answers in their responses:\n  * https://spack-tutorial.readthedocs.io/en/latest/index.html\n  * Text files (`docuemnts/slack/*.txt`) uploaded to S3 bucket via CloudFront distribution\n* Automated updates of both data sources.\n* Dashboard for tracking bot invocations for Slack and Amazon Q:\n  * Aws Console -\u003e Amazon Q Business -\u003e Radiuss -\u003e Analytics dashboard\n  * Aws Console -\u003e Cloudformation -\u003e Stacks -\u003e SlackStack -\u003e Outputs -\u003e AmazonQCloudwatchDashboardOutput\n\n## Architecture:\n![diagram](./assets/radiuss.drawio.png)\n\n### Stacks:\n* Data Stack:\n  * A) Documentation Data\n    1. `Documentation Processing Lambda` pulls in data from `Raw Documentation Bucket` and does the following:\n       * Converts `.rst` files into markdown. \n       * Splits the markdown text based on its title\n       * Generates [metadata files](https://docs.aws.amazon.com/kendra/latest/dg/s3-metadata.html) that will be used by kendra. The metadata files contains the following attributes:\n         * title: section title from data split \n         * data_source: `documentation`\n         * _source_uri: URL from the documentation which is `https://spack.readthedocs.io/en/latest/` + file name + \"#\" + section title  \n    2. `Documentation Processing Lambda` saves the split markdown and the metadata files into `Processed Documentation Bucket`.\n    3. `Documentation Processing Lambda` triggers a kendra data source sync job to crawl the `Processed Documentation Bucket`.\n  * B) Slack Data\n    Slack Processing Lambda:\n    1. `Slack Processing Lambda` pulls in data from `Raw Slack Bucket` which contains historical Slack data and does the following:\n       * Generates [metadata files](https://docs.aws.amazon.com/kendra/latest/dg/s3-metadata.html) that will be used by kendra. The metadata files contains the following attributes:\n         * title: section title from data split \n         * data_source: `slack`\n         * _source_uri: generated CloudFront URL from the `Raw Slack Bucket`\n    2. `Slack Processing Lambda` saves historical slack data and the metadata files into `Processed Slack Bucket`.\n    3. `Slack Processing Lambda` triggers a kendra data source sync job to crawl the `Processed Slack Bucket`.\n    4. `Raw Slack Bucket` data is passed into a CloudFront distribution for public access.\n    Slack Ingest Lambda:\n    0. `Slack Ingest Lambda` is triggered by event bridge daily.\n    1. `Slack Ingest Lambda` pulls in the past 24 hours conversation from slackdata from slack and writes it to Raw slack data\n    2. `Slack Ingest Lambda` saves conversation data into `Processed Slack Bucket` together with its metadata.\n    3. `Slack Processing Lambda` triggers a kendra data source sync job to crawl the `Processed Slack Bucket`.\n    4. `Processed Slack Bucket` data is passed into a CloudFront distribution for public access.\n  \n* Amazon Q Stack: [Amazon Q Business](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/what-is.html) is a fully managed, \ngenerative-AI powered assistant tailored for this use case to answer questions based on the data from the data stack.\n1. `Identity Center` - Provides authentication to Amazon Q.\n2. `Kendra` provides context to the responses via semantic search and sources.\n3. `Cloudfront` links are provided by kendra and propagates to the responses of Amazon Q.\n4. `Public Docs` links are provided by kendra and propagates to the responses of Amazon Q.\n5. Invocations are logged in a `Cloudwatch` Dashboard.\n\n* Slack\n  * A) Answering Questions\n    1. Slack app invokes `API Gateway` with the question as a part of the payload. \n    2. `API Gateway` invokes `Slackbot Lambda`.\n    3. `Slackbot Lambda` pulls Slack token from `Secrets Manager`.\n    4. `Slackbot Lambda` pulls Slack parameters for responses from `SSM Parameter Store`.\n    4. `Kendra` is queried with the question and responds with relevant passages and sources from documentation and slack data from `Cloudfront`.\n    5. Public docs are returned as part of the response if the chatbot used it as a source.\n    6. Slack data via `Cloudfront` are returned as part of the response if the chatbot used it as a source.\n  * B) Reporting\n    0. `Metrics Lambda` is triggered every day at 0:00 UTC\n    1. Everytime the `Slackbot Lambda` is triggered it is captured in `Cloudwatch` as a metric.\n    2. `Metrics Lambda` pulls daily data from `Cloudwatch`\n    3. `Metrics Lambda` pulls Slack token from `Secrets Manager`\n    4. `Metrics Lambda` pulls slack parameters for responses from `SSM Parameter Store`\n    5. `Metrics Lambda` send message on slack with daily report\n\n## Deploying the Solution:\n### Requirements:\n * Active AWS account\n * Docker\n * [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)\n * [Slack workspace](https://slack.com/help/articles/206845317-Create-a-Slack-workspace)\n   * `Parent Channel`: Public [Slack Channel](https://slack.com/help/articles/201402297-Create-a-channel) where users will be interacting with the slack chatbot.\n   * `Child Channel`: Private [Slack Channel](https://slack.com/help/articles/201402297-Create-a-channel) where metrics report will be sent to.\n * If building from an arm based machine (Apple M series) change the parameter for `architecutre` in `documentation_processing_lambda` in `stacks/data.py` to `lambda_.Architecture.ARM_64`. \n\n### Step 1: Account Set-up\n * Ensure [Bedrock model access](https://docs.aws.amazon.com/bedrock/latest/userguide/model-access-modify.html) for `anthropic.claude-v2:1`\n * Enable [IAM identify Center](https://docs.aws.amazon.com/singlesignon/latest/userguide/get-set-up-for-idc.html) for your account.\n\n### Step 2: Install project dependencies\n```bash\npip install -r requirements.txt\n```\n\n### Step 3: Bootstrap Account (Skip if done previously)\n```bash\ncdk bootstrap\n```\n\n### Step 4: Synthesize CDK App\n```bash\ncdk synth\n```\n\n### Step 5: Deploy AWS infrastructure\n```bash\ncdk deploy --all\n```\n\n### Step 6: Slack Set-up\n1. Create a Slack app: \n* Go to: https://api.slack.com/apps \n* Select `Create an App`\n* Select `From a manifest`\n  1. Select `Spack` workspace \n  2. Select `YAML` tab and copy the contents of the [app manifest](spackbot_manifest.yml) and select `Next` \n  3. Select `Create`\n\n2. Install App\n * On the left pane, under settings select `Install App`\n * Select `Install to \u003cworkspace\u003e`\n * Select `Allow`\n\n3. Copy Bot User OAuth Token\n\n![slack_token](./images/copy_slack_bot_token.png)\n\n* Go to: AWS Console -\u003e AWS Secrets Manager -\u003e Secrets -\u003e SlackAccessKey### -\u003e Overview -\u003e Retrieve Secret Value -\u003e Edit\n* Paste value where it says `place-holder-access-key`\n* Click `Save`\n\n4. Enter endpoint (One app is finished deploying from Step 1) \n* Got to: AWS Console -\u003e Cloudformation -\u003e Stacks -\u003e SlackStack -\u003e Outputs -\u003e SlackBotEndpointOutput (copy Value)\n* Enable events\n\n![install_app](./images/enable_event_subscription_on_slack_application.png)\n\n* Paste value under `Request URL`\n\n![install_app](./images/verify_event_subscription_on_slack_application.png)\n* On the bottom right of the screen select `Save Changes`\n\n5. Invite bot to channels (Parent and Child):\n* Select the channel\n* On the upper right next to huddle click on the three dots.\n* Select `edit settings`\n* Go to `integrations` tab\n* Select `Add an app`\n* Under the `In your workspace` tab select add the chatbot\n\n6. Enter Slack workspace information:\n\nObtain the following information from slack:\n* Parent channel ID\n* Child channel ID\n\nNote: To obtain channel id, right-click the channel -\u003e View Channel Details -\u003e About -\u003e Copy channel ID\n* Slackbot member ID: Under apps -\u003e right-click the bot -\u003e view app details -\u003e Copy Member ID. If Slack bot is not under apps, click `Add apps` and select the slackbot.\n\nEnter above information into AWS:\n* Got to: AWS Console -\u003e Systems Manager -\u003e Application Management -\u003e Parameter Store -\u003e My parameters\n* Select `/Radiuss/Spack/ChildChannelId` and edit. Enter the child channel id as the value and select `save changes`\n* Select `/Radiuss/Spack/ParentChannelId` and edit. Enter the parent channel id as the value and select `save changes`\n* Select `/Radiuss/Spack/SlackbotMemberId` and edit. Enter the Slackbot member id as the value and select `save changes`\n\nSecurity: It is highly recommended that the user change the slack token periodically.\n\n### Step 7: Adding users to Amazon Q\n* Go to AWS Console -\u003e Amazon Q Business -\u003e Applications -\u003e Radiuss -\u003e User Access -\u003e Manage user access\n* Select `Add groups and users`\n* Select `Add and assign new users`\n* Select `Next`\n* Enter information\n* Select `Next`\n* Select `Add`\n\n#### Upgrade/Downgrade user subscription\n* Go to AWS Console -\u003e Amazon Q Business -\u003e Applications -\u003e Radiuss -\u003e User Access -\u003e Manage user access\n* Select user via radio button\n* Select `Edit subscription`\n* Select `Choose subscription` from dropdown\nSubscription tiers are available in this [link](https://aws.amazon.com/q/business/pricing/)\n\n## Accessing the applications:\n* `Amazon Q`: AWS Console -\u003e Amazon Q Business -\u003e Applications -\u003e Radiuss -\u003e Web experience settings -\u003e Deployed URL\n* `Slack`: Workspace -\u003e Designated Channel -\u003e Send a single message that starts with @SpackChatbot\n\n## Clean up:\n```bash\ncdk destroy --all\n```\n\n# Authors and Reviewers:\n * Nick Biso, Machine Learning Engineer - Amazon Web Services Inc.\n * Ian Lunsford, Aerospace Cloud Consultant - Amazon Web Services Inc.\n * Natasha Tchir, Machine Learning Engineer - Amazon Web Services Inc.\n * Katherine Feng, Machine Learning Engineer - Amazon Web Services Inc.\n\n## Security\n\nSee [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information.\n\n## License\n\nThis library is licensed under the MIT-0 License. See the LICENSE file.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faws-samples%2Fmulti-interface-chatbot-using-amazon-q-and-slack-with-cloudfront-clickable-references","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faws-samples%2Fmulti-interface-chatbot-using-amazon-q-and-slack-with-cloudfront-clickable-references","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faws-samples%2Fmulti-interface-chatbot-using-amazon-q-and-slack-with-cloudfront-clickable-references/lists"}