Embed Amazon Quick Suite chat agents in business applications

Organizations can face two key challenges with conversational AI. First, users need answers where they work—in their CRM, support console, or analytics portal—not in separate tools. Second, implementing a secure conversation centered on their systems would require weeks of development to build authentication, token verification, domain security, and global distribution infrastructure.

Amazon Quick Suite's embedded chat helps solve the first challenge by bringing conversational AI directly into your apps, so users can query structured data, search documents, and trigger actions without switching tools.

In this post, we show you how to solve the second challenge with a one-click deployment solution for embedding chat agents using the Quick Suite Embedding SDK on business sites.

Solution overview

The solution uses a secure web portal for embedded chat using Amazon CloudFront for global content delivery, Amazon Cognito for OAuth 2.0 authentication, Amazon API Gateway for REST API endpoints, AWS Lambda for serverless API processing, and the OpenID Connect (OIDC) organization for identity integration with Quick Suite.

The solution uses deep protection with multiple layers of protection: DDoS protection in CloudFront, a private Amazon Simple Storage Service (Amazon S3) private bucket with original access control helps prevent direct access to front-end assets, AWS WAF level of limit protection in API Gateway, and JSON Web Token (JWT) signature verification using limited Amazon Cognic generic keys. with less privileged AWS Identity and Access Management (IAM) permissions.

The following diagram shows the structure of the solution.

The workflow consists of the following steps:

1. Users access a web portal URL, which redirects to CloudFront.
2. CloudFront uses native access control to download HTML, CSS, and JavaScript files from a private S3 bucket.
3. The web app checks for a valid authentication token and redirects unauthorized users to an Amazon Cognito managed UI for OAuth 2.0 login.
4. Users enter information on an Amazon Cognito login page, which authenticates them and redirects back to the CloudFront URL with a one-time authorization code.
5. The application generates an authorization code and makes an HTTPS API call to the API Gateway, which bypasses the AWS WAF rate limit.
6. API Gateway invokes the Lambda function with the authorization code.
7. The Lambda function makes a server-to-server HTTPS call to an Amazon Cognito OAuth token repository, exchanging an authorization code for JWT tokens (ID token, access token, refresh token).
8. The function verifies the cryptographic signature of the ID token using the Amazon Cognito public keys JSON Web Key Set (JWKS) with thread-safe caching.

The following is an example JWT done in code:

{"at_hash": "abcdefifB5vH2D0HEvLghi", "sub": "12345678-abcd-1234-efgh-123456789012", "email_verified": true, "iss": " "cognito:username": "12345678-abcd-1234-efgh-123456789012", "origin_jti": "abcd1234-5678-90ef-ghij-klmnopqrstuv", "aud": "1a2b3c4d5e6f7g8h9i0j1k2l3m", "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "token_use": "id", "auth_time": 1704063600, "exp": 1704067200, "iat": 1704063600, "jti": "abcdef12-3456-7890-abcd-ef1234567890", "email": "[email protected]"}

9. The Lambda function calls the AWS Security Token Service (AWS STS) AssumeRoleWithWebIdentity API with an authenticated ID token to assume the IAM web identity role and accept temporary AWS credentials.
10. The function uses temporary information to call the Quick Suite ListUsers API to verify that the user exists, and then calls the GenerateEmbedUrlForRegisteredUser API to help generate a secure embedded URL with domain restrictions.
11. The function returns an embedded URL in a JSON response with cross-resource sharing (CORS) headers through API Gateway to CloudFront. The following is an example of an embed URL:

    {"ChatEmbedUrl": " "user": "[email protected]"}

12. The CloudFront application uses the Quick Suite Embedding SDK to create an embedding context and provide a conversational interface through an HTML iframe with secure connections from other locations.

You can deploy a solution with the following high-level steps:

1. Deploy a serverless infrastructure using the AWS Cloud Development Kit (AWS CDK).
2. Assign users to Amazon Cognito and Quick Suite.
3. Share Quick Suite assets (chat agent and related communications, knowledge base).
4. Access the web portal to use Quick Suite chat agents.

What is required

The following requirements are required to use the solution shown in this post:

Deploy a serverless infrastructure using the AWS CDK

Complete the following steps to deploy a serverless infrastructure using the AWS CDK:

1. Clone a GitHub repository:

git clone [email protected]:aws-samples/sample-quicksuite-chat-embedding.git 
cd sample-quicksuite-chat-embedding

2. Deploy infrastructure:

You will be asked to enter your AWS Region code, AWS CloudFormation stack ID and portal title, and your AWS CLI profile.

Assign users to Amazon Cognito and Quick Suite

Complete the following steps to provision users in Amazon Cognito and Quick Suite:

1. Create an Amazon Cognito user in the Amazon Cognito user pool:

python scripts/create_cognito_user.py --profile  

2. Create an associate user in Quick Suite:

python scripts/create_quicksuite_user.py --profile  

Share the Quick Suite chat agent

Complete the following steps to share your Quick Suite chat agent:

1. Log in to the Quick Suite console using credentials for the Quick Suite Author Pro role.
2. Select Negotiation agents in the navigation pane.
3. Select the agents you want to share (for example, AnyCompany Ecom order assistant) and select Share it.

4. Search for the username (for example, [email protected]) that you created earlier.
5. Select Share it.

After sharing this agent, you also need to share each connected resource of the agent separately to ensure full functionality.

Access the web portal to use Quick Suite chat agents

Complete the following steps to access the web portal and start using chat agents:

1. See the temporary password in the Amazon Cognito confirmation email.
2. Access the CloudFront URL in your web browser with a temporary user ID and password.
3. You will be prompted to change your password on your first login.

After successful login, you can see My Helper in the dialog interface.

4. Select a Region to connect to custom Quick Suite chat agents.

5. To see chat agents shared with you, select It was shared with me below Filter.

6. Select the agent you want and start chatting.

The following screenshots show the chat interaction of a customer service representative tracking an instance of an online order and processing its refund as requested by a verified customer over the phone.

Clean up

To clean up your resources, remove used AWS resources:

The conclusion

This solution addresses the main challenges of embedding conversational AI on a large scale: obtaining the authentication of thousands of users simultaneously in all regions of the world, maintaining enterprise-level security with extensive audit trails, and simplifying deployment through automated infrastructure provisioning. You can customize portal branding, configure security policies, and integrate with existing identity providers. You can scale to thousands of users at once automatically while keeping payment rates as you go.

To try this solution, match the GitHub repository and use the complete one-click infrastructure to embed Quick Suite chat agents.

About the writers

Satyanarayana Adimula is a Senior Architect at AWS Generative AI Innovation & Delivery. Drawing on more than 20 years of data knowledge and analytics, he specializes in building agent AI systems that enable large enterprises to automate complex workflows, accelerate decision-making, and achieve measurable business results.