| ⚡ 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 Microsoft Teams 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 business expert's generative AI to enable Microsoft Teams members to access your organizations data and knowledge sources via conversational question-answering. If you use Slack, refer to Deploy a Slack gateway for Amazon Q, your business expert.
You can connect to your organization data via data source connectors and integrate it with Teams Gateway for Amazon Q business expert to enable access to your Teams channel members. It allows your users to:
- Converse with Amazon Q business expert using Teams 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!
AmazonQTeamsGatewayDemo3.mp4
It's easy to deploy in your own AWS Account, and add to your own teams. We show you how below.
- In DMs it responds to all messages
- Renders answers containing markdown - e.g. headings, lists, bold, italics, tables, etc.
- In channels it responds only to @mentions, and always replies in thread.
- 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 business expert Teams 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 Teams, and start experimenting!
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 business expert application. If you haven't set one up yet, see Creating an Amazon Q application
Lastly, you need a Microsoft account and a Microsoft Teams subscription to create and publish the app using the steps below. If you don’t have these, see if your company can create sandboxes for you to experiment, or create a new account and trial subscription as needed to complete the directions below.
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
- Log into the AWS console if you are not already.
- Choose one of the Launch Stack buttons below for your desired AWS region to open the AWS CloudFormation console and create a new stack.
- Enter the following parameters:
Stack Name: Name your App, e.g. AMAZON-Q-TEAMS-GATEWAY.AmazonQAppId: Your existing Amazon Q business expert application ID (copy from Amazon Q console).AmazonQRegion: Choose the region where you created your Amazon Q business expert application.AmazonQUserId: (Optional) Amazon Q User ID email address (leave empty to use Teams users email as user Id)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-teams-gateway/AmazonQTeamsGateway.json |
| Oregon (us-west-2) | |
https://s3.us-west-2.amazonaws.com/aws-ml-blog-us-west-2/artifacts/amazon-q-teams-gateway/AmazonQTeamsGateway.json |
When your CloudFormation stack status is CREATE_COMPLETE, choose the Outputs tab, and keep it open - you'll need it below.
- Go to the Azure Portal: https://portal.azure.com/#blade/Microsoft_AAD_RegisteredApps/ApplicationsListBlade and login with your Microsoft account.
- Choose + New registration
- For Name, provide the name for your app. Tip: Keep things simple by using the
Stack Nameyou entered above. - For Who can use this application or access this API?, choose Accounts in this organizational directory only (AWS only - Single tenant)
- Choose Register
- Note down the Application (client) ID value, and the Directory (tenant) ID from the Overview page. You'll need them later when asked for MicrosoftAppId and MicrosoftAppTenantId.
- For Name, provide the name for your app. Tip: Keep things simple by using the
- In the Select API permissions page (on the left navigation menu)
- Choose Add a permission
- Choose Microsoft Graph
- Choose Application permissions
- Select User.Read.All
- Select ChannelMessage.Read.All
- Select Team.ReadBasic.All
- Select Files.Read.All
- Choose Add permissions. This permission allows the app to read data in your organization's directory about the signed in user.
- Remove the original User.Read - Delegated permission (use the … menu on the right to choose Remove permission)
- Choose ✓ Grant admin consent for Default Directory
- In the Certificates & secrets page
- Choose + New client secret
- For Description, provide a value such as -client-secret
- Choose a value for Expires. NOTE: In production, you'll need to manually rotate your secret before it expires.
- Choose Add
- Note down the Value for your new secret. You'll need it later when asked for MicrosoftAppPassword.
- (Optional) Choose Owners to add any additional owners for the application.
- Go to the Microsoft Bot Framework: https://dev.botframework.com/bots/new - login with your Microsoft account.
- (Optional) Create and upload a cool custom icon for your new Amazon Q Bot. Or, use this one that I created using Amazon Bedrock image playgound!
- Enter your prefered Display name, Bot handle, and Long description.
- For Messaging endpoint copy and paste the value of the
TeamsEventHandlerApiEndpointfrom your Stack outputs tab (from Step 1). Do not check Enable Streaming Endpoint. - For App type, choose
Single Tenant. - For Paste your app ID below to continue, enter the MicrosoftAppId value you noted above.
- For App Tenant ID, enter the MicrosoftAppTenantId value you noted above.
- Leave the other values as they are, agree to the terms, and choose Register.
- On the Channels page, under Add a featured channel choose Microsoft Teams
- Choose Microsoft Teams Commercial (most common), and then Save.
- Agree to the Terms of Service and choose Agree
Let's configure your App 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 app secret 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.
- Login to your AWS console
- In your AWS account go to Secret manager, using the URL shown in the stack output:
TeamsSecretConsoleUrl. - Choose
Retrieve secret value - Choose
Edit - Replace the value of
MicrosoftAppId,MicrosoftAppPassword, andMicrosoftAppTenantIdwith the values you noted in the previous steps. - Choose Save
- Go to Developer Portal for Teams: https://dev.teams.microsoft.com/home - login with your Microsoft Teams user account.
- Choose + New app
- For Name, enter your bot name.
- Enter Full name and both short and full Descriptions (you can just use the bot name for them all if you want - just don't leave them empty)
- Enter values for Developer information and App URLs fields.
- For testing, you can make up values, and URLs like
https://www.anycompany.com/etc. Use real ones for production.
- For testing, you can make up values, and URLs like
- For Application (client) ID* enter the value of
MicrosoftAppIdfrom above. - Choose Save.
- Under Branding you can upload my AI generated icons, or different icon(s), or none at all.. it's up to you.
- Under App features, choose Bot
- Select Enter a bot ID, and enter the
MicrosoftAppIdfrom the earlier steps - Under What can your bot do?, check Upload and download files.
- Under Select the scopes in which people can use this command, check all 3 boxes (Personal, Team, and Group chat).
- Choose Save
- Select Enter a bot ID, and enter the
- Choose Publish
- Choose Download the app package to download a zip file to your computer.
- Choose Preview in Teams to Microsoft Teams (work or school) app
- From the Microsoft Teams left navigation bar, choose Apps, then Manage your apps, then ⤒ Upload an app
- Choose Upload an app to your orgs app catalog, and select the zip file downloaded in the previous step. This adds the app to Teams.
- Select the card for your new app and choose Add.
And, now, at last, you can test your bot in Microsoft Teams!
To use your Amazon Q business expert app in your team channels, first add it to each team:
- In the Teams app, select your Team and choose 'Manage team'
- In the Apps tab, choose the new Amazon Q app, and Add.
Time to say Hi!
- Go to Teams
- Under Apps add your new Amazon Q business expert app to a Chat
- Optionally add your app to one or more Team channels
- In the app DM chat, say Hello. In a team channel, ask it for help with an @mention.
- Enjoy.
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.
See Security issue notifications for more information.
This library is licensed under the MIT-0 License. See the LICENSE file.