Botium Connector for Amazon Lex

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!

How it works

Botium connects to the Amazon Lex API.

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)

Requirements

• Node.js and NPM
• a published Lex bot, and user account with administrative rights
• a project directory on your workstation to hold test cases and Botium configuration

Install Botium and Amazon Lex Connector

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

Connecting Amazon Lex to Botium

You have to create an IAM user to enable Botium to access the Amazon Lex API.

• 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 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": "<whatever>",
      "CONTAINERMODE": "lex",
      "LEX_REGION": "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.

How to start sample

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

Setting Session and Request Attributes

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

Using the botium-connector-lex-cli

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

Supported Capabilities

Set the capability CONTAINERMODE to lex to activate this connector.

LEX_VERSION

Default: V1

V1 or V2

LEX_ACCESS_KEY_ID

See Amazon IAM user

LEX_SECRET_ACCESS_KEY

See Amazon IAM user

LEX_REGION

Amazon region code where you have created your bot. Amazon Lex V1 Console/Amazon Lex V2 Console.

Hint: a list of region codes is available here

LEX_PROJECT_NAME

The name (V1) or ID (V2) of the bot. See Amazon Lex V1 Console/Amazon Lex V2 Console.

For Lex V2, use the Project ID instead of the name

LEX_PROJECT_ALIAS

The alias name (V1) or ID (V2) of the bot. (see Publishing section in the Amazon Lex Console)

For Lex V2, use the alias ID instead of the name

LEX_LOCALE (V2 only)

Default: en_US

Publishing alias locale. (see Publishing section in the Amazon Lex Console)

LEX_SESSION_ATTRIBUTES

Optional.

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")

LEX_REQUEST_ATTRIBUTES

Optional.

Request attributes.

LEX_ACCEPT

Default: text/plain; charset=utf-8

The response content type. If you prefer to receive audio set it to one of the supported audio formats (see Lex docs)

LEX_CONTENTTYPE_TEXT

Default: text/plain; charset=utf-8

Content type used when sending text.

LEX_CONTENTTYPE_AUDIO

Default: audio/l16; rate=16000; channels=1

Content type used when sending audio. Has to match your audio data format.