Add a generative AI experience to your website or web application with Amazon Q embedded

Generative AI offers many benefits for both you, as a software provider, and your end-users. AI assistants can help users generate insights, get help, and find information that may be hard to surface using traditional means. In addition, they can help your employees reduce repetitive tasks and focus on high-value work. However, adding generative AI assistants to your website or web application requires significant domain knowledge and the technical expertise to build, deploy, and maintain the infrastructure and end-user experience. These challenges fall outside of some software providers’ core domain, creating barriers to offering AI assistants to users.

Amazon Q Business is a generative AI assistant that can answer questions, provide summaries, generate content, and securely complete tasks based on data and information in your enterprise systems. Amazon Q Business securely unites disparate data with over 40 built-in connectors to popular enterprise applications, document repositories, chat applications, and knowledge management systems. You can use natural language to request information or assistance to generate content. Amazon Q Business handles the complexity of deploying and maintaining the infrastructure required for generative AI assistants so you can focus on creating a delightful end-user experience.

Amazon Q embedded is a feature that lets you embed a hosted Amazon Q Business assistant on your website or application to create more personalized experiences that boost end-users’ productivity. You can configure the assistant with guardrails to define global and topic-level controls for your environment. With an embedded Amazon Q Business assistant, end-users can receive immediate, permission-aware responses from your data sources, with citations.

In this post, we demonstrate how to use the Amazon Q embedded feature to add an Amazon Q Business assistant to your website or web application using basic HTML or React. We also show you how to use the feature with content management systems like WordPress and Drupal. This post includes a sample webpage for Amazon Q Business that allows you to quickly test and demonstrate your AI assistant. This allows you to develop the changes on your website or application in parallel while refining your Amazon Q Business configurations.

Solution overview

Embedding Amazon Q Business gives your users access to a generative AI assistant without leaving your website or web application. Integrating the assistant involves creating an Amazon Q Business application, adding users or groups, connecting relevant data sources, allowlisting your domain, and finally adding an HTML inline frame (iframe) element to your website or web application.

Prerequisites

In this section, we walk through how to set up an Amazon Q Business application, permissions, and user access.

Amazon Q Business application

The Amazon Q embedded feature requires an Amazon Q Business application. If you don’t have an existing application, you can create an application integrated with AWS IAM Identity Center or AWS Identity and Access Management (IAM) identity federation. Refer to Configuring an Amazon Q Business application using AWS IAM Identity Center, or Creating an Amazon Q Business application using Identity Federation through IAM if you need to make a new application.

Permissions

Configuring the Amazon Q embedded feature IAM permissions that allow you to use and manage Amazon Q Business. Your permission policy must at least allow the Amazon Q Business CreateWebExperience and UpdateWebExperience actions:

"Action": "qbusiness:CreateWebExperience",
"Action": "qbusiness:UpdateWebExperience",

When creating the IAM permission policy, the IAM Visual policy creator is a great way to see the options available. Using the least privileged access approach, you can restrict the resource in which the permission grants access to a specific AWS Region, account ID, application ID, and web experience ID.

"Resource": "arn:aws:qbusiness:us-east-1:123456789012:application/<replace-with-id>"
"Resource": "arn:aws:qbusiness:us-east-1:123456789012:application/<replace-with-id>/web-experience/<replace-with-id>"

You can find your application ID on the Amazon Q Business console under Application settings or from the list-applications command in the AWS Command Line Interface (AWS CLI). You can find your web experience ID with the list-web-experiences AWS CLI command. For example:

aws qbusiness list-applications
aws qbusiness list-web-experiences --application-id a1b2c3d4-5678-90ab-cdef-EXAMPLE11111

User access

Amazon Q Business requires authentication before users can engage with the assistant. If you use AWS IAM Identity Center, you can grant users access to the assistant by adding the users or groups to your Amazon Q Business application. If you use IAM identity federation, Amazon Q Business automatically subscribes users to the subscription type you select when you create the application. For more information on managing users, refer to Managing user subscriptions for IAM Identity Center-integrated applications, or see Updating and cancelling user subscriptions for applications using IAM Federation.

Allowlisting your website or web application

To embed Amazon Q Business on your website or web application, you must first allowlist your domain. This restricts your assistant to only sites you trust and stops others from embedding your assistant. You can add multiple domains for different services or development instances used for testing. Complete the following steps:

Open the Amazon Q Business console.
Next, select your Amazon Q Business application.
From the menu, choose Amazon Q embedded under the Enhancements section, then choose Add allowed website.
For Enter website URL, enter the base URL of the website or web application you want to allowlist for Amazon Q Business, for example https://www.example.com (trailing / not required), and choose Add.

Amazon Q Business hosts the web experience on an AWS domain. To find the URL, navigate to the main page of your Amazon Q Business application and copy the value for Deployed URL, for example https://1234abcdef5678.chat.qbusiness.example.on.aws/, in the Web experience settings section. Now you can embed this assistant into the website or web application hosted at the domain you allowlisted.

Customizing the user experience

You can customize the user experience look and feel for your organization. Customization options include the assistant title, subtitle, welcome message, font, color, and logo. You can also enable sample prompts. Refer to Customizing an Amazon Q Business web experience to see the available customization options.

The following screenshots show the default Amazon Q Business user experience (left) and an Amazon Q Business user experience with a custom title, subtitle, and welcome message (right).

Add Amazon Q Business to your website or web application

Before continuing, make sure you have allowlisted your domain as described earlier in this post.

You can choose from the following embedding options:

Using an HTML iframe element
Using a React component
Using a content management system

Embed Amazon Q Business using an HTML iframe element

You can embed Amazon Q Business on your website or web application using an iframe element, which is an HTML element that you can use to insert another HTML page into the current one. Other embedding options build upon this foundational HTML element. The following is a sample iframe element:

