Botium Connector for Amazon Lex
npm install botium-connector-lex
![license]()
This is a Botium connector for testing your Amazon Lex chatbot.
__Did you read the Botium in a Nutshell articles? Be warned, without prior knowledge of Botium you won't be able to properly use this library!__
It can be used as any other Botium connector with all Botium Stack components:
* Botium CLI
* Botium Bindings
* Botium Box
This connector processes info about NLP. So Intent/Entity asserters can be used. (Does not returns confidences, and alternative intents)
When using __Botium CLI__:
``
> npm install -g botium-cli
> npm install -g botium-connector-lex
> botium-cli init
> botium-cli run
When using __Botium Bindings__:
`
> npm install -g botium-bindings
> npm install -g botium-connector-lex
> botium-bindings init mocha
> npm install && npm run mocha
When using __Botium Box__:
_Already integrated into Botium Box, no setup required_
There are two possibilities to connect to Amazon Lex:
* Create an IAM user (see here for help)
* Important: choose _Programmatic access_ as access type
* Note access key and secret, you need it later
* Choose _Attach existing policies to user directly_ to give permissions _AmazonLexFullAccess_
* Feel free to use finer grained policies if you know what you are doing,
or read Authentication and Access Control for Amazon Lex
* Create an IAM Role (see here)
* Choose _Attach existing policies to user directly_ to give permissions _AmazonLexFullAccess_
* Feel free to use finer grained policies if you know what you are doing,
or read Authentication and Access Control for Amazon Lex
* Add a trust policy (see here)
* The external Id has to to be provided as Capability
* The Role ARN has to to be provided as Capability
Create a botium.json with
* Amazon region where you have created your bot. See Amazon Lex Console
* access key and secret of IAM user,
* name of the bot
* alias of the bot (see publishing)
`
{
"botium": {
"Capabilities": {
"PROJECTNAME": "
"CONTAINERMODE": "lex",
"LEX_REGION": "xxx",
"LEX_AUTH_MODE": "xxx",
"LEX_ROLE_ARN": "xxx",
"LEX_ROLE_EXTERNAL_ID": "xxx",
"LEX_ACCESS_KEY_ID": "xxx",
"LEX_SECRET_ACCESS_KEY": "xxx",
"LEX_PROJECT_NAME": "xxx",
"LEX_PROJECT_ALIAS": "xxx"
}
}
}
To check the configuration, run the emulator (Botium CLI required) to bring up a chat interface in your terminal window:
`
> botium-cli emulator
Botium setup is ready, you can begin to write your BotiumScript files.
There is a small demo in samples/BookTrip dir with Botium Bindings. This tests the BookTrip template of Amazon Lex. To start it you have to :
* Create and publish a bot from the template
* Go to console
* Choose region (top right) and note it, you need it later
* Click _Create_
* Choose _BookTrip_
* Choose a name and note it, you need it later
* Accept COPPA
* Click _Create_ to create the Lex project
* Now click _Publish_ and select an alias
* Adapt botium.json in the sample directory
* Run the sample
`
> cd ./samples/BookTrip
> npm install && npm test
Session attributes can be initialized with the _LEX_SESSION_ATTRIBUTES_-capability (see below). They will be updated on each Lex response.
They can be updated within a conversation as well:
#me
I would like to order some flowers
UPDATE_CUSTOM SET_LEX_SESSION_ATTRIBUTE|attr1|attr1-value
Request attributes to be used on each request can be set with the _LEX_REQUEST_ATTRIBUTES_-capability (see below)
They can be given within a conversation as well:
#me
I would like to order some flowers
UPDATE_CUSTOM SET_LEX_REQUEST_ATTRIBUTE|attr2|attr2-value
This connector provides a CLI interface for importing convos and utterances from your Amazon Lex bot and convert it to BotiumScript.
* Bot intents and user examples are mapped to utterances in BotiumScript
* Slots in user examples are either filled with enumeration values (for enumeration slot types) or with samples values from the official documentation
* Convos are using the utterances as input and attach an INTENT asserter
* If using the _--buildentities_ switch, the utterances are separated by slot names and an additional ENTITIES asserter is attached
You can either run the CLI with botium-cli (recommended - it is integrated there), or directly from this connector (see samples/BookTrip directory for some examples):
> npx botium-connector-lex-cli import --buildconvos --buildentities --output spec/convo
_Please note that you will have to install the npm package botium-core manually before using this CLI_
For getting help on the available CLI options and switches, run:
> npx botium-connector-lex-cli import --help
Set the capability __CONTAINERMODE__ to __lex__ to activate this connector.
V1 or V2
_Hint: a list of region codes is available here_
_For Lex V2, use the Project ID instead of the name_
_For Lex V2, use the alias ID instead of the name_
Publishing alias locale. (see Publishing section in the Amazon Lex Console)
Initial session attributes. It must be object, or object as string. Lex supports just string attributes.
(otherwise retrurns error like "error sending to bot Error: Lex answered with error { InvalidParameterType: Expected params.sessionAttributes['somenumber'] to be a string")
Request attributes.
The response content type. If you prefer to receive audio set it to one of the supported audio formats (see Lex docs)
Content type used when sending text.
Content type used when sending audio. Has to match your audio data format.