Amazon Q Business - API Overview

---

---

The API provides various actions and operations that can be used to interact with Amazon Q Business. The APIs can be effectively used to create applications, manage conversations, and upload documents.

Q Business

Amazon Q Business is a chat assistant powered by AI that helps employees work more efficiently. It supports various tasks, such as answering questions, finding information, writing emails, summarizing text, creating document outlines, and generating ideas. By asking questions, users get conversational answers, making their work easier and boosting productivity.

For an overview of the Amazon Q Business APIs, see Overview of Amazon Q Business API operations.

Q Apps

The Amazon Q Apps is a feature that allows web experience users to build their own generative AI-powered apps. With Amazon Q Apps, users can effortlessly create, share, and customize apps on enterprise data to streamline tasks and boost individual and team productivity. For example, you can create a tool that only generates content for marketing, which can help your marketing team work more efficiently. Or, you can create a tool that writes customer emails and promotional content in a specific style, tone, and brand voice.

For an overview of the Amazon Q App APIs, see Overview of Amazon Q Apps API operations.

Setup Streaming chat Using APIs

Amazon Q Business offers a streaming Chat API for delivering chat responses to users in a series of partial results. These responses are transmitted using sequential data packets.

To configure streaming, you can use WebSockets or an AWS SDK. For WebSockets, a secure connection is established to a supported Amazon Q Business endpoint (e.g., wss://qbusiness.us-west-2.api.aws:8443/chat) over port 8443. Ensure that this port is enabled and not blocked by your network configuration.

Setup WebSocket Stream

The following section outlines the steps to set up your WebSocket stream.

• Attach the following policy to the IAM role that makes the request.

{
    "Version": "2012-10-17",
        "Statement": [
            {
                "Sid": "my-qbusiness-websocket-policy",
                    "Effect": "Allow",
                    "Action": "qbusiness:Chat",
                    "Resource": "*"
            }
        ]
}
    

To start the session, create a presigned URL in the following format. Line breaks have been added for readability.

GET wss://qbusiness.us-west-2.api.aws:8443/chat?
&X-Amz-Algorithm=AWS4-HMAC-SHA256
&X-Amz-Credential=access-key%2FYYYYMMDD%2Fus-west-2%2Fqbusiness%2Faws4_request
&X-Amz-Date=YYYYMMDDTHHMMSSZ
&X-Amz-Expires=300
&X-Amz-Security-Token=security-token
&X-Amz-Signature=string
&X-Amz-SignedHeaders=host
&chat-input={"applicationId":"application_id","userId":"test_user@amazon.com","userGroups":null,"clientToken":str(uuid.uuid4())}
    

Create the string to sign, which contains meta information about your request. You use the string to sign in the next step when you calculate the request signature.

hashed_canonical_request = HashSHA256(canonical_request.Encode("utf-8")).HexDigest()
new_credential_scope = datestamp + '/' + region + '/qbusiness/aws4_request'
string_to_sign=algorithm + "\n"
+ amz_date + "\n"
+ new_credential_scope + "\n"
+ HashSHA256(canonical_request.Encode("utf-8")).HexDigest()
    

Create the string to sign, which contains meta information about your request. You use the string to sign in the next step when you calculate the request signature.

hashed_canonical_request = HashSHA256(canonical_request.Encode("utf-8")).HexDigest()
new_credential_scope = datestamp + '/' + region + '/qbusiness/aws4_request'
string_to_sign=algorithm + "\n"
+ amz_date + "\n"
+ new_credential_scope + "\n"
+ HashSHA256(canonical_request.Encode("utf-8")).HexDigest()
    

Calculate the signature. To do this, derive a signing key from your AWS secret access key. For a greater degree of protection, the derived key is specific to the date, service, and AWS Region. Use this derived key to sign the request.

#Create the signing key
signing_key = GetSignatureKey(secret_key, datestamp, region, service)
        
# Sign the string_to_sign using the signing key
signature = HMAC.new(signing_key, (string_to_sign).Encode("utf-8"), Sha256()).HexDigest
    

Add signing information to the request and create the request URL.
After you calculate the signature, add it to the query string.

First, add the authentication information to the query string.

canonical_querystring += "&X-Amz-Signature=" + signature
    

Second, create the URL for the request.

request_url = endpoint + canonical_uri + "?" + canonical_querystring
    

Use the request URL with your WebSocket library to make the request to Amazon Q Business.

The request to Amazon Q Business must include the following headers. Typically these headers are managed by your WebSocket client library.

Host: qbusiness.us-west-2.amazonaws.com:8443 
Connection: Upgrade
Upgrade: websocket
Origin: URI-of-WebSocket-client
Sec-WebSocket-Version: 13
Sec-WebSocket-Key: randomly-generated-string <calculated at runtime>
    

When Amazon Q Business receives your WebSocket request, it responds with a WebSocket upgrade response. Typically your WebSocket library manages this response and sets up a socket for communications with Amazon Q Business.

The following is the response from Amazon Q Business. Line breaks have been added for readability.

HTTP/1.1 101 WebSocket Protocol Handshake
Connection: upgrade
Upgrade: websocket
websocket-origin: wss://qbusiness.us-west-2.amazonaws.com:8443
websocket-location: qbusiness.us-west-2.amazonaws.com:8443/chat?
&X-Amz-Algorithm=AWS4-HMAC-SHA256
&X-Amz-Credential=access-key%2FYYYYMMDD%2Fus-west-2%2Fqbusiness%2Faws4_request
&X-Amz-Date=YYYYMMDDTHHMMSSZ
&X-Amz-Expires=300
&X-Amz-Security-Token=security_token
&X-Amz-SignedHeaders=host
&chat-input=%7B%22applicationId%22%3A%20%22aa419bef-ac4e-4c57-9224-f603e185ac09%22%2C%20%22userId%22%3A%20%testuser%40amazon.com%22%2C%20%22userGroups%22%3A%20null%2C%20%22clientToken%22%3A%20%2283eb07d9-193c-420c-97c6-f2f343d13591%22%2C%20%22conversationId%22%3A%20null%2C%20%22parentMessageId%22%3A%20null%7D
&X-Amz-Signature=Signature Version 4 signature
x-amzn-RequestId: RequestId
sec-websocket-accept: hash-of-the-Sec-WebSocket-Key-header
    

Make your WebSocket streaming request.
After the WebSocket connection is established, the client can start sending a sequence of chat frames, each encoded using event stream encoding.
Each data frame contains three headers combined with a chunk of raw text bytes; the following table describes these headers.

To end the data stream, send an end of input event in an event stream encoded message.

Handling WebSocket Streaming Errors

When an error happens while processing your request, Amazon Q Business sends a special response back to you. This response contains the headers described in the following table; the body of the response contains a descriptive error message.

Event Stream Encoding

Amazon Q Business uses a format called event stream encoding for streaming chat.

Event stream encoding allows two-way communication between a client and a server. When you send a message to Amazon Q Business, it's encoded in a special format. The response you get back from Amazon Q Business is also in this same format.

Data Frames

Each streaming request contains one or more data frames. There are two steps to creating a data frame:

• Combine raw ChatInput data with metadata to create the payload of your request.
• Combine the payload with a signature to form the event message that is sent to Amazon Q Business.