<iframe src="https://1234abcdef5678.chat.qbusiness.example.on.aws/"></iframe>

You can customize the iframe element with various attributes such as the width, height, and title. Setting the Amazon Q Business deployed URL as the value for the src attribute will display the Amazon Q Business web experience within the iframe. The following code shows an example iframe element with the id, title, width, height, and src attributes set to example values:

<iframe
    id="inlineFrameExample"
    title="Inline Frame Example"
    width="600"
    height="650"
    src="https://1234abcdef5678.chat.qbusiness.example.on.aws/">
</iframe>

Refer to <iframe>: The Inline Frame element to learn more about the iframe element.

Embed Amazon Q Business using a React component

You can embed Amazon Q Business on your website or web application using a React component. React components offer more customizations and modularity than a standard iframe. In this post, we’ve included a sample React component that wraps an iframe element and adds abilities such as an expanding and collapsing chat interface and showing a loading spinner when the page first loads.

To use this React component, download the sample code from the Embed GenAI chat into React GitHub repo and add it to your React source code. Then you can import the component into your website or web application and add the Chat element with at least the embedUrl attribute set to the deployed URL of your Amazon Q Business application. The following example code shows the options of the sample React component:

import Chat from "../components/embed";
...
<Chat
    embedUrl="https://1234abcdef5678.chat.qbusiness.example.on.aws/"
    embedWidth={600}          // Optional
    embedHeight={650}         // Optional
    embedOffsetRightPc={5}    // Optional
    headerText="Chat"         // Optional
    headerInfo="Chat with us" // Optional
/>

Embed Amazon Q Business using a content management system

You can embed Amazon Q Business on a website published by a content management system that allows you to add HTML elements to the content. We’ve included examples for WordPress and Drupal, both of which you can deploy with Amazon Lightsail.

Embedding on a WordPress site

To embed Amazon Q Business on your WordPress site, first access the WordPress admin page. Optionally, add a block group wrapper to constrain iframe sizing with the values of your choosing. For example, you could set the layout content height to 650px, width to 620px, a width of 100% in the iframe to fill the container, and select a full-size block item. Finally, add a custom HTML block and insert the iframe code. The following code is a sample iframe element:

<iframe
    id="inlineFrameExample"
    title="Inline Frame Example"
    width="100%"
    height="650"
    src="https://021345abcdef.chat.qbusiness.example.on.aws/">
</iframe>

The following screenshot shows an example of adding a block to a WordPress site.

The following screenshot shows an example of adding an iframe to the block.

The following screenshot shows an example of Amazon Q Business in a WordPress site.

Embedding on a Drupal site

To embed Amazon Q Business on your Drupal site, complete the following steps:

Open the Drupal admin page.
Choose Content, Blocks, and Add content block.
Give your content block a description and change the text format to HTML.
Choose the Source
Add your iframe to the Body section of the block, then choose Save and configure.
When configuring your content block, the visibility options are optional and can be left with the default values.
Choose a Region to display this block, such as Content Above or Sidebar, then choose Save block.

The following screenshot shows an example of Amazon Q Business embedded with the Content Above option.

The following screenshot shows an example of Amazon Q Business embedded with the Sidebar option.

Sample website

To help you get started embedding Amazon Q Business, we have included a sample website that you can deploy on AWS Amplify with an AWS CloudFormation stack. The sample website contains an HTML iframe element with your Amazon Q Business assistant. To use the website, complete the following steps:

First collect your Amazon Q Business application ID and make a note. You can find your application ID on the Amazon Q Business console as described earlier in this post.
Download our YAML sample CloudFormation template to your workstation.
Deploy the stack either using the AWS CloudFormation console or using the AWS CLI.
After uploading the sample CloudFormation template, enter a stack name, a web page name, and your Amazon Q Business application ID in the Application ID input field.
You can leave all other settings at their default values.
After the stack fully deploys, navigate to the Outputs tab on the AWS CloudFormation console and copy the Amplify URL.
Return to the Amazon Q Business console, select your Amazon Q Business application, and choose Amazon Q Embedded to add your Amplify URL to the Allowed websites list as described earlier in this post.
Navigate to your Amplify URL in your web browser to see your sample website with Amazon Q Business. You may need to Sign in to Q Business.

Clean Up

To avoid future charges in your account from Amplify you can delete the resources you created in the previous section walkthrough on creating a sample website.

On the CloudFormation console, in the navigation pane, choose Stacks.
Select the stack you launched in the previous step, then choose Delete.

Conclusion

In this post, we showed you various methods of embedding Amazon Q Business, which enables users to have natural language conversations and get meaningful assistance directly on your website or web application. We discussed creating an Amazon Q Business application and how to allowlist your URL. We then walked through adding Amazon Q Business with a standard HTML iframe, a React component, and how to update a WordPress or Drupal site.

To get started, refer to Getting started with Amazon Q Business to create an Amazon Q Business application. For more information on the Amazon Q embedded feature, see Amazon Q embedded. Refer to Enhancing an Amazon Q Business application environment for guidance on integrating your data sources, which can include your website content, to enrich the answers Amazon Q Business can provide your website or web application users.

About the authors

Bobby Williams is a Senior Solutions Architect at AWS. He has decades of experience designing, building, and supporting enterprise software solutions that scale globally. He works on solutions across industry verticals and horizontals and is driven to create a delightful experience for every customer.

David Girling is a Senior AI/ML Solutions Architect with over 20 years of experience in designing, leading, and developing enterprise systems. David is part of a specialist team that focuses on helping customers learn, innovate, and utilize these highly capable services with their data for their use cases.

Philip Whiteside is a Solutions Architect (SA) at Amazon Web Services. Philip is passionate about overcoming barriers by utilizing technology.