Interact with an Amazon Lex V2 bot with the AWS CLI, AWS SDK for Python (Boto3), and AWS SDK for DotNet
Amazon Lex is a service for building conversational interfaces into any application. The new Amazon Lex V2 console and APIs make it easier to build, deploy, and manage bots. The Amazon Lex V2 console and APIs provide a simple information architecture in which the bot intents and slot types are scoped to a specific language. Versioning is performed at the bot level so that resources such as intents and slot types don’t have to be versioned individually. All the resources associated with the bot (language, intents, and slot types) are archived as part of the created bot version. This new methodology makes it easier to manage your bots. You can find more information in the Amazon Lex V2 API reference.
The Amazon Lex V2 console and APIs introduce a new method to build and interact with your bots. This post illustrates different methods to interact with a Amazon Lex V2 chatbot programmatically using the:
AWS Command Line Interface, (AWS CLI),
AWS SDK for Python (Boto3), and the
AWS SDK for DotNet.
For this post, we use the MakeAppointment bot, which simulates the workflow of setting up an appointment with a dentist.
Obtain ID values for your bot
To get started, you must collect the following information:
Your bot ID
Your alias ID
Your locale ID (language code)
Obtain your bot ID
You can find your bot ID on the Amazon Lex V2 console.
On the Amazon Lex V2 console, on the Bots page, choose the bot you want to interact with.
For this post, we use MakeAppointmentBot.
Choose the bot and in the Bot details section, you can find the ID.
For this post, our ID is UFIDGBA6DE.
Obtain your alias ID
To obtain your bot’s alias ID, complete the following steps:
On the Amazon Lex V2 console, navigate to your bot.
In the navigation pane, under Bot versions, under Deployment, choose Aliases.
Choose your alias.
For this post, we use TestBotAlias.
In the Details section, you can find the alias ID.
For this post, our alias ID is TSTALIASID.
Obtain your locale ID
Your locale ID indicates which language your bot uses.
On the Amazon Lex V2 console, in the navigation pane, choose Bot versions.
Choose the version of your bot you want to use.
For this post, we use the version called Draft version.
In the navigation pane, under your bot version, choose All languages.
You can see a list of the available languages for your chatbot.
Choose your preferred language.
For this post, we use English (US), which is en_US.
Interacting via the AWS CLI
The AWS Command Line Interface (CLI) is a unified tool to manage your AWS services. With just one tool to download and configure, you can control multiple AWS services from the command line and automate them through scripts.
To demonstrate the AWS CLI, you can use AWS CloudShell. AWS CloudShell is a browser-based shell that makes it easy to securely manage, explore, and interact with your AWS resources. CloudShell is pre-authenticated with your console credentials.
There are some cases where AWS CloudShell don’t have the latest version of the AWS CLI installed. If you receive an error “Invalid choice: ‘lexv2-runtime’”, follow the instructions contained in this guide to update the AWS CLI on AWS CloudShell.
In my case after updating, I got the following version:
And this time when I run the “aws lexv2-runtime” command it is recognized:
After collecting the required information, enter your bot’s parameters (please keep in mind your IDs will be different):
To get started, you will submit the text “I would like to see the dentist” by using the following command:
You will receive the following response:
Diving deep into the response you will notice the dialog state is ElicitSlot, or in other words, the chatbot is requiring the user to provide a value for the slot type ‘AppointmentType’.
Also, you will notice the messages:
In this case you will state “Root canal” as the appointment type:
The response you will receive will look similar to this:
Check the current dialogAction:
Also, the messages:
This time you will provide the pickup date:
This time the response will look similar to this:
At time of writing this blog “next Wednesday” is March 17, 2021, which is what your chatbot interpreted:
And the messages:
Next step is to define the Time:
The response will be similar to this:
This time your chatbot interpreted the value as 09:00 and used it as the value for the slot Time:
Because the slots have been set now, the sessionState dialogAction is ConfirmIntent.
This time, messages contains the details contained in the slots.
You will submit the confirmation:
Response will be similar to:
Also the intent sate is “ReadyForFulfillment” and “Confirmed”
Interact programmatically with Amazon Lex V2 via Boto3
Boto is the AWS SDK for Python. It enables Python developers to create, configure, and manage AWS services, such as Amazon Elastic Compute Cloud (Amazon EC2) and Amazon Simple Storage Service (Amazon S3). Boto provides an easy-to-use, object-oriented API, as well as low-level access to AWS services.
Support for Amazon Lex V2 APIs is introduced in version 1.16.59.
To interact with your Amazon Lex bot using the Boto3 lexv2-runtime, you need to use the values that you collected earlier for botID, AliasId, and localeID.
Boto3 code example
After I collected the required information, I have the following parameters (these will be different for your account):
The first message you send to your bot is “I would like to see the dentist “:
You get a response similar to the following:
We can dive deeper into the response to see the dialog state is ElicitSlot, meaning the chatbot is requiring the user to provide a value for the slot type AppointmentType:
In this case, you enter Root Canal:
This time, your response is the following:
The chatbot interpreted that the value for the slot AppointmentType is root canal:
You can also check the current dialogAction:
In the messages section, you can see the following:
Provide appointment date:
You get a response similar to the following:
At the time of this writing, “next Wednesday” is March 17, 2021, which is exactly what your chatbot interpreted:
You can see the following in the messages section:
The next step is to define the PickupTime:
Use the following code:
You receive a response similar to the following:
The chatbot set your appointment Time for 9:00 AM:
Because the slots have been set, the sessionState dialogAction is now ConfirmIntent:
This time, the messages section contains the details contained in the slots:
You submit the confirmation:
The response looks like the following:
The sessionState dialogAction this time is Close:
Also, the intent state is ReadyForFulfillment and Confirmed:
About DotNet SDK
The AWS SDK for DotNet provides an interface that you can use from your DotNet applications to interact with your bots. You can use the SDK for DotNet to build client applications for users.
The following application interacts with the . It uses the AmazonLexRuntimeV2Client from the SDK for DotNet to call the RecognizeText operation to conduct a conversation with the bot.
To run the application, you need the following values:
botId –The identifier assigned to the bot when you created it. You can see the bot ID on the Amazon Lex console on the Bot details
botAliasId – The identifier assigned to the bot alias when you created it. You can see the bot alias ID on the Amazon Lex console on the Aliases If you can’t see the alias ID in the list, choose the gear icon on the upper right and turn on Alias ID.
localeId – The identifier of the locale that you used for your bot. For a list of locales and language codes, see Languages and locales supported by Amazon Lex.
accessKey and secretKey – The authentication keys for your account. If you don’t have a set of keys, create them using the AWS Identity and Access Management (IAM) console.
sessionId – An identifier for the session with the Amazon Lex bot. In this case, the code uses a random UUID.
Additionally, if your bot isn’t in the US East (N. Virginia) AWS Region, make sure that you change the region value.
Let’s look at the following sample code to understand how we can easily interact with Amazon Lex V2 from the DotNet framework.
First, we create an AmazonLexRuntimeV2Client object with the access key and secret:
Provide the following information:
The request uses the required URI parameters botAliasId, botId, localeId, and sessionId.
The user initiates the conversation by providing the intent:
Next, we call the GetRecongizeTextV2Response method by passing the required parameters and the AmazonLexRuntimeV2Client client object:
Inside the GetRecongizeTextV2Response method, we create a RecognizeTextRequest object, containing the parameters to the RecognizeText operation:
The RecognizeTextRequest in JSON format looks like the following:
Then we send the user input to Amazon Lex. Client applications can use this API to send requests to Amazon Lex at runtime. You can send requests synchronously or asynchronously. For this post, we send the request using the RecognizeTextAsync method asynchronously. Amazon Lex interprets the user input using the machine learning model that it built for the bot. See the following code:
In response, Amazon Lex returns the next message to convey to the user and an optional response card to display:
As you can see, Amazon Lex returns the next message inside the Content as a plain text, with HttpStatusCode as 200.
DotNet SDK code example
The following is the full source code:
Now that you have learned how to interact with your Amazon Lex v2 chatbot programmatically with the AWS CLI, Boto3, and, the AWS SDK for DotNet, you can integrate your bots with your applications or with different platforms. If you want to learn more about Amazon Lex v2, you can explore building a banking bot with support for English and Spanish. You can also dive deep into Amazon Lex through the Developer Guide.
About the Authors
Juan Bustos is an AI Services Specialist Solutions Architect at Amazon Web Services, based in Dallas, TX. Outside of work, he loves spending time writing and playing music as well as trying random restaurants with his family.
Esther Lee is a Product Manager for AWS Language AI Services. She is passionate about the intersection of technology and education. Out of the office, Esther enjoys long walks along the beach, dinners with friends and friendly rounds of Mahjong.