# Create conversational AI bots in Amazon Connect You can use the Amazon Connect admin website to create, edit, and continuously improve conversational AI bots for interactive voice response (IVR) and chatbot self-service experiences. The bots are powered by Amazon Lex. By using the Amazon Connect admin website, you can deliver dynamic, conversational AI experiences to understand your customer's intent, ask follow-on questions, and automate the resolution of their issues. The topics in this section explain how to enable the bot building experience in Amazon Connect admin website, and how to build your bot. **Topics** + [Enable bot and analytics in Amazon Connect](enable-bot-building.md) + [Create a bot](work-bot-building-experience.md) + [Create a flow and add your conversational AI bot](create-bot-flow.md) + [Configure third-party speech providers](configure-third-party-speech-providers.md) + [Create an Connect AI agents intent](create-qic-intent-connect.md) + [Create bot versions and aliases](create-bot-version.md) + [Evaluate the performance of your conversational AI bot](lex-bot-analytics.md) + [Bot metrics and analytics](bot-metrics.md) + [Bot Advanced configuration](bot-advanced-config.md) + [Add an Amazon Lex bot](amazon-lex.md) # Enable bot building and analytics in Amazon Connect Complete the following steps to enable users to create Amazon Lex bots in the Amazon Connect admin website and view metrics about bot performance. Users can not edit LEX V1 bots or cross-regional bots from within Amazon Connect. 1. Open the [Amazon Connect console.](https://console.aws.amazon.com/connect/) 1. Select the Amazon Connect instance that you want to integrate with your Amazon Lex bot. ![\[The Amazon Connect virtual contact center instances page, the instance alias.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/instance.png) 1. On the navigation menu, choose **Flows**. 1. Choose **Enable Lex Bot Management in Amazon Connect** and **Enable Bot Analytics and Transcripts in Amazon Connect**, and then **Save**. ![\[The Amazon Lex bots page, the options to enable Lex bot management and analytics Amazon Connect.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/lex-bot-service-linked-role.png) **Note** If you already have existing Service Control Policies (SCP) in place that block access to Lex, Amazon Connect respects those policies and does not enable the Bot Management and Analytics feature. However, if you put those SCP policies in place after you've already enabled this feature, they won't be respected. In that case, you'll need to disable this feature. Amazon Connect displays the service role and service linked role name it uses. uses Amazon Lex resource-based policies to make calls to your Amazon Lex bot. When you associate an Amazon Lex bot with your Amazon Connect instance, the resource-based policy on the bot is updated to give Amazon Connect permission to invoke the bot. For more information about Amazon Lex resource-based policies, see [Resource-based policies within Amazon Lex V2](https://docs.aws.amazon.com/lexv2/latest/dg/security_iam_service-with-iam.html#security_iam_service-with-iam-resource-based-policies) in the *Amazon Lex V2 Developer Guide*. 1. Assign the following security profile permissions to users who need to create and manage bots and bot analytics: + **Channels and Flows** - **Bots** - **View**, **Edit**, **Create** permissions + **Analytics and Optimization** - **Historical metrics** - **Access** permission # Create a bot by using the Amazon Connect admin website You can build complete Lex bots in the Amazon Connect admin website without ever leaving the Amazon Connect interface. There is no charge for building or editing bots in Amazon Connect. Instead, you are billed by Amazon Lex for usage. For pricing information, see the [Amazon Lex pricing](https://aws.amazon.com/lex/pricing/) page. **To create a bot** 1. Log in to the Amazon Connect admin website at https://*instance name*.my.connect.aws/. Use an Admin account or an account that has **Channels and Flows** - **Bots** - **Create** permission in its security profile. 1. In the left navigation menu, choose **Routing**, **Flows**. 1. On the **Flows** page, choose **Bots**, **Create bot**. ![\[The Flows page, the Bots tab, the Create bot button.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/flows-bots-tab.png) 1. In the **Details** dialog box, provide the following information: + **Bot name**: Enter a unique name for the bot. + **Bot description**: - (Optional) Provide additional information about the purpose of the bot. + **Child Online Privacy Protection Act (COPPA)**: Choose whether the bot is subject to the Child Online Privacy Protection Act. The following image shows the **Details** dialog box and these options. ![\[Bot creation details page with name, description, and COPPA settings.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/bot-create.png) 1. Choose **Create**. After the bot is successfully created, you are directed to the bot configuration page. The following image shows an example page for a newly created bot named **HotelBookingBot**. ![\[A sample configuration page for an unconfigured bot.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/hotelbookingbot.png) 1. On the bot configuration page, choose **Add language**. Choose the primary language for your bot and your preferred way to create this language. ![\[A sample Define your bot page, the Add language dropdown box.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/bot-language-create.png) 1. After you choose your language, you are directed to the **Define your bot** section. An example section is shown in the following image. This section is where you'll add intents. ![\[A sample Define bot section.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/define-bot-page.png) ## Add intents to your bot In the **Define your bot** section, you add intents. Intents are the goals that your users want to accomplish, such as ordering flowers or booking a hotel. Your bot must have at least one intent. There are two types of intents: + Custom intents: Create intents that represent the actions or requests your bot should handle. This topic explains how to create custom intents. + Build-in intents: By default, all bots contain a single built-in intent, the fallback intent. This intent is used when the bot does not recognize any other intent. For example, if a user says "I want to order flowers" to a hotel booking intent, the fallback intent is triggered. The following image shows an example of a built-in intent. ![\[The Use built-in intent dialog box, a built-in intent names AMAZON.HelpIntent.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/built-in-intent.png) **To create a custom intent** 1. Choose **Add intent**, and then choose **Add empty intent**. 1. In the **Add intent** dialog box, enter a name for your intent and a description that's meaningful to you. Choose **Add**. 1. Enter the following information to configure your intent: + Add sample **Utterances**: Choose **Add** and then provide phrases or questions that users might use to express that intent. Choose **Save**. + Configure **Slots**: Choose **Add** and then define the slots, or parameters, required to fulfill the intent. Each slot has a type that defines the values that can be entered in the slot. Choose **Add** to add the slot. When you're done adding slots, choose **Save**. + Create **Prompts**: Choose **Edit** and then you can enter prompts that the bot will use to ask for information or clarify user inputs. Choose **Save** when finished. + **Initial response message**: The initial message sent to the user after the intent is invoked. You can provide responses, initialize values, and define the next step that the bot takes to respond to the user at the beginning of the intent. + **Confirmation prompt and responses**: These are used to confirm or decline fulfillment of the intent. The confirmation prompt asks the user to review slot values. For example, "I've booked a hotel room for Friday. Is this correct?" The declination response is sent to the user when they decline the confirmation. + **Closing response message**: This is the response sent to the user after the intent is fulfilled and all other messages are played. For example, "Thank you for booking a hotel room." For more information about intents for Amazon Lex bots intents and advanced configurations, see [Adding intents](https://docs.aws.amazon.com/lexv2/latest/dg/add-intents.html) in the *Amazon Lex V2 Developer Guide*. # Create a flow and add your conversational AI bot This topic explains how to add a previously created conversational AI bot to a flow. 1. On the navigation menu in Amazon Connect, choose **Routing**, **Flows**, **Create flow**, and type a name for the flow. 1. Under **Interact**, drag a [Get customer input](get-customer-input.md) block onto the designer, and connect it to the **Entry ** point block. 1. Choose the [Get customer input](get-customer-input.md) block to open it. 1. On the Amazon Lex tab, use the dropdown menus to select the bot you created earlier and the alias, as shown in the following image. ![\[The Get customer input block properties, the Amazon Lex tab.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/get-customer-input-lextab.png) 1. Under **Customer prompt or bot initialization**, choose **Text-to-speech or chat text**. 1. Type a message that provides callers with information about what they can do. For example, use a message that matches the intents used in the bot, such as *To check your account balance, press or say 1. To speak to an agent, press or say 2*. The following image shows this message on the properties page of the [Get customer input](get-customer-input.md) block. ![\[The customer prompt or bot initialization section of the Get customer input block.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/customer-prompt-bot-initialization.png) 1. Under **Intents**, choose **Add an intent**, and then enter or search for the customer intents that should trigger the bot. ![\[The Intents section, the Add an intent button, search button.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/add-intent.png) When you search for intents, you can filter by the locale. The locale is only used for filtering, it is not tied to the locale when the bot is triggered. For example, you might find the BookHotel intent by using the English (US) locale, but the intent can be successfully returned in both English (US) and English (GB). For more information on finding intents, see [How to find intents](#find-notlisted-intents). The following image shows the dialog box to filter intents by locale. ![\[The search option, the Filter using locale to add intent dialog box.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/filter-intents.png) 1. Choose **Save**. **Important** If you're using an Amazon Lex V2 bot, your language attribute in Amazon Connect must match the language model used to build your Lex bot. This is different than Amazon Lex (Classic). Use a [Set voice](set-voice.md#set-voice-lexv2bot) block to indicate the Amazon Connect language model, or use a [Set contact attributes](set-contact-attributes.md) block. ## How to find intents for Amazon Lex V1 bots, cross-Region bots, or dynamically set bots The **Intents** dropdown box does not list intents for Amazon Lex V1 bots, cross region bots, or if the bot ARN is dynamically set. For these intents, try the following options to find them. + Check whether the **AmazonConnectEnabled** tag is set to true: 1. Open the Amazon Lex console, choose **Bots**, select the bot, then choose **Tags**. 1. If the **AmazonConnectEnabled** tag is not present, add **AmazonConnectEnabled = true**. 1. Return to the Amazon Connect admin website. Refresh the flow designer to see the selections in **Get customer input** block. + Check if the version is associated with the alias: 1. In Amazon Connect admin website, choose **Routing**, **Flows**, the bot, **Aliases**. Verify that **Use in flow and flow modules** is enabled, as shown in the following image. ![\[The Aliases tab, the Use in flow and flow modules toggle.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/bot-alias-enabled.png) 1. Refresh the flow designer to see the selections in **Get customer input** block. # Configure third-party speech providers in Amazon Connect You can configure third-party speech-to-text (STT) and text-to-speech (TTS) providers in Amazon Connect to expand language coverage, improve recognition accuracy, and deliver more expressive synthesized speech. This section describes how to configure third-party STT providers for bots and third-party TTS providers for use in contact flows. **Topics** + [Configure third-party speech-to-text (STT) providers](configure-third-party-stt.md) + [Configure third-party text-to-speech (TTS) providers](configure-third-party-tts.md) + [Endpoints and Regions for third-party STT providers](endpoints-regions-third-party-stt.md) + [Managing secrets and resource policies](managing-secrets-resource-policies.md) # Configure third-party speech-to-text (STT) providers Use the following instructions to configure a third-party speech-to-text (STT) provider. ## Prerequisites + A bot with an existing locale. + A third-party STT provider API key stored in AWS Secrets Manager. For more information about storing API keys as secrets in Secrets Manager, see [Create an AWS Secrets Manager secret](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html). + An Secrets Manager resource policy allowing Amazon Connect to retrieve the secret. For more information, see [Managing secrets and resource policies](managing-secrets-resource-policies.md). + AWS KMS key permissions allowing decryption. For more information, see [Managing secrets and resource policies](managing-secrets-resource-policies.md). + A provider model ID and Secrets Manager ARN. ## Step 1: Open the speech model configuration panel 1. Sign in to the Amazon Connect admin website. 1. Choose **Bots**, then choose the bot. 1. Choose the locale. 1. In the **Speech model** section, choose **Edit** to open the configuration modal. ![\[The configuration page for your conversational AI bot.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/Lex/01-airlinesbot.png) ## Step 2: Choose the model type In the **Model type** dropdown, choose **Speech-to-Text (STT)**. This ensures the locale is configured for transcription rather than speech-to-speech. ![\[The speech model dialog box.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/Lex/02-speech-model.png) ## Step 3: Review the default speech model settings By default, Amazon is selected as the speech-to-text provider. Review the current settings before switching to a third-party provider. ![\[The speech model dialog box with Amazon selected as the voice provider.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/Lex/03-speech-model-amazon.png) ## Step 4: Choose a third-party STT provider Open the **Voice provider** dropdown and choose a supported third-party speech-to-text provider. ![\[The speech model dialog box with Deepgram selected as the voice provider.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/Lex/04-speech-model-deepgram.png) ## Step 5: Enter the model ID and Secrets Manager ARN 1. In **Model ID**, enter the provider's model name. + Some providers require a minimum or maximum length. + Model IDs are case-sensitive and must match provider documentation. 1. In **Secrets Manager ARN**, enter the ARN of the secret that contains the provider API key. + The secret must be in the same Region as your Amazon Connect instance. + Secrets Manager and KMS key policies must permit Amazon Connect to access and decrypt the key. For more information, see [Managing secrets and resource policies](managing-secrets-resource-policies.md). 1. Choose **Continue** to save your changes. ## Build and activate the locale If the locale shows **Unbuilt changes**, choose **Build language**. The new STT settings become active after a successful build. ## Runtime behavior (STT) + Amazon Connect routes audio to the chosen third-party speech-to-text provider. + No changes to flows or Lambda functions are required. + Errors such as invalid credentials or invalid model IDs appear in logs. + Metrics and analytics continue to function normally. ## Troubleshooting (STT) + **Invalid model ID**: Confirm the value with provider documentation. + **Access denied**: Verify Secrets Manager and KMS permissions. + **Locale build fails**: Ensure required fields are valid. + **High latency**: Validate the provider region configuration. # Configure third-party text-to-speech (TTS) providers Use the following instructions to configure a third-party text-to-speech (TTS) provider. ## Prerequisites + A contact flow exists (or you have permission to create one). + A third-party TTS provider API key stored in AWS Secrets Manager. For more information about storing API keys as secrets in Secrets Manager, see [Create an AWS Secrets Manager secret](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html). + An Secrets Manager resource policy allowing Amazon Connect to retrieve the key. For more information, see [Managing secrets and resource policies](managing-secrets-resource-policies.md). + AWS KMS key permissions allowing decryption. For more information, see [Managing secrets and resource policies](managing-secrets-resource-policies.md). + Provider-specific model and voice values. ## Step 1: Open the contact flow 1. Sign in to the Amazon Connect admin website. 1. Choose **Flows**. 1. Choose an existing flow or create a new one. ## Step 2: Add or choose a Set voice block 1. In the Flow designer, search for **Set voice**. 1. Drag the block onto the canvas or choose an existing one. 1. Choose the block to open its configuration panel. ## Step 3: Choose a third-party TTS provider In the **Voice provider** dropdown, choose the third-party text-to-speech provider you want to use. ![\[The 'Set voice' configuration pane showing a drop-down list of voice providers.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/Lex/08-set-voice-amazon.png) ## Step 4: Specify model, voice, Secrets Manager ARN, and language 1. Under **Model**, choose **Set manually** and enter the provider model. 1. Under **Voice**, choose **Set manually** and enter the provider voice. 1. Under **Secrets Manager ARN**, choose **Set manually** and enter the ARN of the provider secret. + The secret must be in the same AWS Region. + AWS Secrets Manager and KMS policies must permit retrieval and decryption. For more information, see [Managing secrets and resource policies](managing-secrets-resource-policies.md). 1. Under **Language**, choose **Set manually** and choose a language that is supported by the provider voice. ![\[The 'Voice provider' configuration pane showing the ElevenLabs third-party voice provider.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/Lex/09-voice-provider-elevenlabs.png) ## Step 5: Save and publish the flow 1. Choose **Save** in the Flow designer. 1. Choose **Publish** to activate the updated flow settings. ## Runtime behavior (TTS) + Amazon Connect sends text to the TTS provider for synthesis. + Returned audio is played to the customer. + Execution logs include provider errors such as invalid credentials or model values. ## Troubleshooting (TTS) + **No audio output**: Validate model and voice values. + **Authentication errors**: Verify Secrets Manager and KMS permissions. + **Dynamic attributes**: Ensure runtime values resolve to valid provider parameters. + **High latency**: Validate provider region alignment. # Endpoints and Regions for third-party STT providers By default, Amazon Connect communicates with the following endpoints: **Deepgram**: [https://api.deepgram.com](https://api.deepgram.com) **ElevenLabs**: [https://api.elevenlabs.io](https://api.elevenlabs.io) You can specify a different provider Region alongside your API key as part of the JSON object: ``` { "apiToken": "XXXXX", "apiTokenRegion": "xx" } ``` The following regions are supported: | **Provider** | **apiTokenRegion** | **Endpoint** | | --- | --- | --- | | Deepgram | eu | [https://api.eu.deepgram.com](https://api.eu.deepgram.com) (only supported for speech-to-text) | | Deepgram | \$1SHORT\$1UID\$1.\$1REGION\$1SUBDOMAIN\$1 | https://\$1SHORT\$1UID\$1.\$1REGION\$1SUBDOMAIN\$1.api.deepgram.com (Deepgram Dedicated endpoints) | | ElevenLabs | us | [https://api.us.elevenlabs.io](https://api.us.elevenlabs.io) | | ElevenLabs | eu | [https://api.eu.residency.elevenlabs.io](https://api.eu.residency.elevenlabs.io) | | ElevenLabs | in | [https://api.in.residency.elevenlabs.io](https://api.in.residency.elevenlabs.io) | # Managing secrets and resource policies When you [configure a third-party speech provider](configure-third-party-speech-providers.md), you will need to create a secret in Secrets Manager that contains the speech provider's API key. Creating the secret is a two step process: + Create the secret containing the API key. For instructions, see [Create an AWS Secrets Manager secret](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html). + Configure the necessary permissions: + Attach a resource-based policy to the secret. + Attach a resource-based policy to the KMS key (not the API key) associated with the secret. The KMS key protects the API key in the secret. These policies allow Amazon Connect to access to the API key within the secret. Note that you cannot use the default `aws/secretsmanager` KMS key; you will have to create a new key or use an existing customer-managed key. For more information about how KMS keys secure secrets, see [Secret encryption and decryption in Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/security-encryption.html). Make sure that the resource-based policy for the secret includes the `aws:SourceAccount` and `aws:SourceArn` confused deputy conditions (see [The confused deputy problem](https://docs.aws.amazon.com/IAM/latest/UserGuide/confused-deputy.html)) and that the resource-based policy for the KMS key includes the `kms:EncryptionContext:SecretARN` condition. This will ensure that Amazon Connect can only access your API key secret in context of a single specific instance, and can only access your KMS key in context of both that instance and the specific secret. ## Example of a resource-based policy for Secrets Manager secrets The following is an example of a resource-based policy that you can attach to your secret. ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": [ "connect.amazonaws.com" ] }, "Action": "secretsmanager:GetSecretValue", "Resource": "*", "Condition": { "ArnLike": { "aws:sourceArn": "///the ARN of your Amazon Connect instance///" }, "StringEquals": { "aws:sourceAccount": "///Your account ID///" } } } ] } ``` ## Example of a resource-based policy for AWS KMS keys The following is an example of a resource-based policy that you can attach to your KMS key. ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": [ "connect.amazonaws.com" ] }, "Action": "kms:Decrypt", "Resource": "*", "Condition": { "ArnLike": { "aws:sourceArn": "///the ARN of your Amazon Connect instance///" }, "StringEquals": { "aws:sourceAccount": "///Your account ID///", "kms:EncryptionContext:SecretARN": "///the ARN of your secrets manager secret///" } } } ] } ``` ## Attaching a resource-based policy to your Secrets Manager secret To attach a resource-based policy to your secret, go to the Secrets Manager console within the AWS Management Console, navigate to your secret, choose **Edit Permissions** or **Resource Permissions** and then add or modify the resource policy directly on the page so that it looks similar to the [example](#example-resource-policy-secrets-manager). You can also attach the resource policy through the AWS CLI's `put-resource-policy` command, or programmatically using the [PutResourcePolicy](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_PutResourcePolicy.html) API operation. ## Attaching a resource-based policy to your KMS key To attach a resource-based policy to your KMS key, go to the AWS Key Management Service console within the AWS Management Console, navigate to your KMS key and edit your key policy to look like the [example](#example-resource-policy-kms-keys). You can also update the key through the AWS CLI's `put-key-policy` command, or programmatically using the [PutKeyPolicy](https://docs.aws.amazon.com/kms/latest/APIReference/API_PutKeyPolicy.html) API operation. ## Rotating API keys We recommend rotating API keys at least every 90 days to minimize the risk of compromise, and to maintain a well-practiced key rotation process for emergency situations. To rotate an API key, you must rotate the secret in which it is contained. See [Rotate Secrets Manager secrets](https://docs.aws.amazon.com/secretsmanager/latest/userguide/rotating-secrets.html) in the *Secrets Manager User Guide* for more information on how to rotate secrets. When you rotate an API key, it is recommended that you wait for the previous key's usage to drop to zero before revoking the old API key to ensure that ongoing requests are not impacted. # Create an Connect AI agents intent from an Amazon Connect instance You can use the generative AI capabilities powered by Connect AI agents for your bot by enabling the [AMAZON.QinConnectIntent](https://docs.aws.amazon.com/lexv2/latest/dg/built-in-intent-qinconnect.html) in your bot. This is an Amazon Lex built-in intent. Complete the following steps to enable Connect AI agents. 1. Open the bot for which you want to add the **AMAZON.QinConnectIntent** intent. 1. Navigate to the **Configuration** tab in the bot builder interface. 1. Enable the **AMAZON.QinConnectIntent** intent by setting the toggle to on. The following image shows the location of the toggle. ![\[A sample configuration page for an unconfigured bot.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/enable-qic-bot.png) The **Connect AI agents intent** toggle is only supported for bots created directly within the Amazon Connect admin website. To add Amazon Q capabilities to intents for bots created outside of Amazon Connect admin website, use the Amazon Lex console to update the configuration. 1. In the **Enable Connect AI agents intent **dialog box, use the dropdown menu to choose the Amazon Resource Name (ARN) of the Connect AI agents intent. ![\[A Enable Connect AI agents intent dialog box.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/qic-intent-dropdownbox.png) 1. Choose **Confirm** to add **AMAZON.QinConnectIntent** intent support. **Important** You cannot use **AMAZON.QInConnectIntent** along with intents without specific utterances such as **AMAZON.QnAIntent**, **AMAZON.BedrockAgentIntent** in the same bot locale. For more information, see [AMAZON.QinConnectIntent](https://docs.aws.amazon.com/lexv2/latest/dg/built-in-intent-qinconnect.html) in the *Amazon Lex V2 Developer Guide*. # Create bot versions and aliases in Amazon Connect To control which bot implementation your client uses, you create versions and aliases. + A version acts as a numbered snapshot of your work. + You can point an alias to the version of your bot that you want to be available to your customers. In between creating versions, you can continue to update the Draft version of your bot without affecting your customer's experience. This process is crucial for deploying bots in a production environment. ## Create a version Creating a new version preserves the current state of your bot configuration. Complete the following steps to create a new version of your Amazon Lex bot in Amazon Connect. 1. Open the bot for which you want to create a new version. 1. Choose the **Versions** tab, and then choose **Create version**. ![\[The Versions tab, the Create version button.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/bot-versionstab.png) 1. In the **Create version** dialog box: 1. Enter a version description (optional, but recommended for tracking changes) 1. Choose **Create**. The following image shows an example **Create version** dialog box. ![\[A Create version dialog box.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/create-version-bot.png) After the version is created, you can associate it with aliases or you can use it to revert to a previous state of your bot. ## Create an alias An alias is a pointer to a specific version of a bot. With an alias, you can easily update the version that your client applications are using. For example, you can point an alias to version 1 of your bot. When you are ready to update the bot, you create version 2 and change the alias to point to the new version. Because your applications use the alias instead of a specific version, all of your clients get the new functionality without needing to be updated. This allows for controlled rollouts and easy version management. **Important** If you want to use the bot in a flow, be sure to choose **Enable for use in flow and flow modules** when you create an alias. Complete the following steps to create an alias for your Amazon Lex bot. 1. Open the bot for which you want to add the alias. 1. Choose the **Aliases** tab, and then choose **Create aliases**. ![\[The Alias tab, the Create aliases button.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/bot-aliases-button.png) 1. In the **Create Alias** dialog box: 1. Enter a unique name for the alias. 1. Provide a description for the alias (optional, but recommended). 1. Select the bot version you want to associate with this alias. 1. (Recommended) Choose **Enable for use in flow and flow modules**. This is required if you want to use the bot in a flow. 1. Choose **Create**. The following image shows an example **Create alias** dialog box. ![\[A Create Alias dialog box.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/bot-create-alias.png) For more information about versioning and aliasing in Amazon Lex V2, see [Versioning and aliases with your Lex V2 bot](https://docs.aws.amazon.com/lexv2/latest/dg/versions-aliases.html) in the *Amazon Lex V2 Developer Guide*. # Evaluate the performance of your conversational AI bot in Amazon Connect You can use the comprehensive analytics tools in Amazon Connect to help you evaluate and optimize your conversational AI bot performance. These insights enable you to identify successful interactions, pinpoint failure points, and visualize conversation patterns to continuously improve customer experience. The analytics dashboard includes key metrics such as Utterance recognition rate and Conversation performance. These metrics help you understand both the success and failure rates of your bot's interactions with customers. **Note** The Bot Analytics page shows data for conversations triggered only from flows. You can trigger bots externally using Lex APIs or custom integrations, but data for those conversations are not reflects on this page. **To view analytics for your bot** 1. Log in to the Amazon Connect admin website at https://*instance name*.my.connect.aws/. Use an Admin account or an account that has the following permissions in its security profile: + **Channels and Flows** - **Bots** - **View** + **Channels and Flows** - **Bots** - **Edit** + **Analytics and Optimization** - **Historical metrics** - **Access** 1. In the left navigation menu, choose **Routing**, **Flows**. 1. On the **Flows** page, choose **Bots**, choose the bot whose performance you want to evaluate, and then choose **Analytics**. ![\[The Flows page, the Analytics tab.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/bot-analytics1.png) The following image shows sample analytics data. ![\[The Analytics tab with sample analytics data for a bot.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/bot-analytics.png) Use these analytics to identify improvement opportunities, refine your bot's responses, and enhance the overall customer experience. For additional metrics and advanced analysis techniques specific to Amazon Lex, see [Monitoring bot performance in Lex V2](https://docs.aws.amazon.com/lexv2/latest/dg/monitoring-bot-performance.html). # Amazon Connect bot metrics and analytics The following flow driven metrics are available on the [Flows and conversational bot performance dashboard](flows-performance-dashboard.md) and the [GetMetricDataV2](https://docs.aws.amazon.com/connect/latest/APIReference/API_GetMetricDataV2.html). ## Average bot conversation time This metric measures the average duration of completed conversations for which the invoking resource (flow or flow module) started between the specified start and end time. **Metric type**: String (*hh:mm:ss*) **Metric category**: Flow driven metric **How to access using the Amazon Connect API**: + [GetMetricDataV2](https://docs.aws.amazon.com/connect/latest/APIReference/API_GetMetricDataV2.html) API metric identifier: `AVG_BOT_CONVERSATION_TIME` It can be filtered on specific conversation outcomes with `BOT_CONVERSATION_OUTCOME_TYPE` metric level filter. **Calculation logic**: + Sum(Conversation Start Time - Conversation End Time of all filtered conversations) / (Count of all filtered conversations) **Notes**: + Data for this metric is available starting from December 2, 2024 00:00:00 GMT. ## Average bot conversation turns This metric provides the average number of turns for completed conversations for which the invoking resource (flow or flow module) started between the specified start and end time. A single turn is a request from the client application and a response from the bot. **Metric type**: Double **Metric category**: Flow driven metric **How to access using the Amazon Connect API**: + [GetMetricDataV2](https://docs.aws.amazon.com/connect/latest/APIReference/API_GetMetricDataV2.html) API metric identifier: `AVG_BOT_CONVERSATION_TURNS` It can be filtered on specific conversation outcomes with `BOT_CONVERSATION_OUTCOME_TYPE` metric level filter. **Calculation logic**: + Sum(Conversation Turn of all filtered conversations) / (Count of all filtered conversations) **Notes**: + Data for this metric is available starting from December 2, 2024 00:00:00 GMT. ## Bot conversations completed This metric provides the count of completed conversations for which the invoking resource (flow or flow module) started between the specified start and end time. The conversation end time can be beyond the specified end time. For example, if you request this metric with start time at 9 AM and end time at 10 AM, the result includes conversations where the invoking resource (flow or flow module): + started at 9:15 AM and ended at 9:40 AM + started at 9:50 AM and ended at 10:10 AM but will exclude conversations for which the invoking resource (flow or flow module): + started at 8:50 AM and ended at 9:10 AM **Metric type**: Integer **Metric category**: Flow driven metric **How to access using the Amazon Connect API**: + [GetMetricDataV2](https://docs.aws.amazon.com/connect/latest/APIReference/API_GetMetricDataV2.html) API metric identifier: `BOT_CONVERSATIONS_COMPLETED` It can be filtered on the following conversation outcomes using metric level filter `BOT_CONVERSATION_OUTCOME_TYPE`. + SUCCESS: The final intent in the conversation is categorized as *success*. + FAILED: The final intent in the conversation is failed. The conversation is also failed if Amazon Lex V2 defaults to the `AMAZON.FallbackIntent`. + DROPPED: The customer does not respond before the conversation is categorized as *success* or *failed*. **Calculation logic**: + Total count of conversations. **Notes**: + Data for this metric is available starting from December 2, 2024 00:00:00 GMT. ## Bot intents completed This metric provides the count of completed intents. It includes intents for completed conversations where the invoking resource (flow or flow module) started between the specified start and end time. **Metric type**: Integer **Metric category**: Flow driven metric **How to access using the Amazon Connect API**: + [GetMetricDataV2](https://docs.aws.amazon.com/connect/latest/APIReference/API_GetMetricDataV2.html) API metric identifier: `BOT_INTENTS_COMPLETED` It can be filtered on the following conversation outcomes using metric level filter `BOT_CONVERSATION_OUTCOME_TYPE`. It can be filtered on the following intent outcomes using metric level filter `BOT_INTENTS_OUTCOME_TYPE`. + SUCCESS: The bot successfully fulfilled the intent. One of the following situations is true: + The intent *state* is *ReadyForFulfillment* and the type of *dialogAction* is *Close*. + The intent `state` is `Fulfilled` and the type of `dialogAction` is `Close`. + FAILED: The bot failed to fulfill the intent. The intent state. One of the following situations is true: + The intent `state` is `Failed` and the `type` of `dialogAction` is `Close` (for example, the user declined the confirmation prompt). + The bot switches to the `AMAZON.FallbackIntent` before the intent is completed. + SWITCHED: The bot recognizes a different intent and switches to that intent instead, before the original intent is categorized as a *success* or *failed*. + DROPPED: The customer does not respond before the intent is categorized as *success* or *failed*. **Calculation logic**: + Total count of intents. **Notes**: + Data for this metric is available starting from December 2, 2024 00:00:00 GMT. ## Percent bot conversations outcome This metric provides the percentage of total conversations that ended in the specific outcome type specified in the metric level filter (`BOT_CONVERSATION_OUTCOME_TYPE`). It only includes completed conversations for which the invoking resource (flow or flow module) started between the specified start and end time. **Metric type**: Percent **Metric category**: Flow driven metric **How to access using the Amazon Connect API**: + [GetMetricDataV2](https://docs.aws.amazon.com/connect/latest/APIReference/API_GetMetricDataV2.html) API metric identifier: `PERCENT_BOT_CONVERSATIONS_OUTCOME` **How to access using the Amazon Connect admin website**: **Calculation logic**: + (Count of conversations with BOT\$1CONVERSATION\$1OUTCOME\$1TYPE)/(Total count of conversations) \$1 100 **Notes**: + Data for this metric is available starting from December 2, 2024 00:00:00 GMT. ## Percent bot intents outcome This metric provides the percentage of intents that ended in the specific outcome type specified in the metric level filter (`BOT_INTENT_OUTCOME_TYPE`). It includes intents in completed conversations where the invoking resource (flow or flow module) started between the specified start and end time. **Metric type**: Percent **Metric category**: Flow driven metric **How to access using the Amazon Connect API**: + [GetMetricDataV2](https://docs.aws.amazon.com/connect/latest/APIReference/API_GetMetricDataV2.html) API metric identifier: `PERCENT_BOT_INTENTS_OUTCOME` **How to access using the Amazon Connect admin website**: **Calculation logic**: + (Count of intents with BOT\$1INTENT\$1OUTCOME\$1TYPE)/(Total count of intents) \$1 100 # Bot Advanced configuration support from Amazon Connect The advanced configuration feature enables you to make detailed customizations to your bot without going to the Amazon Lex console. 1. On the Amazon Connect admin website, in the left navigation, choose **Flows**. Choose the **Bots** tab, and then choose the bot you want to work with. 1. Choose the **Advanced configurations** button, as shown in the following image. ![\[The Advanced configurations button on a bot details page.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/bot-advanced-config.png) This action will switch the view to a more detailed interface where you can access more features to customize your bot. 1. To switch back to the simple bot user interface, choose **Configuration summary**, as shown in the following image. ![\[An Advanced configuration page, the Configuration summary button.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/bot-adv-config2.png) # Add an Amazon Lex bot to Amazon Connect **Important** **End of support notice**: On September 15, 2025, AWS will discontinue support for Amazon Lex V1. After September 15, 2025, you will no longer be able to access the Amazon Lex V1 console or Amazon Lex V1 resources. To learn about migrating to Amazon Lex V2, see [Migrating a bot](https://docs.aws.amazon.com/lex/latest/dg/migrate.html). In this article we guide you through the steps to add an Amazon Lex bot to Amazon Connect. With Amazon Lex, you can build conversational interactions (bots) that feel natural to your customers. Amazon Connect with Amazon Lex bots can also capture customer input as digits that customers enter on their numeric keypad when used in an Amazon Connect flow. This way customers can choose how they want to enter sensitive information such as account numbers. To follow along with this walkthrough, you need the following: + An active AWS account. + An Amazon Connect instance. **Tip** You can also use Amazon Lex to power interactive messages for Amazon Connect chat. Interactive messages are rich messages that present a prompt and pre-configured display options that a customer can select from. These messages are powered by Amazon Lex and configured through Amazon Lex using a Lambda. For more information, see [Add Amazon Lex interactive messages for customers in chat](interactive-messages.md). ## Create an Amazon Lex bot In this step you'll create a custom bot to demonstrate the Press or Say integration with Amazon Connect. The bot prompts callers to press or say a number that matches the menu option for the task to complete. In this case, the input is checking their account balance. ------ #### [ Amazon Lex ] 1. Open the [Amazon Lex console.](https://console.aws.amazon.com/lexv2/home) 1. Choose **Create bot**. 1. On the **Configure bot settings** page, choose **Create - Create a blank bot** and provide the following information: + **Bot name** — For this walkthrough, name the bot **AccountBalance**. + **IAM permissions** — Select a role if you have one created. Otherwise, choose **Create a role with basic Amazon Lex permissions**. + **COPPA** — Choose whether the bot is subject to the Child Online Privacy Protection Act. + **Session timeout** — Choose how long the bot should wait to get input from a caller before ending the session. 1. Choose **Next**. 1. Provide language and voice specific information: + **Language** — Select language and locale from the list of [Languages and locales supported by Amazon Lex](https://docs.aws.amazon.com/lexv2/latest/dg/how-languages.html). + **Voice interaction** — Select the voice for your bot to use when speaking to callers. The default voice for Amazon Connect is Joanna. 1. Choose **Done**. The AccountBalance bot is created, and the **Intent** page is displayed. ------ #### [ Amazon Lex (Classic) ] 1. Open the [Amazon Lex console.](https://console.aws.amazon.com/lex/) 1. If you are creating your first bot, choose **Get Started**. Otherwise, choose **Bots, Create**. 1. On the **Create your bot** page, choose **Custom bot** and provide the following information: + **Bot name** — For this walkthrough, name the bot **AccountBalance**. + **Output voice** — Select the voice for your bot to use when speaking to callers. The default voice for Amazon Connect is Joanna. + **Session timeout** — Choose how long the bot should wait to get input from a caller before ending the session. + **COPPA** — Choose whether the bot is subject to the Child Online Privacy Protection Act. 1. Choose **Create**. ------ ## Configure the Amazon Lex bot In this step you'll determine how the bot responds to customers by providing intents, sample utterances, slots for input, and error handling. For this example, you'll configure the bot with two intents: one to look up account information, and another to speak with an agent. ### Create AccountLookup intent ------ #### [ Amazon Lex ] 1. After you created the bot, you are on the **Intents** page the Amazon Lex console. If you're not there, you can get there by choosing **Bots**, **AccountBalance**, **Bot versions**, **Draft version**, **Intents**. Choose **Add intent**, **Add empty intent**. 1. In the **Intent name** box, enter **AccountLookup**. 1. Scroll down the page to **Sample utterances**. In this step you enter utterances that allow the customer to elicit the AccountLookup intent. Enter the following utterances, and choose **Add utterance** after each one. + **Check my account balance** + **One**: This assigns the utterance of "one" or key press of "1" to the **AccountLookup** intent. The following image shows where to add the utterance in the **Sample utterances** section. ![\[The sample utterances section of the Intents page.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/lexv2-enter-utterances.png) 1. Scroll to the **Slots** section, and choose **Add slot**. Complete the box as follows: 1. **Required for this intent** = selected. 1. **Name** = **AccountNumber**. 1. **Slot type** = **AMAZON.Number**. 1. **Prompts** = the text to be spoken when the call is answered. For example, ask callers to enter their account number using their keypad: **Using your touch-tone keypad, please enter your account number**. Choose **Add**. The following image shows a completed **Add slot** section. ![\[The add slot section of the Intents page.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/lexv2-add-slots.png) 1. Scroll to the **Closing responses** section. Add a message for the bot to say to customers. For example, **Your account balance is \$11,234.56**. (For this walkthrough, we aren't going to actually get the data, which is what you would do in reality.) The following image shows a completed **Closing responses** section. ![\[The closing responses section of the Intents page.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/lexv2-response1.png) 1. Choose **Save intent**. ------ #### [ Amazon Lex (Classic) ] 1. In the Amazon Lex console choose the **\$1** icon next to **Intents**, and choose **Create new intent**. 1. Name the intent **AccountLookup**. 1. Add a sample utterance, such as *Check my account balance*, and choose the **\$1** icon. 1. Add a second utterance, such as *One* and choose the **\$1** icon. This assigns the utterance of "one" or key press of "1" to the **AccountLookup** intent. **Tip** You must add an utterance of "one" in the bot, and not the number "1". This is because Amazon Lex doesn't support numeric input directly. To get around this, later in this walkthrough you'll use numeric input to interact with a Lex bot invoked from a flow. 1. Under **Slots**, add a slot named **AccountNumber**. The following image shows the location of the **Slots** section on the page. ![\[The slot section on the Intents page.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/lex-slots.png) 1. For **Slot type**, use the drop-down to choose **AMAZON.NUMBER**. 1. For **Prompt**, add the text to be spoken when the call is answered. For example, ask callers to enter their account number using their keypad: *Using your touch-tone keypad, please enter your account number*. 1. Choose the \$1 icon. 1. Make sure that the **Required **check box is selected. 1. In the **Response** section, add a message for the bot to say to customers. For example, **Your account balance is \$11,234.56**. 1. Choose **Save Intent**. ------ ### Create SpeakToAgent intent ------ #### [ Amazon Lex ] 1. Navigate to the **Intents** page: choose **Back to intents list**. 1. Choose **Add intent**, **Add empty intent**. 1. In the **Intent name** box, enter **SpeakToAgent**, and then choose **Add**. 1. Scroll down to **Sample utterances** section. Enter the following utterances, which allow the customer to elicit the SpeakToAgent intent: + **Speak to an agent** + **Two** 1. Scroll down to the **Closing responses** section. Add a message for the bot to say to customers. For example, **Okay, an agent will be with you shortly**. 1. Choose **Save intent**. ------ #### [ Amazon Lex (Classic) ] 1. In the Amazon Lex console choose the **\$1** icon next to **Intents**, and choose **Create new intent**. 1. Name the intent **SpeakToAgent**. 1. Select **SpeakToAgent**. 1. Add a sample utterance, such as *Speak to an agent*, and choose **\$1**. 1. Add a second utterance, such as *Two*, and choose **\$1**. 1. Add a message that lets callers know that their call is being connected to an agent. For example, "Okay, an agent will be with you shortly." 1. Choose **Save Intent**. ------ ## Build and test the Amazon Lex bot After you create your bot, make sure it works as intended. ------ #### [ Amazon Lex ] 1. At the bottom of the page, choose **Build**. It may take a minute or two. The following image shows where the **Build** button is located. ![\[The location of the Build button on the page.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/lexv2-build-test-intent.png) 1. When it's finished building, choose **Test**. 1. Let's test the **AccountLookup** intent: In the **Test Draft version** pane, in the **Type a message** box, type **1** and press Enter. Then type a fictitious account number and press Enter. The following image shows where you enter intent. ![\[The box where you type the intent to test.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/lexv2-test1.png) 1. Clear the test box. 1. Type the intents you want to test. 1. To confirm that the **SpeakToAgent** intent is working, clear the test box, and then type **2** and press Enter. The following image shows what the test looks like after you clear it and then enter 2. ![\[The test box.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/lexv2-test2.png) 1. Close the **Test Draft version** pane. ------ #### [ Amazon Lex (Classic) ] 1. Choose **Build**. It may take a minute or two. 1. When it's finished building, choose **Test Chatbot**, as shown in the following image. ![\[The test chatbot button, on the right side of the page.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/lex-test-chatbot.png) 1. Let's test the **AccountLookup** intent: In the **Test Chatbot** pane, in the **Chat with your bot** box, type **1**. Then type a fictitious account number. In the following image, the arrow points to the box where you type 1. ![\[The test bot, the box for typing your message.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/lex-test-run.png) 1. Choose **Clear chat history**. 1. To confirm that the **SpeakToAgent** intent is working, type **2**. ------ ## Create a bot version (Optional) In this step you create a new bot version to use in an alias. It's how you create an alias that can be used in a production environment. Test aliases are subject to lower throttling limits. Although this is a test walkthrough, creating a version is a best practice. ------ #### [ Amazon Lex ] 1. If you're on the **Intents** page, choose **Back to intents list**. 1. On the left menu, choose **Bot versions**. 1. Choose **Create version**. 1. Review the details of the **AccountBalance** bot, and then choose **Create**. This creates a version of your bot (Version 1). You can switch versions on an non-test alias without having to track which version is getting published. ![\[The Versions page with Version 1 listed.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/lexv2-version1.png) ------ ## Create an alias for the bot ------ #### [ Amazon Lex ] 1. In the left menu, choose **Aliases**. 1. On the **Aliases** page, choose **Create alias**. 1. In the **Alias name** box, enter a name, such as **Test**. Later in this walkthrough you'll use this alias to specify this version of the bot in your flow. **Important** In a production environment, always use a different alias than **TestBotAlias** for Amazon Lex and **\$1LATEST** for Amazon Lex classic. **TestBotAlias** and **\$1LATEST** support a limited number of concurrent calls to an Amazon Lex bot. For more information, see [Runtime quotas](https://docs.aws.amazon.com/lexv2/latest/dg/quotas.html#quotas-service). 1. For **Associated version**, choose the version you just created, such as **Version 1**. 1. Choose **Create**. ------ #### [ Amazon Lex (Classic) ] 1. Choose **Publish**. 1. Provide an alias for your bot. Use the alias to specify this version of the bot in the flow, for example, **Test**. **Important** In a production environment, always use a different alias than **TestBotAlias** for Amazon Lex and **\$1LATEST** for Amazon Lex classic. **TestBotAlias** and **\$1LATEST** support a limited number of concurrent calls to an Amazon Lex bot. For more information, see [Runtime Service Quotas](https://docs.aws.amazon.com/lex/latest/dg/gl-limits.html#gl-limits-runtime). 1. Choose **Publish**. ------ ## Add the Amazon Lex bot to your Amazon Connect instance ------ #### [ Amazon Lex ] 1. Open the [Amazon Connect console.](https://console.aws.amazon.com/connect/) 1. Select the Amazon Connect instance that you want to integrate with your Amazon Lex bot. ![\[The Amazon Connect virtual contact center instances page, the instance alias.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/instance.png) 1. On the navigation menu, choose **Flows**. 1. Under **Amazon Lex**, use the dropdown to select the Region of your Amazon Lex bot, and then select your Amazon Lex bot, **AccountBalance**. 1. Select the Amazon Lex bot alias name from the dropdown (**Test**), and then choose **\$1 Add Lex Bot**. The following image shows Amazon Lex section after it has been configured. ![\[The Amazon Lex section of the flows page.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/lexv2-region-bot.png) **Note** Amazon Connect uses Amazon Lex resource-based policies to make calls to your Amazon Lex bot. When you associate an Amazon Lex bot with your Amazon Connect instance, the resource-based policy on the bot is updated to give Amazon Connect permission to invoke the bot. For more information on Amazon Lex resource-based policies, see [How Amazon Lex works with IAM](https://docs.aws.amazon.com/lexv2/latest/dg/security_iam_service-with-iam.html#security_iam_service-with-iam-resource-based-policies). ------ #### [ Amazon Lex (Classic) ] 1. Open the [Amazon Connect console.](https://console.aws.amazon.com/connect/) 1. Select the Amazon Connect instance that you want to integrate with your Amazon Lex bot. 1. On the navigation menu, choose **Contact flows**. 1. Under **Amazon Lex**, select the Region of your Amazon Lex classic bot from the dropdown, and then select your Amazon Lex classic bot. It’s name will have the suffix "(Classic)". Then choose **Add Lex Bot**. ------ ## Create a flow and add your Amazon Lex bot **Important** If you're using an Amazon Lex V2 bot, your language attribute in Amazon Connect must match the language model used to build your Lex bot. This is different than Amazon Lex (Classic). Use a [Set voice](set-voice.md#set-voice-lexv2bot) block to indicate the Amazon Connect language model, or use a [Set contact attributes](set-contact-attributes.md) block. Next, create a new flow that uses your Amazon Lex bot. When you create the flow, you configure the message played to callers. 1. Log in to your Amazon Connect instance with an account that has permissions for contact flows and Amazon Lex bots. 1. On the navigation menu, choose **Routing, Flows, Create Flow**, and type a name for the flow. 1. Under **Interact**, drag a [Get customer input](get-customer-input.md) block onto the designer, and connect it to the **Entry point block**. 1. Choose the **Get customer input** block to open it. Choose **Text to speech or chat text, Enter text**. 1. Type a message that provides callers with information about what they can do. For example, use a message that matches the intents used in the bot, such as "To check your account balance, press or say 1. To speak to an agent, press or say 2." The following image shows this message on the Properties page of the **Get customer input** block. ![\[The Properties page of the Get customer input block.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/lex-get-customer-input.png) 1. Select the **Amazon Lex** tab, as shown in the following image. ![\[The Amazon Lex tab on the Properties page of the Get customer input block.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/lexv2-get-customer-input2.png) 1. In the **Name** dropdown, select the **AccountBalance** bot you created earlier. 1. If you selected an Amazon Lex bot, under **Alias** use the dropdown menu to select the bot alias, **Test**. from 1. Amazon Lex Classic bots have the suffix "(Classic)" appended to their names. If you have selected a Classic bot, enter the alias you want to use in the **Alias** field. 1. For Amazon Lex V2 bots, you also have the option of manually setting a bot alias ARN. Choose **Set manually**, then either type the ARN of the bot alias you want to use or set the ARN using a dynamic attribute. 1. Under **Intents**, choose **Add an intent**. 1. Type **AccountLookup** and choose **Add another intent**. The following image shows the **Intents** section configured with this information. ![\[The Intents section of Amazon Lex tab.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/lex-get-customer-input3.png) 1. Type **SpeakToAgent** and choose **Save**. ### Finish the flow In this step you finish adding parts to the flow that run after the caller interacts with the bot: 1. If the caller presses 1 to get their account balance, use a **Prompt** block to play a message and disconnect the call. 1. If the caller presses 2 to speak to an agent, use a **Set queue** block to set the queue and transfer the caller to the queue, which ends the flow. Here are the steps to create the flow: 1. Under **Interact**, drag a **Play prompt block** to the designer, and connect the **AccountLookup** node of the **Get customer input** block to it. After the customer gets their account balance from the Amazon Lex bot, the message in the **Play prompt** block plays. 1. Under **Terminate/Transfer**, drag a **Disconnect** block to the designer, and connect the **Play prompt** block to it. After the prompt message plays, the call is disconnected. To complete the **SpeakToAgent** intent: 1. Add a **Set working queue** block and connect it to the **SpeakToAgent** node of the **Get customer input** block. 1. Add a **Transfer to queue** block. 1. Connect the Success node of the **Set customer queue flow** block to the **Transfer queue**. 1. Choose **Save**, then **Publish**. Your finished flow will look something like the following image. The flow starts with the **Get customer input** block. That block branches to **Play prompt** or **Set customer queue**. ![\[The finished flow in the flow designer.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/lex-contactflow-designer.png) **Tip** If your business uses multiple locales in a single bot, add a [Set contact attributes](set-contact-attributes.md) block to the beginning of your flow. Configure this block to use the [\$1.LanguageCode](connect-attrib-list.md#attribs-system-table) system attribute. ## Assign the flow to a phone number When customers call in to your contact center, the flow to which they are sent is the one assigned to the telephone number that they called. To make the new flow active, assign it to a phone number for your instance. 1. Open the Amazon Connect console. 1. Choose **Routing, Phone numbers**. 1. On the **Manage Phone numbers** page, select the phone number to assign to the flow. 1. Add a description. 1. In the **Flow/IVR** menu, choose the flow that you just created. 1. Choose **Save**. ## Try it\$1 To try the bot and flow, call the number you assigned to the flow. Follow the prompts. # Best practices for using the chat channel and Amazon Lex Following are some recommended best practices for using the chat channel and Amazon Lex together. + You can use the same bot for both the voice and chat channels. However, you may want the bot to respond differently based on the channel. For example, you want to return SSML for voice so a number is read as a phone number, but you want to return normal text to chat. You can do this by passing the **Channel** attribute. For instructions, see [How to use the same Amazon Lex bot for voice and chat](one-bot-voice-chat.md). + For voice, some words are best spelled phonetically to get the correct pronunciation, such as last names. If this is the case with your scenario, include it in the design of your bot. Or, you can keep the voice and chat bots separate. + Tell agents about the bot. When a contact is connected to the agent, the agent sees the entire transcript in their window. The transcript includes text from both the customer and the bot. # Add Amazon Lex interactive messages for customers in chat Interactive messages are rich messages that present a prompt and pre-configured display options for a customer to choose. These messages are powered by Amazon Lex and configured through Amazon Lex using an AWS Lambda function. **Tip** If you have integrated with Apple Messages for Business, see [Interactive Message Types](https://register.apple.com/resources/messages/msp-rest-api/type-interactive) on the Apple website. ## Validation limits The string field limits (for example, title, subtitle, etc.) are expected to be enforced by the client (that is, a custom built interface or the hosted communications widget). The [SendMessage](https://docs.aws.amazon.com/connect-participant/latest/APIReference/API_SendMessage.html) API checks only that the total size of the string is less than 20KB. + When you use the hosted communications widget without customizing it, if the string exceeds field limits, it is truncated on the user interface and an ellipsis (...) is appended. You can determine how to enforce field limits by customizing the widget. + If you are integrating with other platforms (such as Apple Messages for Business), review the limits in this topic for Amazon Connect, and review the limits in the documentation for the other platform. For example, quick replies are not supported on older versions of iOS. All other field limits must be followed for the message to be successfully sent. **Image URL requirements for Apple Messages for Business** When using interactive messages with the [Apple Messages for Business](apple-messages-for-business.md) channel, image URLs (`imageData`) must be Amazon S3 object URLs. Other publicly accessible URLs are not supported. In addition, the following requirements apply: The S3 bucket must grant read access to the `connect.amazonaws.com` service principal, or the S3 object must be publicly accessible. The image size must not exceed 200 KB. ## Message display templates Amazon Connect provides the following message display templates. Use them to render information to customers in a chat: + [List picker](#list-picker) + [Time picker](#time-picker) + [Panel](#panel) + [Quick reply](#quick-reply-template) + [Carousel](#carousel-template) + [Apple form template](#apple-form-template) + [Apple pay template](#apple-pay-template) + [iMessage app template](#imessage-app-template) + [WhatsApp list](#whatsapp-list) + [WhatsApp reply button](#whatsapp-reply-button) + [Rich formatting in titles and subtitles](#rich-link-formatting) These templates define how the information renders, and what information is surfaced in the chat interface. When interactive messages are sent through chat, flows validate that the message format follows one of these templates. ## List picker template Use the list picker template to present the customer with a list of up to six choices. Each choice can have its own image. The following images show two examples of how the list picker template renders information in a chat. + One image shows three buttons, each one with the name of a fruit in text: apple, orange, banana. + The second image shows a picture of a store and then under it, three buttons, each one with the name, image, and price of the fruit. ![\[The list picker template rendering information in a chat.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/interactive-messages-listpicker-images2.png) The following code is the list picker template that you can use in your Lambda. Note the following: + **Bold text** indicates a mandatory parameter. + In some cases, if the parent element isn't mandatory, but the fields in the parent element are, then the fields are mandatory. For example, see the `data.replyMessage` structure in the following template. If the structure exists, `title` is mandatory. Otherwise a complete `replyMessage` is optional. ``` { "templateType":"ListPicker", "version":"1.0", "data":{ "replyMessage":{ "title":"Thanks for selecting!", "subtitle":"Produce selected", "imageType":"URL", "imageData":"https://interactive-msg.s3-us-west-2.amazonaws.com/fruit_34.3kb.jpg", "imageDescription":"Select a produce to buy" }, "content":{ "title":"What produce would you like to buy?", "subtitle":"Tap to select option", "imageType":"URL", "imageData":"https://interactive-msg.s3-us-west-2.amazonaws.com/fruit_34.3kb.jpg", "imageDescription":"Select a produce to buy", "elements":[ { "title":"Apple", "subtitle":"$1.00", "imageType":"URL", "imageData":"https://interactive-message-testing.s3-us-west-2.amazonaws.com/apple_4.2kb.jpg" }, { "title":"Orange", "subtitle":"$1.50", "imageType":"URL", "imageData":"https://interactive-message-testing.s3-us-west-2.amazonaws.com/orange_17.7kb.jpg", }, { "title":"Banana", "subtitle":"$10.00", "imageType":"URL", "imageData":"https://interactive-message-testing.s3-us-west-2.amazonaws.com/banana_7.9kb.jpg", "imageDescription":"Banana" } ] } ``` ### List picker limits The following table lists the limits for each of the list picker elements, should you choose to build your own Lambda from scratch. The mandatory parameters are in bold. To send unlimited options, implement action buttons in your application. For more information, see [Implementation of action buttons in interactive message list picker/panel](https://github.com/amazon-connect/amazon-connect-chat-interface/blob/master/.github/docs/InteractiveMessageActionButtonImplementation.md). **** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/interactive-messages.html) **Note** If you are using the `targetForLinks` field and Amazon Connect communications widget, in order to open links in the same browser tab, you must add the following attribute to the widget code snippet to allow the current iframe to open and navigate links within the same tab: ``` amazon_connect('updateSandboxAttributes', 'allow-scripts allow-same-origin allow-popups allow-downloads allow-top-navigation-by-user-activation') ``` ## Time picker template The time picker template is useful for enabling customers to schedule appointments. You can provide up to 40 timeslots to the customer in a chat. The following images show two examples of how the time picker template renders information in a chat. + One image shows one date, and under it, one time slot. + The second image shows one date, and under it, two time slots. ![\[The time picker template rendering information in a chat.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/interactive-messages-timepicker.png) The following image shows the time picker with an image **Note** If you are using this message template with the [Apple Messages for Business](apple-messages-for-business.md) channel and do not add an image, Amazon Connect will add a default image in both the reply and response message. ![\[The time picker with an image.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/interactive-messages-timepicker-with-image.png) The following code is the time picker template that you can use in your Lambda. Note the following: + **Bold text** indicates a mandatory parameter. + In some cases, if the parent element isn't mandatory, but the fields the parent element are, then the fields are mandatory. For example, see the `data.replyMessage` structure in the following template. If the structure exists, `title` is mandatory. Otherwise a complete `replyMessage` is optional. ``` { "templateType":"TimePicker", "version":"1.0", "data":{ "replyMessage":{ "title":"Thanks for selecting", "subtitle":"Appointment selected", "imageType":"URL", "imageData":"https://interactive-msg.s3-us-west-2.amazonaws.com/booked.jpg", "imageDescription":"Appointment booked" }, "content":{ "title":"Schedule appointment", "subtitle":"Tap to select option", "imageType":"URL", "imageData":"https://interactive-msg.s3-us-west-2.amazonaws.com/calendar.jpg", "imageDescription":"Appointment booked", "timeZoneOffset":-450, "location":{ "latitude":47.616299, "longitude":-122.4311, "title":"Oscar", "radius":1, }, "timeslots":[ { "date" : "2020-10-31T17:00+00:00", "duration": 60, }, { "date" : "2020-11-15T13:00+00:00", "duration": 60, }, { "date" : "2020-11-15T16:00+00:00", "duration": 60, } ], } } } } ``` ### Time picker limits The following table lists the limits for each of the time picker elements. Use this information if you choose to build your own Lambda from scratch. The mandatory parameters are in bold. **** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/interactive-messages.html) ## Panel template By using the panel template, you can present the customer with up to 10 choices under one question. However, you can include only one image, rather than an image with each choice. The follow image shows an example of how the panel template renders information in a chat. It shows an image at the top of the message, and under the image it shows a prompt that asks *How can I help? Tap to select option*. Under the prompt three options are displayed to the customer: **Check self-service options**, **Talk to an agent**, **End chat**. ![\[The panel template rendering information in a chat.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/interactive-messages-panel1.png) The following code is the panel template that you can use in your Lambda. Note the following: + **Bold text** indicates a mandatory parameter. + In some cases, if the parent element isn't mandatory, but the fields in the parent element are, then the fields are mandatory. For example, see the `data.replyMessage` structure in the following template. If the structure exists, a `title` is mandatory. Otherwise, a complete `replyMessage` is optional. ``` { "templateType":"Panel", "version":"1.0", "data":{ "replyMessage":{ "title":"Thanks for selecting!", "subtitle":"Option selected", }, "content":{ "title":"How can I help you?", "subtitle":"Tap to select option", "imageType":"URL", "imageData":"https://interactive-msg.s3-us-west-2.amazonaws.com/company.jpg", "imageDescription":"Select an option", "elements":[ { "title":"Check self-service options", }, { "title":"Talk to an agent", }, { "title":"End chat", } ] } } } ``` ### Panel limits The following table lists the limits for each of the panel elements, should you choose to build your own Lambda from scratch. The mandatory parameters are in bold. To send unlimited options, implement action buttons in your application. For more information, see [Implementation of action buttons in interactive message list picker/panel](https://github.com/amazon-connect/amazon-connect-chat-interface/blob/master/.github/docs/InteractiveMessageActionButtonImplementation.md). **** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/interactive-messages.html) ## Quick reply template Use quick reply messages to get simple responses from customers, and then to customers in an in-line list. Images are not supported for quick replies. The following image shows an example of how the quick reply template renders information in a chat. ![\[The panel template rendering information in a chat.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/quick-reply-template.png) The following code is the quick reply template that you can use in your Lambda. ``` { "templateType": "QuickReply", "version": "1.0", "data": { "replyMessage": { "title": "Thanks for selecting!" }, "content": { "title": "Which department would you like?", "elements": [{ "title": "Billing" }, { "title": "Cancellation" }, { "title": "New Service" } ] } } } ``` ### Quick reply limits The following table lists the limits for each of the quick reply elements. Use this information if you choose to build your own Lambda from scratch. The mandatory parameters are in bold. **** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/interactive-messages.html) ## Carousel template Use carousels to display up to 5 list pickers or panels to customers in a single message. Similar to the list picker and time picker, you can add more options to the carousel by using the SHOW\$1MORE feature. The following GIF shows an example of how the carousel template renders information in a chat. Customers scroll through the carousel of images by using the left and right arrows. ![\[A carousel in a customer's chat experience.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/carousel-interactive.gif) The following image shows two **Learn More** hyperlinks, which are examples of carousel picker hyperlink elements. ![\[A carousel picker with hyperlinks.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/carousel-interactive1.png) The following code is the carousel template that you can use in your Lambda. ``` { "templateType": "Carousel", "version": "1.0", "data": { "content": { "title": "View our popular destinations", "elements": [ { "templateIdentifier": "template0", "templateType": "Panel", "version": "1.0", "data": { "content": { "title": "California", "subtitle": "Tap to select option", "elements": [ { "title": "Book flights" }, { "title": "Book hotels" }, { "title": "Talk to agent" } ] } } }, { "templateIdentifier": "template1", "templateType": "Panel", "version": "1.0", "data": { "content": { "title": "New York", "subtitle": "Tap to select option", "elements": [ { "title": "Book flights" }, { "title": "Book hotels" }, { "title": "Talk to agent" } ] } } } ] } } } ``` For hosted communications widget users: + The selections on the carousel template result in a JSON string response structured like the following example, to be sent back to Lambda (other interactive message types return regular string response with only `selectionText` value): ``` { templateIdentifier: "template0", listTitle: "California", selectionText: "Book hotels" } ``` + In carousels, you can provide hyperlinks in the list picker/panel elements. To create a hyperlink instead of a button, include the following additional fields for the element that should be a hyperlink: ``` { title: "Book flights", ... type: "hyperlink", url: "https://www.example.com/Flights" } ``` ### Carousel limits The following table lists the limits for each of the carousel elements. Use this information if you choose to build your own Lambda from scratch. The mandatory parameters are in bold. **** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/interactive-messages.html) ## Apple form template **Note** This template is applicable only for Apple Messages for Business contact flows. A business can send a form interactive message to their end customers through a single message, containing multiple pages of requested inputs. When the message is received on an end-customer's Apple device, they can open the form and navigate through the pages, providing a response for each page, before submitting all responses at the end of the form. For example, businesses can use Apple forms for various purposes, including triaging flows, customer surveys, and account creation / sign-ups. **Warning** Interactive message content and end customer responses are stored in contact record transcript and are viewable by other chat participants and contact analysts with access to transcripts. To prevent PII from appearing in your contact record transcript **after the contact has ended**, you will want to use the [Set recording and analytics behavior block](set-recording-behavior.md) in your step-by-step guide flow, [enable Contact Lens](sensitive-data-redaction.md), and enable the redaction of sensitive date. For full details on how to enable PII redaction, see [Enable redaction of sensitive data](enable-analytics.md#enable-redaction). The types of pages supported are: + **ListPicker**: a list of options that the user must select from with image support. + **WheelPicker**: similar to ListPicker but selection is made through scrollable wheel of options. + **DatePicker**: a calendar view where user can pick a date. + **Input**: a text field that the user must fill in. The following code is an example of an Apple forms template you can use in your Lambda. **Note** **Bold text** is a mandatory parameter. In some cases, if the parent element exists in the request and it isn't mandatory/bold, but the fields in it are, then the fields are mandatory. Simple survey form example: ``` {   "templateType": "AppleForm",   "version": "1.0",   "data": {     "content": {       "title": "Survey",       "pages": [         {           "pageType": "DatePicker",           "title": "Date you visited",           "subtitle": "When did you last visit?",           "minDate": "2024-01-02"         },         {           "pageType": "ListPicker",           "title": "Rating",           "subtitle": "How do you rate the experience?",           "items": [             {               "title": "Good",               "imageType": "URL",               "imageData": "https://mybucket.s3.us-west-2.amazonaws.com/good.jpg"             },             {               "title": "Okay",               "imageType": "URL",               "imageData": "https://mybucket.s3.us-west-2.amazonaws.com/okay.jpg"             },             {               "title": "Poor",               "imageType": "URL",               "imageData": "https://mybucket.s3.us-west-2.amazonaws.com/poor.jpg"             }           ]         },         {           "pageType": "ListPicker",           "title": "Dine type",           "subtitle": "Select all dine types that apply",           "multiSelect": true,           "items": [             {               "title": "Pickup"             },             {               "title": "Dine-in"             },             {               "title": "Delivery"             }           ]         },         {           "pageType": "WheelPicker",           "title": "Visits",           "subtitle": "How often do you visit?",           "items": [             {               "title": "Often"             }             {               "title": "Sometimes"             },             {               "title": "Rarely"             }           ]         },         {           "pageType": "Input",           "title": "Additional notes",           "subtitle": "Anything else you'd like to mention about your visit?",           "multiLine": true         }       ]     }   } } ``` ### Apple form limits #### InteractiveMessage | Field | Type | Required | Description / Notes | | --- | --- | --- | --- | | version | string | Yes | Version number. Allowed value: "1.0" | | templateType | TemplateType | Yes | Interactive message template type. Allowed values: ["ListPicker", "TimePicker", "Panel", "QuickReply", "Carousel", "ViewResource", "AppleForm"] | | data | InteractiveMessageData | Yes | Interactive message data | #### InteractiveMessageData | Field | Type | Required | Description / Notes | | --- | --- | --- | --- | | content | InteractiveMessageContent | Yes | Main interactive message content | | replyMessage | ReplyMessage | No | Message display configuration for after response to interactive message is sent | #### AppleFormContent | Field | Type | Required | Description / Notes | | --- | --- | --- | --- | | title | String | Yes | Top-level title of the form. Displayed in Apple receive message bubble and transcript rendering | | subtitle | String | No | Used as subtitle in ReceivedMessage | | imageType | String | No | Valid values: "URL" Used for image in ReceivedMessage | | imageData | String | No | S3 image url Used for image in ReceivedMessage | | pages | AppleFormPage[] | Yes | List of form pages | | showSummary | Boolean | No | Whether to display a summary page of responses to review before submission Default: False (no confirmation/summary page) | | splashPage | AppleFormSplashPage | No | Initial splash page to display before actual pages Default: No splash page | #### AppleFormSplashPage | Field | Type | Required | Description / Notes | | --- | --- | --- | --- | | title | String | Yes | Title of splash page | | subtitle | String | No | Subtitle / body of splash page | | imageType | ImageType | No | Present when displaying image within splash page Allowed value: "URL" Default: No image displayed | | imageData | String | No | For imageType="URL", this is the URL value Default: No image displayed | | buttonTitle | String | Yes | Text of Continue button. Required by Apple, default text with localization not supported | #### AppleFormPage + Base model for form pages. Specific page types extend from this model | Field | Type | Required | Description / Notes | | --- | --- | --- | --- | | pageType | ApplePageType | Yes | Enum for page type. Allowed values: ["Input", "DatePicker", "WheelPicker", "ListPicker"] | | title | String | Yes | Page title | | subtitle | String | Yes | Page subtitle. Used in confirmation page | #### AppleFormDatePickerPage **AppleFormDatePickerPage **extends [AppleFormPage](#apple-forms-limits-appleformpage) | Field | Type | Required | Description / Notes | | --- | --- | --- | --- | | pageType | ApplePageType | Yes | Value: "DatePicker" | | labelText | String | No | Text displayed next to the date input. See example screenshots in Appendix | | helperText | String | No | Helper text displayed under the date input. See example screenshots in Appendix Default: No helper text | | dateFormat | String | No | ISO 8601 date format. Default: MM/dd/yyyy | | startDate | String | No | Initial / default selected date in valid date format Default: Current date for end user when message is sent | | minDate | String | No | Min date allowed to be selected in valid date format Default: No min | | maxDate | String | No | Max date allowed to be selected in valid date format Default: Current date for end user when message is sent | #### AppleFormListPickerPage **AppleFormListPickerPage** extends [AppleFormPage](#apple-forms-limits-appleformpage) | Field | Type | Required | Description / Notes | | --- | --- | --- | --- | | pageType | ApplePageType | Yes | Value: "ListPicker" | | multiSelect | Boolean | No | Enables selecting multiple items Default: false (single selection) | | items | AppleFormListPickerPageItem[] | Yes | List of list page items | #### AppleFormListPickerPageItem **AppleFormListPickerPageItem** extends [AppleFormPage](#apple-forms-limits-appleformpage) | Field | Type | Required | Description / Notes | | --- | --- | --- | --- | | title | String | Yes | Display text of item | | imageType | ImageType | No | Present when displaying image within item Allowed value: "URL" Default: No image displayed | | imageData | String | No | For imageType="URL", this is the URL value Default: No image displayed | **Note** Similar image model to existing interactive message models (ListPicker), except `imageDescription` is not included, which is used for image alt text in chat widget / web chats and ignored for Apple interactive messages. #### AppleFormWheelPickerPage **AppleFormWheelPickerPage** extends [AppleFormPage](#apple-forms-limits-appleformpage) | Field | Type | Required | Description / Notes | | --- | --- | --- | --- | | pageType | ApplePageType | Yes | Value: "WheelPicker" | | items | AppleFormWheelPickerPageItem[] | Yes | List of wheel picker items | | labelText | String | No | Text displayed next to the input. See example screenshots in Appendix | #### AppleFormWheelPickerPageItem **AppleFormWheelPickerPageItem** extends [AppleFormPage](#apple-forms-limits-appleformpage) | Field | Type | Required | Description / Notes | | --- | --- | --- | --- | | title | String | Yes | Display text of picker item | #### AppleFormInputPage **AppleFormInputPage** extends [AppleFormPage](#apple-forms-limits-appleformpage) | Field | Type | Required | Description / Notes | | --- | --- | --- | --- | | pageType | ApplePageType | Yes | Value: "Input" | | labelText | String | No | Text displayed next to the input box. See example screenshots in Appendix | | helperText | String | No | Additional text displayed under input box Default: No helper text | | placeholderText | String | No | Placeholder text to display initially when there's no input Default: "(Optional)" or "(Required)" placeholder text | | prefixText | String | No | Prefix text to display next to input. Ex: '\$1' when input is monetary value Default: No prefix text | | required | Boolean | No | Whether end user is required to provide input Default: false | | multiLine | Boolean | No | Whether multi-line input can be provided Default: false (single line) | | maxCharCount | Number | No | Max char count of input. Enforced on Apple client Default: No limit | | regex | String | No | Regex string to place constraints on input provided Default: No regex constraints | | keyboardType | String | No | Determines what type of keyboard is displayed when end user is providing input Allowed values: Same as Apple. See [docs](https://register.apple.com/resources/messages/msp-rest-api/type-interactive#form-message). Some of the allowed values: numberPad, phonePad, emailAddress | | textContentType | String | No | Helps with auto-fill suggestions on Apple device.  Allowed values: Same as Apple. See [docs](https://register.apple.com/resources/messages/msp-rest-api/type-interactive#form-message). Some of the allowed values: telephoneNumber, fullStreetAddress, familyName | ## Apple Pay template **Note** This template is applicable only for Apple Messages for Business contact flows. Use the Apple Pay template to provide an easy and secure way for customers to buy goods and services through Apple Messages for Business with Apple Pay. The following code is the Apple Pay template that you can use in your Lambda: **Note** **Bold text** is a mandatory parameter. In some cases, if the parent element exists in the request and it isn't mandatory/bold, but the fields in it are, then the fields are mandatory. ``` {   "templateType":"ApplePay",   "version":"1.0",   "data":{     "content":{       "title":"Halibut",       "subtitle":"$63.99 at Sam's Fish",       "imageType":"URL",       "imageData":"https://interactive-msg.s3-us-west-2.amazonaws.com/fish.jpg",       "payment": {         "endpoints": {           "orderTrackingUrl": "https://sams.example.com/orderTrackingUrl/",           "paymentGatewayUrl": "https://sams.example.com/paymentGateway/",           "paymentMethodUpdateUrl": "https://sams.example.com/paymentMethodUpdate/",           "shippingContactUpdateUrl": "https://sams.example.com/shippingContactUpdate/",           "shippingMethodUpdateUrl": "https://sams.example.com/shippingMethodUpdate/",           "fallbackUrl": "https://sams.example.com/paymentGateway/"         },         "merchantSession": {           "epochTimestamp": 1525730094057,           "expiresAt": 1525730094057,           "merchantSessionIdentifier": "PSH40080EF4D6.........9NOE9FD",           "nonce": "fe72cd0f",           "merchantIdentifier": "merchant.com.sams.fish",           "displayName": "Sam's Fish",           "signature": "308006092a8.......09F0W8EGH00",           "initiative": "messaging",           "initiativeContext": "https://sams.example.com/paymentGateway/",           "signedFields": [             "merchantIdentifier",             "merchantSessionIdentifier",             "initiative",             "initiativeContext",             "displayName",             "nonce"           ],         },         "paymentRequest": {           "applePay": {             "merchantCapabilities": [               "supports3DS",               "supportsDebit",               "supportsCredit"             ],             "merchantIdentifier": "merchant.com.sams.fish",             "supportedNetworks": [               "amex",               "visa",               "discover",               "masterCard"             ]           },           "countryCode": "US",           "currencyCode": "USD",           "lineItems": [             {               "amount": "59.00",               "label": "Halibut",               "type": "final"             },             {               "amount": "4.99",               "label": "Shipping",               "type": "final"             }           ],           "requiredBillingContactFields": [             "postalAddress"           ],           "requiredShippingContactFields": [             "postalAddress",             "phone",             "email",             "name"           ],           "shippingMethods": [             {               "amount": "0.00",               "detail": "Available within an hour",               "identifier": "in_store_pickup",               "label": "In-Store Pickup"             },             {               "amount": "4.99",               "detail": "5-8 Business Days",               "identifier": "flat_rate_shipping_id_2",               "label": "UPS Ground"             },             {               "amount": "29.99",               "detail": "1-3 Business Days",               "identifier": "flat_rate_shipping_id_1",               "label": "FedEx Priority Mail"             }           ],           "total": {             "amount": "63.99",             "label": "Sam's Fish",             "type": "final"           },           "supportedCountries" : [             "US",             "CA",             "UK",             "JP",             "CN"           ]         }       },       "requestIdentifier" : "6b2ca008-1388-4261-a9df-fe04cd1c23a9"     }   } } ``` ### Apple Pay limits | Parent field | Field | Required | Minimum characters | Maximum characters | Other requirement | | --- | --- | --- | --- | --- | --- | | | templateType | Yes | | | Valid template type | | | data | Yes | | | | | | version | Yes | | | Must be "1.0" | | data | content | Yes | | | | | content | title | Yes | 1 | 512 | The title of the received message bubble | | | subtitle | No | 0 | 512 | Subtitle to be displayed under title of the received message bubble | | | imageData | No | 0 | 200 | Must be a valid publicly accessible URL | | | imageType | No | 0 | 50 | Must be "URL" | | | payment | Yes | | | A dictionary containing fields giving the specifics of an Apple Pay request. | | | requestIdentifier | No | | | String, An identifier for the ApplePay request. If not specified, an UUID will be generated and used. | | payment | endpoints | Yes | | | A dictionary containing the endpoints for payment processing, contact updates, and order tracking. | | | merchantSession | Yes | | | A dictionary containing the payment session provided by Apple Pay after requesting a new payment session. | | | paymentRequest | Yes | | | A dictionary with information about the payment request | | endpoints | paymentGatewayUrl | Yes | | | String. Called by Apple Pay to process the payment through the payment provider. The URL should match the URL in the initiativeContext field of the merchant session | | | fallbackUrl | No | | | A URL that opens in a web browser so the customer can complete the purchase if their device is unable to make payments using Apple Pay. If specified, fallbackUrl need to match paymentGatewayUrl. | | | orderTrackingUrl | No | | | Called by Messages for Business after completing the order; provides you with an opportunity to update the order information in your system. | | | paymentMethodUpdateUrl | No | | | Called by Apple Pay when the customer changes the payment method. If you don’t implement this endpoint and you include this key in the dictionary, the customer sees an error message. | | | shippingContactUpdateUrl | No | | | Called by Apple Pay when the customer changes their shipping address information. If you don’t implement this endpoint and you include this key in the dictionary, the customer sees an error message | | | shippingMethodUpdateUrl | No | | | Called by Apple Pay when the customer changes the shipping method. If you don’t implement this endpoint and you include this key in the dictionary, the customer sees an error message. | | merchantSession | displayName | Yes | 1 | 64 | String. The canonical name for your store, suitable for display. Do not localize the name. | | | initiative | Yes | | | String. Must be “messaging” | | | initiativeContext | Yes | | | String. Pass your payment gateway URL. | | | merchantIdentifier | Yes | | | String. A unique identifier that represents a merchant for Apple Pay. | | | merchantSessionIdentifier | Yes | | | String. A unique identifier that represents a merchant's session for Apple Pay. | | | epochTimestamp | Yes | | | String.The time representation in number of seconds that have elapsed since 00:00:00 UTC, Thursday, January 1, 1970. | | | expiresAt | Yes | | | String. The expiration time representation in number of seconds that have elapsed since 00:00:00 UTC, Thursday, January 1, 1970. | | | nonce | No | | | Binary. A single-use string that checks the integrity of the interaction. | | | signature | No | | | Binary. A hash of the public key used to sign the interactions. | | | signedFields | No | | | List of strings contains the signed properties. | | paymentRequest | applePay | Yes | | | A dictionary that describes the Apple Pay configuration. | | | countryCode | Yes | | | String. The merchant’s two-letter ISO 3166 country code. | | | currencyCode | Yes | | | String. The three-letter ISO 4217 currency code for the payment. | | | lineItems | No | | | An array of line items explaining payments and additional charges. Line items are not required. However, the array cannot be empty if the lineItems key is present. | | | total | Yes | | | A dictionary containing the total. The total amount must be greater than zero to pass validation. | | | requiredBillingContactFields | No | | | The list of the customer's required billing information needed to process the transaction. For the list of possible strings, see [requiredBillingContactFields](https://developer.apple.com/documentation/apple_pay_on_the_web/applepaypaymentrequest/2216120-requiredbillingcontactfields). Require only the contact fields needed to process the payment. Requesting unnecessary fields adds complexity to the transaction, which can increase the chances of the customer canceling the payment request. | | | requiredShippingContactFields | No | | | The list of shipping or contact information required from the customer to fulfill the order. For example, if you need the customer's email or phone number, then include this key. For the list of possible strings, see [requiredShippingContactFields](https://developer.apple.com/documentation/apple_pay_on_the_web/applepaypaymentrequest/2216121-requiredshippingcontactfields). | | | shippingMethods | No | | | An array that lists the available shipping methods. The Apple Pay payment sheet displays the first shipping method from the array as the default shipping method. | | | supportedCountries | No | | | An array of countries to support. List each country with their ISO 3166 country code. | | applePay | merchantIdentifier | Yes | | | A unique identifier that represents a merchant for Apple Pay. | | | merchantCapabilities | Yes | | | An array of payment capabilities supported by the merchant. The array must include supports3DS, and may optionally include supportsCredit, supportsDebit, and supportsEMV. | | | supportedNetworks | Yes | | | An array of payment networks supported by the merchant. The array must include one or more of the following values: amex, discover, jcb, masterCard, privateLabel, or visa | | lineItem | amount | Yes | | | The monetary amount of the line item. | | | label | Yes | | | A short, localized description of the line item. | | | type | No | | | A value that indicates whether the line item is final or pending. | | total | amount | Yes | | | The total amount of the payment. | | | label | Yes | | | A short, localized description of the payment. | | | type | No | | | A value that indicates whether the payment is final or pending. | | shippingMethods | amount | Yes | | | String. The non-negative cost associated with this shipping method. | | | detail | Yes | | | String. Additional description of the shipping method. | | | label | Yes | | | String. A short description of the shipping method. | | | identifier | Yes | | | String. A client-defined value used to identify this shipping method. | ## iMessage App template **Note** This template is applicable only for Apple Messages for Business contact flows. Use the iMessage Apps template to present the customer with your custom built iMessage App. The following code is an example iMessage App template that you can use in your Lambda function.  ``` {    templateType: AppleCustomInteractiveMessage,    version: "1.0",    data: {        content: {            appIconUrl: "https://interactive-message-testing.s3-us-west-2.amazonaws.com/apple_4.2kb.jpg",            appId: "123456789",            appName: "Package Delivery",            title: "Bubble Title CIM",            bid: "com.apple.messages.MSMessageExtensionBalloonPlugin:{team-id}:{ext-bundle-id}",            dataUrl: "?deliveryDate=26-01-2024&destinationName=Home&street=1infiniteloop&state=CA&city=Cupertino&country=USA&postalCode=12345&latitude=37.331686&longitude=-122.030656&isMyLocation=false&isFinalDestination=true",            subtitle: "Bubble package",        },        replyMessage: {            title: "Custom reply message title",            subtitle: "Custom reply message subtitle",            imageType: "URL",            imageData: "https://interactive-msg.s3-us-west-2.amazonaws.com/fruit_34.3kb.jpg",        }    } } ``` ### iMessage App limits | **Parent Field** | **Field** | **Required** | **Type** | **Other Notes** | | --- | --- | --- | --- | --- | | | templateType | Yes | TemplateType | Valid template type, "AppleCustomInteractiveMessage" | | | data | Yes | InteractiveMessageData | Contains content and receivedMessage dictionaries | | | version | Yes | string | Must be "1.0" | | data | content | Yes | InteractiveMessageContent | Interactive Content of the iMessage App | | | replyMessage | Yes | ReplyMessage | Message display configuration for after response to interactive message is sent | | content | appIconUrl | Yes | string | AWS S3 URL | | | appId | Yes | string | Business IMessage App Id | | | appName | Yes | string | Business IMessage App name | | | bid | Yes | string | Business IMessage App Bid. Pattern:  com.apple.messages.MSMessageExtensionBalloonPlugin:\$1team-id\$1:\$1ext-bundle-id\$1 | | | dataUrl | Yes | string | Data that is passed into the iMessage App | | | useLiveLayout | No | boolean | Default True | | | title | Yes | string | title of the Imessage App bubble | | | subtitle | No | string | subtitle of the Imessage App bubble | | replyMessage | title | No | string | | | | subtitle | No | string | | | | imageType | No | string | Must be a valid publicly accessible URL | | | imageData | No | string | Cannot exist without an image | ## WhatsApp list **Note** You only use this template for WhatsApp messaging flows. For more information about integrating WhatsApp with Amazon Connect, see [Set up WhatsApp Business messaging](whatsapp-integration.md), earlier in this guide. You use the WhatsApp list template in WhatsApp chats to provide customers with a list of options. The following example shows a list of options for a banking service. ``` { "templateType": "WhatsAppInteractiveList", "version": "1.0", "data": { "content": { "title": "Which account do you need help with?", "body": { "text": "Which account do you need help with?" }, "action": { "button": "Options", "sections": [ { "title": "Your accounts", "rows": [ { "id": "11111111", "title": "11111111", "description": "PERSONAL CHECKING" }, { "id": "22223333", "title": "22223333", "description": "PERSONAL SAVINGS" } ] }, { "title": "Other", "rows": [ { "id": "other", "title": "I can't find my account" } ] } ] } } } } ``` The following image shows a typical screen before and after a customer opens a list. ![\[Image showing a list of options.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/whatsapp-options-results.png) ### WhatsApp options limits | Parent field | Field | Required | Minimum length | Maximum length | Other Requirement | | --- | --- | --- | --- | --- | --- | | | templateType | Yes | | | Must be "WhatsAppInteractiveList" | | | data | Yes | | | | | | version | Yes | | | Must be "1.0" | | data | content | Yes | | | | | content | title | Yes | | | | | | header | No | | | | | | body | Yes | | | | | | footer | No | | | | | | action | Yes | | | | | header | type | Yes | | | Must be "text" | | | text | Yes | 1 | 60 | | | body | text | Yes | 1 | 4096 | | | footer | text | Yes | 1 | 60 | | | action | sections | Yes | 1 | 10 | | | | button | Yes | 1 | 20 | | | section | title | Yes | 1 | 24 | | | | rows | Yes | 1 | 10 | Maximum 10 rows across all sections | | row | id | Yes | 1 | 200 | Must be unique across rows | | | title | Yes | 1 | 24 | | | | description | No | 1 | 72 | | ## WhatsApp reply button **Note** You only use this template for WhatsApp messaging flows. You can use the WhatsApp reply button template to present an in-line list of options for customers. ``` { "templateType": "WhatsAppInteractiveReplyButton", "version": "1.0", "data": { "content": { "title": "What would you like to do?", "body": { "text": "What would you like to do?" }, "action": { "buttons": [ { "type": "reply", "reply": { "id": "agent", "title": "Continue to agent" } }, { "type": "reply", "reply": { "id": "end_chat", "title": "End chat" } } ] } } } } ``` The following image shows a typical user experience. ![\[Image of a reply in a chat session.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/whatsapp-reply-template.png) ### WhatsApp reply button limits The WhatsApp reply template has the following limits. | Parent Field | Field | Required | Minimum length | Maximum length | Other Requirement | | --- | --- | --- | --- | --- | --- | | | templateType | Yes | | | Must be "WhatsAppInteractiveReplyButton" | | | data | Yes | | | | | | version | Yes | | | Must be "1.0" | | data | content | Yes | | | | | content | title | Yes | | | | | | header | No | | | | | | body | Yes | | | | | | footer | No | | | | | | action | Yes | | | | | header | type | Yes | | | Valid values: "text", "document", "image", "video" | | | text | No | 1 | 60 | | | | image | No | | | | | | video | No | | | | | | document | No | | | | | image | link | Yes | | | Must be publicly accessible media URL starting with https/http | | video | link | Yes | | | Must be publicly accessible media URL starting with https/http | | document | link | Yes | | | Must be publicly accessible media URL starting with https/http | | body | text | Yes | 1 | 1024 | | | footer | text | Yes | 1 | 60 | | | action | buttons | Yes | 1 | 3 | | | button | type | Yes | | | Must be "reply" | | | reply.id | Yes | 1 | 256 | Must be unique across buttons | | | reply.title | Yes | 1 | 20 | | ## Rich formatting in titles and subtitles You can add rich formatting to the titles and subtitles of your chat messages. For example, you can add links, italics, bold, numbered lists, and bulleted lists. You use [markdown]( https://commonmark.org/help/) to format your text. The following image of a chat box shows an example list picker with rich formatting in the title and subtitle. + The title **How can we help? aws.amazon.com** is bold and contains a link. + The subtitle contains italics and bold text, a bulleted list, and a numbered list. It also shows a plain link, text link, and sample code. + The bottom of the chat box shows three list picker elements. ![\[A chat box, a title with a link, a subtitle with lists and links.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/rich-link-formatting-example1a.png) ### How to format text with markdown You can write title and subtitle strings in a multi-line format, or in a single line with ``\r\n`` line break characters. + **Multi-line format**: The following code sample shows how to author lists in markdown in a multi-line format. ``` const MultiLinePickerSubtitle = `This is some *emphasized text* and some **strongly emphasized text** This is a bulleted list (multiline): * item 1 * item 2 * item 3 This is a numbered list: 1. item 1 2. item 2 3. item 3 Questions? Visit https://plainlink.com/faq [This is a link](https://aws.amazon.com) This is \`\` ` const PickerTemplate = { templateType: "ListPicker|Panel", version: "1.0", data: { content: { title: "How can we help?", subtitle: MultiLinePickerSubtitle, elements: [ /* ... */ ] } } } ``` + **Single line format**: The following example shows how to author a subtitle in a single line by using ``\r\n`` line break characters. ``` const SingleLinePickerSubtitle = "This is some *emphasized text* and some **strongly emphasized text**\r\nThis is a bulleted list:\n* item 1\n* item 2\n* item 3\n\nThis is a numbered list:\n1. item 1\n2. item 2\n3. item 3\n\nQuestions? Visit https://plainlink.com/faq\r\n[This is a link](https://aws.amazon.com)\r\nThis is ``"; const PickerTemplate = { templateType: "ListPicker|Panel", version: "1.0", data: { content: { title: "How can we help?", subtitle: SingleLinePickerSubtitle, elements: [ /* ... */ ] } } } ``` The following example shows how format italics and bold text with markdown: `This is some *emphasized text* and some **strongly emphasized text**` The following example shows how to format text as code with markdown: `This is ``` ### How to format links with markdown To create a link, use the following syntax: `[aws](https://aws.amazon.com)` The following examples show two ways you can add links with markdown: `Questions? Visit https://plainlink.com/faq ` `[This is a link](https://aws.amazon.com)` **Note** For list pickers, the `targetForLinks` field can be added as a child field to `content` if you want to have granular control over where links are opened. The communications widget will open links in a new browser tab by default. For more information, see [List picker template](#list-picker).