Voice Resources

Voice Resources allow you to interact with a user through the application. When someone calls in to Voice Elements (or receives a call from Voice Elements), they are connected via a Channel Resource. A Voice Resource will typically be routed to the Channel Resource which will allow you to both play audio and tones to a user, and receive input from that user.

Voice Resource functions are typically blocking functions. This means that when you execute them, they will return when the termination conditions have been met. There are various properties that you can set that control what conditions will cause Voice Resource functions to return. For example, let’s say you want to record a user, you can set the MaximumTime to limit the amount of time that the recording takes to 10 seconds. You set these properties on the Voice Resource and they will take effect for the different Voice Resource functions that you call (like Record, GetDigits, GetResponse, and Play).

Voice Resource Properties

There are a variety of properties that you can set which allow you to have meticulous control over gathering input from a user.

These properties are all used in conjunction with each other, which also gives you control over how they behave. For example, if you do a recording and set the MaximumTime to 10, and the MaximumSilence to 2, it will terminate the recording after 2 seconds of silence OR if there is never 2 seconds of silence it will return after 10 seconds.

You only need to set the properties that you use, and only properties that are related to a particular function will be used for that function. For example, when performing a play, the MaximumSilence will not have any effect.

Termination Code

When you perform a Voice Resource function, it will return a TerminationCode. The Termination Code is the reason why the voice function returned. It’s important to remember that if multiple termination conditions are met, multiple termination codes will be returned back to the user. For example, if you set MaximumDigits to 1, and TerminationDigits to “#”, it will return a termination code containing MaximumDigits and Digit to indicate that the maximum amount of digits was pressed AND that a termination digit was pressed. The TerminationCodeFlag allows you to search to see if a particular condition is contained in the termination code result.

GetDigits

GetDigits() is the function that you call to retrieve digits from a user. It returns once a termination condition has been met. Below are a few examples:

VoiceResource.MaximumDigits = 1;
VoiceResource.MaximumTime = 5;
VoiceResource.PlayTTS("Hello and welcome to the real estate hotline.");
VoiceResource.PlayTTS("Press 1 to speak to an agent now.");
TerminationCode tc = VoiceResource.GetDigits();
/* If the user presses a digit, the termination code will be MaximumDigit. If they do not, the termination code will be Digit */

In the above example, we’ve said that we want to terminate Voice Operations after 1 digit is entered, and 5 seconds after the call to GetDigits. For example, if the user entered 1 during the first prompt, it would cause that play to be interrupted, and the second prompt would not be heard. The GetDigits would return immediately as well. If you were to access the DigitBuffer at that point, it would contain a “1″. If the user did not enter a digit after 5 seconds (starting from the end of the last prompt), then it would return with a Termination Code of

The GetDigits function has a variety of overloads. What’s nice about the overloaded function calls is that they DO NOT change the associated Voice Resource properties. So if you had the MaximumTime parameter set to 10, it would NOT set the MaximumTime to 10.

VoiceResource.PlayTTS("Please enter the ten digit phone number you would like to call");
VoiceResource.GetDigits(10, 15, "", 4);

The first parameter is the maximum number of digits we allow. The second parameter is the maximum time to wait, the third parameter is the termination digits (we set it to blank — there are no digits that will cause it to return early). The fourth parameter is the InterDigitTimeout. This means that if they press a digit and don’t press another for four seconds, it will return.

GetResponse

The GetResponse function works similarly to GetDigits. However, it works for Speech Recognition. When using GetResponse if you would like to detect both speech and digits, you will want to check the TerminationCode to see if the user entered digits, or said something. Please see the Speech Recognition section for more information on using Speech Recognition.

Digit Buffer

Once a call to GetDigits() or GetResponse() is made, digits are placed in the digit buffer. Here’s an example of usage:

VoiceResource.ClearDigitBuffer = false;
VoiceResource.TerminationDigits = "@";
VoiceResource.MaximumDigits = 1;
VoiceResource.PlayTTS("You have reached Inventive Labs.");
VoiceReesource.PlayTTS("For Sales, press 1");
VoiceReesource.PlayTTS("For Support, press 2");
VoiceResource.GetDigits();
string digits = VoiceResource.DigitBuffer; /* Now that GetDigits has been called, the digits should now be in the buffer */
if(digits == "1")
{
// transfer to sales
}
else if(digits == "2")
{
// transfer to support
}

By virtue of setting the MaximumDigits to 1 (and the Termination Digits to “@”), when the user presses a digit, the application will skip down immediately to the call to getdigits and return immediately. At that point the digit buffer will have the digit that they pressed. It will be in the DigitBuffer until the next Voice Operation.

It’s important to note that if ClearDigitBuffer were set to true, then the DigitBuffer would get cleared on each play operation and call to GetDigits.

Maximum Time

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. It can be helpful to set the 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 = 10;
     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
     }
}

Termination Digits

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.”  In this case, you would set the Maximum Digits to “#.”

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();

Also, if you want to know which digit caused the termination, you can put a “+” after the other termination digits. For example:

VoiceResource.TerminationDigits = "#*+";
VoiceResource.PlayTTS("Press # to listen to this message again, and * to return to the previous menu.");
VoiceResource.GetDigits();
string digitBuffer = VoiceResource.DigitBuffer;
if(digitBuffer == "#")
{
 // replay message
}
else if(digitBuffer == "*")
{
 // return to the previous menu
}

Maximum Digits

The MaximumDigits property controls the maximum number of digits that a user can enter before causing Voice Resource functions to terminate. For example, you could set the MaximumDigits to 10 if you wanted to allow a user to enter their ten digit phone number. That way they could enter in 10 digits and you could move to the next prompt, without needing them to enter a pound sign or other termination digit.

Inter Digit Timeout

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.

InterDigitTimeoutStartsAfterFirstDigit

This setting controls when Voice Elements begins to “count” the interdigit timeout. For example, let’s say you have MaximumTime set to 20 and InterDigitTimeout set to 4. When this property is set to true, it will only return after a user has entered a digit. If it is set to false, it will return after 4 seconds (if the user has not entered a digit).

ClearDigitBuffer

When this property is set to true, it clears the digit buffer before the next voice operation.

For example, let’s say you have code that looks like this:

VoiceResource.ClearDigitBuffer = true; 
VoiceResource.PlayTTS("Hello this message is for ..."); 
VoiceResource.PlayTTS("John Smith"); 
VoiceResource.PlayTTS("Please enter your PIN");
VoiceResource.GetDigits();

If a user started to enter their PIN during the first prompt, the digit buffer would get cleared during each subsequent prompt. This means that ONLY the digits entered after the GetDigits would be available.

We typically recommend that you keep this setting to false, unless you are certain that you want to clear the digit buffer.

Maximum Silence

MaximumSilence is used to determine how much silence to allow in a recording before returning. Often, users will forget to enter digits to stop the recording and the MaximumSilence is a good way of stopping things for them.

Speech Recognition

Speech Recognition lets your users control your voice application with their voice. Use this link for more information on using Speech Recognition.

Beep Detection

Beep Detection allows you to detect beeps that are found in answering machines. You can use the beep detector for more accurate call progress, or to make sure that the entirety of your message gets played back to your users. Use this link for more information on using the beep detector.

Record Conversation

The RecordConversation allows you to record both sides of a phone call. This is useful if you need to record call center conversations, or if you’d like to improve the usefulness of an IVR system.