Introduction
Like any toolkit, Voice Elements has a variety of different options so that you are able to completely customize your Telephony Application. When you begin development, it can be a little overwhelming, especially if you have never done any Telephony development.
This post explains some of the more commonly confused concepts when beginning development in Voice Elements.
One of the most common actions is to retrieve digits from a user. This is a straightforward process, but there are a variety of different settings that determine how this behaves.
Settings on the VoiceResource
All of the different settings on the VoiceResource determine how the prompts will behave:
VoiceResource.MaximumDigits
This setting determines the maximum amount of digits that can be entered before the prompt returns. This is useful, when you are prompting for common numbers that have a defined length. For example:
VoiceResource.ClearDigitBuffer = false;
VoiceResource.MaximumDigits = 10;
VoiceResource.PlayTTS("Please enter your 10 digit phone number");
VoiceResource.GetDigits();
GetDigits will return as soon as the user enters the 10th digit.
VoiceResource.MaximumTime
This property determines the maximum amount of time that will be spent at a prompt before we time out. This only gets triggered, if the other success conditions are not met first.
This can be useful if users get stuck on a prompt and don’t know what to enter. I often set the MaximumTime within a loop, so that it repeats a message after a given amount of time:
for(int i = 0; i < 3; i++)
{
VoiceResource.MaximumTime = 15;
VoiceResource.MaximumDigits = 1;
VoiceResource.PlayTTS("Please enter 1 for sales, 2 for support");
VoiceResource.GetDigits();
if(VoiceResource.DigitBuffer == 1 || VoiceResource.DigitBuffer == "2")
{
break; // Exit the loop
}
}
If the user never enters a digit, GetDigits will return after 15 seconds, otherwise it will start the play again.
VoiceResource.TerminationDigits
This setting controls which digits when pressed will automatically cause a prompt to return. This is useful, if you want to have a prompt like “Please enter the amount you would like to pay followed by the pound sign”. Remember, that setting the TerminationDigits to “@” or “ANY”, means that any digit entered will interrupt the current set of prompts. Below is an example of how this works:
VoiceResource.TerminationDigits = "ANY";
VoiceResource.ClearDigitBuffer = false;
VoiceResource.PlayTTS("This is a long message, and the customer knows they should enter 1 at this prompt to be directed to where they would like to go, so it's nice to let them interrupt the prompt");
VoiceResource.GetDigits();
One other item to keep in mind, is that setting the last digit to “+” means that it will return the digit that caused the termination. Normally, the TerminationDigit is not included in the Digit Buffer. When you include a “+” sign it means that the termination digit will be returned. For example:
VoiceResource.TerminationDigits = "#+"; string digits = VoiceResource.DigitBuffer;
If the user enters 123#, you will get 123# returned back as the digit buffer.
Alternatively, if you have:
VoiceResource.TerminationDigits = "#"; string digits = VoiceResource.DigitBuffer;
And enter 123#, you will get 123 returned back as the digit buffer.
VoiceResource.InterDigitTimeout
Often customers won’t enter enough digits to cause a prompt to return, or they will forget to enter a termination digit (like a pound sign). The InterdigitTimeout controls how long Voice Elements should wait between digits that a user presses.
VoiceResource.MaximumSilence
This setting is useful when making a recording. Users often forget to enter termination digits (like #), and when set this will cause the Voice Function to return once the maximum amount of silence is met.
VoiceResource.MaximumTime = 30;
VoiceResource.MaximumSilence = 3;
VoiceResource.TerminationDigits = "#";
VoiceResource.PlayTTS("Please record your message after the tone");
VoiceResource.Record("C:\Test.wav");
In the above code, if the user stops speaking, it will return after 3 seconds of silence.
How Voice Elements Determines Whether or Not To Play a Prompt
You may have noticed that when you have multiple prompts Voice Elements will skip through those prompts to the GetDigits function. Below is some example code:
VoiceResource.ClearDigitBuffer = false;
VoiceResource.TerminationDigits = "@";
VoiceResource.MaximumDigits = 4;
VoiceResource.PlayTTS("Hello this message is for ..."); // If the user begins entering their pin here, they won't hear the second prompt. This is because ClearDigitBuffer is set to false.
VoiceResource.PlayTTS("Matt Bowden. Please enter your PIN");
VoiceResource.GetDigits();
Alternatively you can prevent a user from skipping a prompt, by doing something like:
VoiceResource.ClearDigitBuffer = true;
VoiceResource.MaximumDigits = 4;
VoiceResource.PlayTTS("Hello this message is for ..."); // If the user begins entering their pin here, they won't hear the second prompt. This is because ClearDigitBuffer is set to false.
VoiceResource.PlayTTS("Matt Bowden. Please enter your PIN");
VoiceResource.GetDigits();
The digit buffer will get cleared during each Play / GetDigits. This will prevent people from skipping a message.
Using the Termination Code
Whenever, you do any play, record, or get a response from a user, a TerminationCode is returned to you. It’s easy to gloss over this little detail, but it can be invaluable at times to know what the TerminationCode is. Here is an example:
TerminationCode tc;
VoiceResource.MaximumTime = 30;
VoiceResource.MaximumSilence = 3;
tc = VoiceResource.Record(@"C:\Test\Test.wav");
if (tc == TerminationCode.MaximumSilence && VoiceResource.TalkTime > 3)
{
// successful recording
}
else
{
VoiceResource.PlayTTS("I'm sorry, I didn't hear what you had to say");
}
In the above example, we check to see if the TerminationCode is MaximumSilence. If it is, then we want to make sure that we at least got 1 second of non-silent audio.