Integration with Amazon Lex

Blueworx Voice Response can connect to an Amazon Lex bot using CCXML.

Using Amazon Lex with BVR

Integrating a BVR CCXML application with Lex is achieved using a dialogstart with the src field specifying the bot name and the parameters field specifying other information required by the Lex service to connect to that bot.

The following CCXML variables must be set up for use with the dialogstart:

src The name of the Lex bot to connect to.
lex_bot_alias The alias for the bot to connect to. At the time of writing, an alias can be set up for a Lex bot in the Aliases section of its Settings tab.
lex_access_key The access key credentials that have access to the Lex service on the AWS account hosting the bot to connect to.
lex_secret_key The secret key credentials that have access to the Lex service on the AWS account hosting the bot to connect to.
lex_region The region of the bot to connect to (e.g. eu-west-1). The simplest way to determine the region string to use at the time of writing is to look at the region parameter in the address bar of the browser used to manage your lex bots.
lex_user_id A userID to set for Lex requests. This can be any text string in the format (blah) and is used by Lex to identify a session. If the userID is not specified, a random one will be generated meaning that a new session will be created for each Lex dialog. Note that multiple simultaneous sessions should not use the same userID, so it is recommended that this is set to a value that will be different for each user (for example the username or phone number of the user calling in or being called), for each CCXML session (such as the CCXML session ID), or for each call (such as the Call ID)
bargein Whether or not to allow bargein during audio prompts. If not specified, this will be set to true.
initial_speech_duration Determines the amount of speech (in milliseconds) before BVR starts sending audio to Lex. Default value is 200ms.
final_silence_duration Determines the amount of silence (in milliseconds) required before user input to Lex is considered complete. If not specified, this will be set to 500ms.
initial_input_text If specified, BVR will send the text value of this variable to Lex when it first starts the dialog, which will behave as if the words were spoken to start with. If this is not specified, Lex will await user input.

Once these variables have been setup, the Lex dialog can be started with the following dialogstart:

<dialogstart src="lex_bot_name" type="'application/amazon-lex'" connectionid="evt.connectionid" parameters="lex_bot_alias lex_access_key lex_secret_key lex_region lex_user_id"/>

The Lex dialog finishes when the user's interaction with the bot is completed (that is, once the intent has been determined and all required slots have been filled) or certain session variables have been set. The following exit values are set when a Lex dialog ends (note: the below variable names assume the event is referenced with "evt"):

evt.values.lex_dialog_state The final state of the Lex dialog. This can be either Fulfilled, ReadyForFulfillment or Failed.
evt.values.slots A map of the slots filled in by the Lex session (where the slot name is the key and the value detected by lex is the value).
evt.values.session_attributes A map of the session attributes set on the Lex session. These can be set in the Lex bot itself using Lambda functions.

Using session variables to control BVR

It is possible to trigger certain actions on BVR by setting the bw_action session variable. These session variables must be set by calling a Lambda function from your Lex bot. For further information on this, please refer to the AWS Lex and Lambda documentation.

The bw_action session variable

end_dialog Ends the current Lex dialog, triggering a dialog.exit
transfer Triggers the dialog.transfer CCXML event and ends the dialog. It is possible to set a transfer target by setting the session variable "bw_transfer_target". Further information on transferring in CCXML can be found on the CCXML Call Transfer and Bridging page.

Sample Applications

We have provided sample applications that describe the integration and can be used to connect to Amazon Lex. The sample applications are installed on the BVR server in the following location:


Debugging Lex applications

There are 2 trace components that can be used when debugging Lex applications:

AMZ_LEX_APP Logs out information about the connection to the Lex service and any interaction with it from the perspective of BVR
AWS Logs out information internal to the AWS SDK