|
1 | | -# Overview |
2 | | - |
3 | | -This solution creates a simple website that enables a customer to start a chat with a pre-built widget. The end user enters their name and the username of the agent they would like to speak with and they'll then be put into that agent's queue. The stack creates a website hosted in [Amazon S3](https://aws.amazon.com/s3/) that is served by [Amazon CloudFront](https://aws.amazon.com/cloudfront/). The website calls an [Amazon API Gateway](https://aws.amazon.com/api-gateway/) endpoint that triggers an [AWS Lambda](https://aws.amazon.com/lambda/) function. This Lambda function invokes the [Amazon Connect](https://aws.amazon.com/connect/) Service [StartChatContact](https://docs.aws.amazon.com/en_pv/connect/latest/APIReference/API_StartChatContact.html) API, stores the result in [Amazon DynamoDB](https://aws.amazon.com/dynamodb/), and returns the result to the front end. |
4 | | - |
5 | | - |
6 | | - |
7 | | -In addition to starting the chat and storing the result in the DynamoDB (DDB), the Lambda function helps determine whether the user has an active chat open. Before starting the chat, the Lambda function checks the DDB to see whether there is an existing chat open for that user. If so, the current chat is returned to the website instead of starting a new one. This enables your user to pick up the existing chat where they left off on any device. This functionality is possible by knowing who the user is and keeping track of whether there is an open chat session. An open chat session is determined by the presence of a chat transcript in S3. At the end of a chat conversation, when the chat transcript is uploaded to S3, a Lambda function is triggered to update the DDB with the S3 location of the chat transcript. If there is no S3 location for a chat then we assume the chat is still in session. |
8 | | - |
9 | | -## Deployment Steps |
10 | | - |
11 | | -### Pre-requisites |
12 | | - |
13 | | -You need an Amazon Connect instance to deploy this [CloudFormation](https://aws.amazon.com/cloudformation/) template. You can use an existing one or create a new one by following our onboarding guide [here](https://docs.aws.amazon.com/connect/latest/adminguide/amazon-connect-get-started.html). |
14 | | - |
15 | | -If you are using an existing instance, you may need to make a few changes to your instance to enable Chat. Follow the steps [here](https://github.com/amazon-connect/amazon-connect-chat-ui-examples/blob/master/README.md#enabling-chat-in-an-existing-amazon-connect-contact-center) to see what changes you need to make. |
16 | | - |
17 | | -### Set Up Steps |
18 | | - |
19 | | -1) Go into your Amazon Connect instance and go to the Contact Flows page. Create a new contact flow and select 'Import flow' from the upper right hand corner. Import the 'Basic Chat Disconnect Flow' from the 'contactFlows/' in this repo and click 'Publish'. Follow the same steps for the 'Basic Chat Flow'. |
20 | | - |
21 | | -2) Deploy the CloudFormation template from on of the regions below. |
22 | | - - When updating the parameters, each field in the CloudFormation template and make the necessary updates |
23 | | - - `WebsiteS3BucketName`: this should be the name of a *new* bucket that will be created on your behalf to store the website contents |
24 | | - - `contactFlowId`: This is the id of the 'Basic Chat Flow' you imported in step 1. You can find the contact flow id when viewing the contact flow and clicking on the 'Additional information' link. For example, if the arn for your flow is 'arn:aws:connect:us-west-2:123456789012:instance/11111111-1111-1111-1111-111111111111/contact-flow/22222222-2222-2222-2222-222222222222', the contact flow id is '22222222-2222-2222-2222-222222222222' |
25 | | - - `instanceId`: This is the id of the Amazon Connect instance you want to use. You can find this on the Amazon Connect console or when viewing the contact flow. For example, if the arn for your flow is 'arn:aws:connect:us-west-2:123456789012:instance/11111111-1111-1111-1111-111111111111/contact-flow/22222222-2222-2222-2222-222222222222', the instance id is '11111111-1111-1111-1111-111111111111' |
26 | | - - `AmazonConnectS3BucketName`: This is the bucket that holds the chat transcripts for your Amazon Connect instance. You can find this in the Amazon Connect console when viewing the Data Storage section in your instance details. E.g. If your instance has connect-xxx/connect/instanceName/ChatTranscripts, enter 'connect-xxx' |
27 | | - - `transcriptPath`: This is the path in the S3 bucket that contains the chat transcripts. You can find this in the Amazon Connect console when viewing the Data Storage section in your instance details. E.g. If your instance has connect-xxx/connect/instanceName/ChatTranscripts, enter 'connect/instanceName/ChatTranscripts' |
28 | | - - You do not need to make any change on the next two pages of the CloudFormation stack launch, but you will need to check the box to acknowledge that IAM resources will be created. |
29 | | - |
30 | | - | Region | Launch Button | |
31 | | - | ------ | ------------- | |
32 | | - | us-east-1 (N. Virginia) | [](https://console.aws.amazon.com/cloudformation/home#/stacks/new?stackName=asyncCustomerChatUX&templateURL=https://s3.amazonaws.com/us-east-1.amazon-connect-advanced-customer-chat-cfn/cloudformation.yaml) | |
33 | | - | us-west-2 (Oregon) | [](https://us-west-2.console.aws.amazon.com/cloudformation/home#/stacks/new?stackName=asyncCustomerChatUX&templateURL=https://s3-us-west-2.amazonaws.com/us-west-2.amazon-connect-advanced-customer-chat-cfn/cloudformation.yaml) | |
34 | | - | ap-southeast-2 (Sydney) | [](https://ap-southeast-2.console.aws.amazon.com/cloudformation/home#/stacks/new?stackName=asyncCustomerChatUX&templateURL=https://s3-ap-southeast-2.amazonaws.com/ap-southeast-2.amazon-connect-advanced-customer-chat-cfn/cloudformation.yaml) | |
35 | | - | ap-northeast-1 (Tokyo) | [](https://ap-northeast-1.console.aws.amazon.com/cloudformation/home#/stacks/new?stackName=asyncCustomerChatUX&templateURL=https://s3-ap-northeast-1.amazonaws.com/ap-northeast-1.amazon-connect-advanced-customer-chat-cfn/cloudformation.yaml) | |
36 | | - | eu-central-1 (Frankfurt) | [](https://eu-central-1.console.aws.amazon.com/cloudformation/home#/stacks/new?stackName=asyncCustomerChatUX&templateURL=https://s3-eu-central-1.amazonaws.com/eu-central-1.amazon-connect-advanced-customer-chat-cfn/cloudformation.yaml) | |
37 | | - | eu-west-2 (London) | [](https://eu-west-2.console.aws.amazon.com/cloudformation/home#/stacks/new?stackName=asyncCustomerChatUX&templateURL=https://s3-eu-west-2.amazonaws.com/eu-west-2.amazon-connect-advanced-customer-chat-cfn/cloudformation.yaml) | |
38 | | - | ap-southeast-1 (Singapore) | [](https://ap-southeast-1.console.aws.amazon.com/cloudformation/home#/stacks/new?stackName=asyncCustomerChatUX&templateURL=https://s3-ap-southeast-1.amazonaws.com/ap-southeast-1.amazon-connect-advanced-customer-chat-cfn/cloudformation.yaml) | |
39 | | - | ca-central-1 (Canada) | [](https://ca-central-1.console.aws.amazon.com/cloudformation/home#/stacks/new?stackName=asyncCustomerChatUX&templateURL=https://s3-ca-central-1.amazonaws.com/ca-central-1.amazon-connect-advanced-customer-chat-cfn/cloudformation.yaml) | |
40 | | - |
41 | | -### Testing Steps |
42 | | - |
43 | | - Once the CloudFront distribution is ready, test! |
44 | | - |
45 | | -1) Go to CloudFront URL that was created. You can find the CloudFront URL under the `Outputs` tab of the CloudFormation stack by the key `cloudFrontDistribution`. If you get an Access Denied error saying it cannot read the file from S3, the CDN is not ready. It could take over an hour to be ready. |
46 | | -2) For the agent CCP, open the CCP url from Amazon Connect and change the `/ccp` portion of the URL to `/ccp-v2` |
47 | | -3) When entering the username on your CloudFront web page, enter the username of the agent you would like to speak to. The Contact Flow connects the user to the agent specified in the username field. If a user with the username cannot be found, it puts you in the Basic Queue. |
48 | | - |
49 | | -## Adding this chat widget to your website |
50 | | - |
51 | | -If you want to add the customer chat widget (that is available in the Test Chat experience in the Amazon Connect website) to your website instead of using the CloudFront web page, here are the steps to do so: |
52 | | - |
53 | | -1. Update the CORS configuration in Lambda to refer to your new website. In Lambda, go to the initiateChatLambda function and update the `Access-Control-Allow-Origin` field in the success and failure responses to be your website's URL. |
54 | | - |
55 | | -2. In your website's html code, import 'amazon-connect-chat-interface.js'. This file was copied into your S3 bucket that hosts the website created by this CloudFormation template. If you want to modify the code in the interface.js file, you can refer to [this repo](https://github.com/amazon-connect/amazon-connect-chat-interface) to see its source. |
56 | | - |
57 | | - ```html |
58 | | - <script src="amazon-connect-chat-interface.js"></script> |
59 | | - ``` |
60 | | - |
61 | | -3. Initialize the Chat Interface on page load: |
62 | | - |
63 | | - ```js |
64 | | - $(document).ready((a) => { |
65 | | - connect.ChatInterface.init({ |
66 | | - containerId: 'root', // This is the id of the container where you want the widget to reside |
67 | | - headerConfig: { // Use the optional headerConfig and footerConfig to customize your widget |
68 | | - isHTML: true, |
69 | | - render: () => { |
70 | | - return (`<html code here/>`) |
71 | | - } |
72 | | - }, |
73 | | - footerConfig: { |
74 | | - isHTML: true, |
75 | | - render: () => { |
76 | | - return (`<html code here/>`) |
77 | | - } |
78 | | - } |
79 | | - }); |
80 | | - }); |
81 | | - ``` |
82 | | - |
83 | | -4. Start the chat based on a user action. You will want to add fields for the customer name, username, and enableAttachments because those fields are used in the Lambda function that was created. |
84 | | - |
85 | | - ```js |
86 | | - connect.ChatInterface.initiateChat({ |
87 | | - name: customerName, |
88 | | - username: username, |
89 | | - region: ${region}, |
90 | | - apiGatewayEndpoint: "https://${apiId}.execute-api.${region}.amazonaws.com/Prod", |
91 | | - contactAttributes: JSON.stringify({ |
92 | | - "customerName": customerName |
93 | | - }), |
94 | | - contactFlowId: "${contactFlowId}", |
95 | | - instanceId: "${instanceId}", |
96 | | - featurePermissions: { |
97 | | - "ATTACHMENTS": enableAttachments==='true', // this is the override flag from user for attachments |
98 | | - } |
99 | | - },successHandler, failureHandler) |
100 | | - ``` |
101 | | - |
102 | | -## Enabling interactive messages |
103 | | -If you want to enable interactive messages for Amazon Connect Chat the customer chat widget (that is available in the Test Chat experience in the Amazon Connect website) to your website, read the blog on how to [easily set up interactive messages for your Amazon Connect chatbot](https://aws.amazon.com/blogs/contact-center/easily-set-up-interactive-messages-for-your-amazon-connect-chatbot/) for detailed instructions. |
104 | | - |
105 | | -*What are interactive messages for Amazon Connect Chat?* |
106 | | - |
107 | | -Interactive messages are pre-configured responses that your users can select from, making it easy for your customers to quickly resolve their issues through chat. Interactive messages can be designed using the new Amazon Connect Chat templates, which include several different customer display options like list pickers, list pickers with images, and time pickers. These are sent by Amazon Connect Chat using Amazon Lex chatbots. Interactive messages configured through Lex will be validated in the Amazon Connect contact flow to ensure that they have been configured correctly. |
108 | | - |
109 | | -## Enabling attachments |
110 | | -If you want to enable sending attachments for Amazon Connect Chat the customer chat widget, follow the instructions in the [documentation](https://docs.aws.amazon.com/connect/latest/adminguide/enable-attachments.html) to enable your Amazon Connect instance for attachments. Once enabled, you can mark the `ATTACHMENTS` flag in `connect.ChatInterface.initiateChat` as `true`. Example below: |
111 | | - |
112 | | -```js |
113 | | - connect.ChatInterface.initiateChat({ |
114 | | - name: customerName, |
115 | | - username: username, |
116 | | - region: ${region}, |
117 | | - apiGatewayEndpoint: "https://${apiId}.execute-api.${region}.amazonaws.com/Prod", |
118 | | - contactAttributes: JSON.stringify({ |
119 | | - "customerName": customerName |
120 | | - }), |
121 | | - contactFlowId: "${contactFlowId}", |
122 | | - instanceId: "${instanceId}", |
123 | | - featurePermissions: { |
124 | | - "ATTACHMENTS": true, // this is the override flag from user for attachments |
125 | | - } |
126 | | - },successHandler, failureHandler) |
127 | | -``` |
128 | | - |
129 | | -## Enabling rich messaging |
130 | | - |
131 | | -Amazon Connect Chat now allows your agents and customers to use rich text formatting when composing a message, enabling them to quickly add emphasis and structure to messages, improving comprehension. The available formatting options include bold, italics, hyperlinks, bulleted lists, and numbered lists. [Documentation](https://docs.aws.amazon.com/connect/latest/adminguide/enable-text-formatting-chat.html) |
132 | | - |
133 | | -1. To enable rich messaging, include the new param when invoking `initiateChat`: |
134 | | - |
135 | | -```js |
136 | | - connect.ChatInterface.initiateChat({ |
137 | | - contactFlowId: "${contactFlowId}", |
138 | | - instanceId: "${instanceId}", |
139 | | - // ... |
140 | | - supportedMessagingContentTypes: "text/plain,text/markdown", // include 'text/markdown' for rich messaging support |
141 | | - featurePermissions: { |
142 | | - ATTACHMENTS: false, |
143 | | - MESSAGING_MARKDOWN: true |
144 | | - } |
145 | | - },successHandler, failureHandler) |
146 | | -``` |
147 | | - |
148 | | -2. If updating an exisiting CFN stack, the startChatContact lambda function needs to be updated. |
149 | | - |
150 | | -Be sure to pass `supportedMessagingContentTypes` input to `startChatContact()`: |
151 | | - |
152 | | -```js |
153 | | -function startChatContact(body) { |
154 | | - return new Promise(function (resolve, reject) { |
155 | | - var startChat = { |
156 | | - // ... |
157 | | - ...(!!body["SupportedMessagingContentTypes"] && { "SupportedMessagingContentTypes": body["SupportedMessagingContentTypes"] }) |
158 | | - }; |
159 | | - }) |
160 | | -} |
161 | | -``` |
162 | | - |
163 | | -## Enabling message receipts |
164 | | - |
165 | | -Render and send read/delivered message receipts for customer chat-interface. Enable the feature [in the admin console](https://docs.aws.amazon.com/connect/latest/adminguide/message-receipts.html), and update [`chat-interface`](https://github.com/amazon-connect/amazon-connect-chat-interface#message-receipts) to generate latest webpack bundle. |
166 | | - |
167 | | -To customize wait time before sending read/delivered receipt, set the throttle in global config: |
168 | | - |
169 | | -```js |
170 | | -connect.ChatSession.setGlobalConfig({ |
171 | | - // ... |
172 | | - features: { |
173 | | - messageReceipts: { |
174 | | - shouldSendMessageReceipts: true, |
175 | | - throttleTime: 5000 // default throttle time in ms - time to wait before sending |
176 | | - } |
177 | | - } |
178 | | -}); |
179 | | -``` |
180 | | - |
181 | | -## Disable message receipts |
182 | | - |
183 | | -By default, message receipts feature is enabled in ChatJs. [Disable in `chat-interface`](https://github.com/amazon-connect/amazon-connect-chat-interface#message-receipts) config and remove from the ChatJs config: |
184 | | - |
185 | | -```js |
186 | | -connect.ChatSession.setGlobalConfig({ |
187 | | - // ... |
188 | | - features: { |
189 | | - messageReceipts: { |
190 | | - shouldSendMessageReceipts: false, // default: true |
191 | | - } |
192 | | - } |
193 | | -}); |
194 | | -``` |
195 | | - |
196 | | -## Troubleshooting |
197 | | - |
198 | | -- After deploying the stack if you see an S3 permission error when viewing the CloudFront url, it means the domain is not ready yet. The CDN can take up to an hour to be ready. |
199 | | -- If you are able to initiate the first chat, but subsequent chats are not working (the chat widget just loads), make sure the S3 trigger is set up properly. When a chat is complete, the transcript is placed into the S3 bucket specified in the instance details in the Amazon Connect console. Verify that the location in the Amazon Connect console is the same as what you provided in the CloudFormation parameters `AmazonConnectS3BucketName` and `transcriptPath`. If this trigger is not set up properly, the DynamoDB table with the contact details is not updated to denote that the chat has ended and the Lambda function will continue to pull the ended chat's details instead of creating a new one. Another workaround to this is to clear the DynamoDB table. |
200 | | - |
| 1 | +# DEPRECATED |
| 2 | +`asyncCustomerChatUX` approach is no longer supported. Please go with [`startChatContactAPI`](https://github.com/amazon-connect/amazon-connect-chat-ui-examples/blob/master/cloudformationTemplates/startChatContactAPI/README.md) approach. `startChatContactAPI` now support persistent chat feature. With persistent chat, customers can resume previous conversations with the context, metadata, and transcripts carried forward. Customers don't need to repeat themselves when they return to a chat, and agents have access to the entire conversation history. [LEARN MORE](https://docs.aws.amazon.com/connect/latest/adminguide/chat-persistence.html) |
0 commit comments