VoiceElements now supports Amazon Lex as of Version 8.6.2.0
What is Amazon Lex?
Amazon Lex is a platform that allows you to build your own conversational interface using the learning technologies of Alexa. Voice Elements allows you to stream the voice input of a call directly into the Amazon interface so that your callers can speak directly to the interface. At each step of the conversation Amazon Lex provides information about the conversation directly into your voice application. Perhaps more widely known as Chatbots, this integration will allow you to greatly enhance your customer’s experience while using your IVR.
In order to run this sample, you will need to create or already have an Amazon Lex Chatbot. To read more about Amazon Lex or to begin creation of your chatbot, see AWS: Amazon Lex and AWS: What is a Chatbot?
Amazon Lex Chatbot Tutorial
This tutorial is a walk-through explanation of the Amazon Lex sample solution that can be downloaded from your demo dashboard on the Voice Elements Customer Portal.
(If you haven’t already, sign up for a demo account and get 100 minutes of free call time for the next 30 days with the Voice Elements servers.)
This Solution is designed to demonstrate how easily Voice Elements can interface calls into a chatbot.
You will need the following Amazon Lex credentials for your chatbot to run this demo solution:
-
- Access key ID
- Secret Access key
- Amazon Region
- Amazon Bot Alias
- Amazon Bot Name
Table of Contents
Download the Sample Solution
Sign In to the Voice Elements Customer Portal.
If you are not brought directly to the Dashboard screen, click on Dashboard in the top navigation links.
Sample Solutions Available in Three Download Formats
We offer three download formats for running the Sample Solutions: Windows Executable Program, Windows Source Code Download, or .NET Core Cross Platform Code. You can download any option and run them as often as you like.
Choosing to Download the Windows Executable Program
You’ll enjoy this user friendly option if you are not a programmer, if Visual Studio is not installed on the device or machine you are currently using for the demo, or if you just want to jump straight to seeing Voice Elements in action.
Select the Windows Program button ‘Download exe’. The ZIP file will be downloaded to your machine’s Downloads folder. You might also find it in the tray at the bottom of your browser window. Unzip the folder and extract the files to your chosen location. Look for the application named VoiceApp and run it.
Choosing to Download the Windows Source Code
If you are a programmer and have Visual Studio loaded on the device or machine you are using, you may enjoy downloading the Windows Source Code and seeing it in action from that perspective. Not only will you see how easy it is to program the code, you will also see how simple it is to create your telephony application.
Select the Windows Source Code button ‘Download sln’. Unzip the folder and extract the files to your chosen location. Run the Microsoft Visual Studio Solution.
Choosing to Download the .NET Core Cross Platform Solution
This download format is designed for Linux or Windows You will need a .NET Core compatible compiler to run the solution.
Run Anyway and Allow Access
Your device might recognize the file as an unrecognized app with an unknown publisher and ask if you are sure you want to run it. Select the option that will confirm that you want to run the application anyway.
Your firewall might prompt you to confirm access to the app. Select the option that allows access.
Once you have removed the obstacles, the application will run.
Amazon Lex Chatbot Client Application
Enter your Amazon Lex Credentials
Enter your Amazon Lex credentials for your chatbot:
-
- Access key ID
- Secret Access key
- Amazon Region
- Amazon Bot Alias
- Amazon Bot Name
Interact with your Chatbot
Call your testing phone number and watch the log report the interactions with your chatbot.
Ready to try more Sample Solutions?
You can click on More Samples within the app, or go back to your browser and log in to the Voice Elements Customer Portal. We have a tutorial for each sample solution to guide you through running each sample.
You must close the current sample before running another one.
If you want to run the Sample Solution again, you might consider moving the folder out of downloads to your desktop or a location where you want to store all the Sample Solutions.
We hope you try all our Sample Solutions to really see how comprehensive and robust Voice Elements is.
Understanding the Source Code
How easy is it to attach a call to Amazon Lex?
The following snippet demonstrates how you can engage Amazon Lex. Responses from Amazon are returned as KeyValuePairs.
TerminationCode tc = m_VoiceResource.BotEngage(botMode, null, botMode == "ElicitIntent" ? bHello : null);
if (!m_VoiceResource.TerminationCodeFlag(TerminationCode.Normal)) return;
if (m_VoiceResource.BotResponse == null) return;
foreach (KeyValuePair<string, object> kvp in m_VoiceResource.BotResponse)
{
Log.Write($"key: {kvp.Key} -- value: {kvp.Value}");
}
How do I set my credentials for Amazon Lex?
The following snippet demonstrates how to prepare for calling a chatbot. In order to connect to your Amazon Lex bot, you will need an IAM User which can be found under My Security Credentials on your AWS console. You will need to set up this user with the correct permissions to access Amazon Lex. It also needs to be setup with an access key. Below paired with amazonID should be your access key ID, paired with amazonPW should be your secret access key. See also IAM Users Guide.
m_VoiceResource.BotParameters = new Dictionary<string, string>();
m_VoiceResource.BotParameters.Add("amazonID", "**************");
m_VoiceResource.BotParameters.Add("amazonPW", "*************************");
m_VoiceResource.BotParameters.Add("amazonRegion", "USEast1");
m_VoiceResource.BotParameters.Add("amazonBotAlias", "TestOne");
m_VoiceResource.BotParameters.Add("amazonBotName", "BookTrip");
m_VoiceResource.BotParameters.Add("amazonUserId", Guid.NewGuid().ToString());
How can I get started?
Here is a working script that you can add to the Getting Started sample that comes with Voice Elements:
public void RunScript()
{
try
{
// Answer the phone.
m_ChannelResource.Answer();
Log.Write("Using VR: {0}", m_VoiceResource.DeviceName);
m_VoiceResource.MaximumTime = 30;
bool bError = true;
m_VoiceResource.BotParameters = new Dictionary<string, string>();
m_VoiceResource.BotParameters.Add("amazonID", "Access key ID");
m_VoiceResource.BotParameters.Add("amazonPW", "Secret Access key");
m_VoiceResource.BotParameters.Add("amazonRegion", "USEast1");
m_VoiceResource.BotParameters.Add("amazonBotAlias", "TestOne");
m_VoiceResource.BotParameters.Add("amazonBotName", "BookTrip");
m_VoiceResource.BotParameters.Add("amazonUserId", Guid.NewGuid().ToString());
// Change this if you want the prompt to play to completion before it starts streaming the users voice
m_VoiceResource.DetectBargeIn = true;
//string botMode = "ElicitIntent"; // If you set this, then it will hit amazon first to get it's first prompt.
string botMode = "PlayFile"; // This says to play a file that you have recorded first.
while (true)
{
bError = true;
TerminationCode tc = m_VoiceResource.BotEngage(botMode, botMode == "PlayFile" ? @"D:\AmazonTest\HowCanIHelpYouToday.wav" : null, null);
if (!m_VoiceResource.TerminationCodeFlag(TerminationCode.Normal)) break;
if (m_VoiceResource.BotResponse == null) break;
foreach (KeyValuePair<string, object> kvp in m_VoiceResource.BotResponse)
{
Log.Write($"key: {kvp.Key} -- value: {kvp.Value}");
}
string dialogState = m_VoiceResource.BotResponse["DialogState"] as string;
if (dialogState == null) break;
if (dialogState == "Failed") break;
if (dialogState == "Fulfilled" || dialogState == "ReadyForFulfillment")
{
bError = false;
break;
}
botMode = "PlayBotStream";
}
if (bError)
{
m_VoiceResource.Codec = Codec.Automatic;
m_VoiceResource.DataFormat = DataFormat.Wave;
m_VoiceResource.PlayTTS("Sorry there was an error.");
}
else
{
m_VoiceResource.Codec = Codec.Automatic;
m_VoiceResource.DataFormat = DataFormat.Wave;
m_VoiceResource.PlayTTS("Gotcha Covered.");
}
m_VoiceResource.PlayTTS("Goodbye");
return;
}
catch (ElementsException ee)
{
// These are Telephony Specific exceptions, such an the caller hanging up the phone during a play or record.
if (ee is HangupException)
Log.Write("The Caller Hungup!");
else
Log.WriteException(ee, "Script Elements Exception");
}
catch (Exception ex)
{
// This would be a general logic exception, such as a null reference violation or other .NET exception.
Log.WriteException(ex, "InboundIVR Exception");
}
finally
{
// Disconnect the call (I.E. Hangup)
m_ChannelResource.Disconnect();
// Dispose of the channel resource, (this will dispose of its attached voice resource automatically)
m_ChannelResource.Dispose();
// Set these values to null so they cant be referenced anymore. Once the call is disposed, the resources cannot be utilized.
m_ChannelResource = null;
m_VoiceResource = null;
m_TelephonyServer = null;
}
}
Preparing your HmpElements Server [for premise operations]
You will need to have HmpElements Server Version 10.2.2.0.
Add the following settings to the HMPElementsServer.exe.config file:
<setting name="AmazonInterfacePortCount" serializeAs="String">
<value>0</value>
</setting>
<setting name="AmazonInterfaceRecordingPath" serializeAs="String">
<value />
</setting>
The Port Count is the number of simultaneous operations you expect to have. For example, 4 incoming calls = 4 AmazonInterfacePortCount. You could do more if you wanted more in the queue.
The recording path is to capture the audio of what is being sent to Amazon. It writes a RAW PCM 8000Hz, Mono, 16bit file. You can use Goldwave or your favorite audio editor to listen to them. There will be one file per utterance. So only turn this on if you need to. (You can change this on the fly, without needing to restart HMPElements).
Other Notes
You can ask for the stream that Amazon received to be returned. Just set this:
m_VoiceResource.BotParameters.Add("hmpSendBackStream", "true");
Setting this will return the stream in the m_VoiceResource.BotResponse collection as a MemoryStream. The Key Value is “SpokenStream”.
You can now use a BotMode of “ElicitIntent” and pass a byte[] of the data you want to send to Amazon. This must be RAW (IE no wave headers), and in PCM, 16Bit, 8000Hz, Mono. For example this can be used up front with the first call to BotEngage and causes the BOT to say, “I can help you reserve a car or book a hotel. What would you like to do?”
To load a recording from a file do the following:
FileStream fs = new FileStream(@"D:\Monroe\AmazonTest\Hello.raw", FileMode.Open, FileAccess.Read, FileShare.Read);
MemoryStream ms = new MemoryStream();
using (fs)
{
fs.CopyTo(ms);
}
ms.Position = 0;
byte[] bHello = ms.ToArray();
And use something like this to pass in the the stream:
TerminationCode tc = m_VoiceResource.BotEngage(botMode, null, botMode == "ElicitIntent" ? bHello : null);
Bot Modes
Valid BotModes are: ElicitIntent, PlayBotStream, PlayFile
ElicitIntent engages the BOT and lets it determine what the correct intent is for the call. When using ElicitIntent, you can supply a file to send to Amazon and they will play it as part of the initial conversation.
PlayBotStream moves forward through the conversation.
PlayFile plays a file and then passes control to the Bot.
Have Questions?
Please contact support if you have any questions. We can be reached via email at support@inventivelabs.com.
For a deeper dive into coding Voice Elements and our Class Library, explore: