Basic Functions

This page aims to answer questions about how to perform basic functions. Keep in mind that these code samples often don’t have key pieces that you might want in a full application. For example, if you get a channel resource, you need to make sure that you dispose of it. Please refer to our Sampler project for best practices.

Connecting to Voice Elements Server

It’s a good idea to connect your Voice Elements application to a Voice Elements Server on application start up — otherwise, you can’t perform any Voice functions.

We recommend storing the Voice Elements Server and credentials in a configuration file so you can easily switch between Voice Elements Servers. This also allows you to easily move from our cloud-based service, to your own Voice Elements Server.

try
{
    string sIpaddress = string.Format(@"gtcp://{0}:54331", VoiceApp.Properties.Settings.Default.VEServer); /* Set the connection string */
    s_TelephonyServer = new TelephonyServer(sIpaddress, VoiceApp.Properties.Settings.Default.Username, VoiceApp.Properties.Settings.Default.Password); /* Connect to the Voice Elements Server, by creating a new instance */
    Log.Write("Successfully Connected to: {0}", sIpaddress); /* Write out the connection to the log */
}
catch(Exception ex)
{
    Log.WriteException(ex, "There was an error connecting to Voice Elements!");
}

Answering a call

Voice Elements sends NewCall events whenever it receives phone calls to a certain DNIS (phone number).  However, to receive those new call events, you must register the phone numbers that you would like your application to receive. We typically recommend calling the RegisterDNIS() command without any parameters. If you are running your own server with many different VE applications, you may want to pass in the phone numbers that you would like to register. Lastly, you need to subscribe to the new call event.

s_TelephonyServer.NewCall += new VoiceElements.Client.NewCall(s_TelephonyServer_NewCall); /* We recommend first subscribing to the new call event, so that your application has a method to handle new calls */
s_TelephonyServer.RegisterDNIS(); /* Register the phone numbers that you'd like to respond to */

To answer a call, you simply call the answer function on the channel resource that came in the new call event:

e.ChannelResource.Answer(); /* Answer the phone call */

Reject a call

To reject a phone call, you call the disconnect function before calling the answer method. You can also pass in certain cause codes.

e.ChannelResource.Disconnect(486); /* Disconnects with a busy */

Dial (Make an outbound call)

To place an outbound call, you need a channel resource that’s not currently in use. To do that, you’ll want to get a channel resource:

m_ChannelResource = m_TelephonyServer.GetChannel(); /* Get a Channel resource */

Once you have a channel resource, you simply need to send a dial command:

m_ChannelResource.Dial("5551234567");

How do I set the Caller ID number?

It’s simple, you just need to set the OriginatingPhoneNumber of the Channel Resource

m_ChannelResource.OriginatingPhoneNumber = "5551234567"; /* Set the caller id to 5551234567 */

Call Progress (Detecting Humans vs Machines

You may need to determine if what answers the phone is a human or machine. To do this, you’ll want to change the Call Progress type:

m_ChannelResource.CallProgress = CallProgress.AnalyzeCall;

How long does it wait for an answer?

You can set the maximum amount of time that you would like to wait for phone call to connect by changing the MaximumTime property before a dial. The default is 30 seconds. It can be a good idea to set that to 40 seconds, if you get a lot of no answers when you would expect a machine to answer the call.

m_ChannelResource.MaximumTime = 40; /* Set the maximum time to wait for a call to be answered */

Transfer a Call

To transfer a call, you need to get another Channel Resource to perform a dial on. Once you have a ChannelResource, you can then initiate another outbound call. The key to transferring call is performing a route so that the two sides can talk to each other. Below is code that shows a transfer:

try
{
  m_OutboundChannelResource = TelephonyServer.GetChannel(); /* Get a Channel */
}
catch(Exception ex2)
{
  Log.WriteException(ex2, "Could not get a channel resource!");
}
m_OutboundChannel.RouteFull(m_ChannelResource); /* Route the Channel Resource (which contains the existing call). This allows the other line to hear the phone ringing */
m_OutboundChannelResource.Dial("5551234567"); /* Dial out to a different phone number"); /*

Play a File

All of the interaction that you typically do with a user (including playing files, or getting digits) takes place in the Voice Resource class.

Playing a Voice File is simple. However, if you’re new to telephony, you’ll need to keep in mind that the native format for telephone calls in North America and Japan is 8 bit 8khz mulaw. Elsewhere the native format is 8bit 8khz alaw. It’s a good idea to keep your recordings in this format. We often recommend using a tool like Audacity (Open Source) or Goldwave (Shareware) to save your files in the correct format.

Once you have files that you would like to play, you can use the play command to play them back to a user on an active call.

m_VoiceResource.Play("Hello.wav"); /* Plays a file in the current directory called "Hello.wav" */

Play TTS (Text To Speech)

Text to speech allows you to type what you would like to be said for playback using a computer generated voice. We often recommend starting your application by using Text To Speech, so that you can focus on building your application instead of recording voice files. You simply call the PlayTTS() function to playback Text to Speech to the current call.

m_VoiceResource.PlayTTS("Hello. This is a text to speech sample"); /* Plays back the text to the user listening to that Voice Resource */

Get Digits (IVR)

Gathering input is an essential piece to any Voice application. To get digits from a user, you’ll need to call the GetDigits function. Voice Elements allows you to have very fine-grained control over how you gather digits from users. You’ll want to read the Voice Resource – Deep Dive for information on how to control all aspects of getting input from users.

m_VoiceResource.PlayTTS("Please enter any digit");
m_VoiceResource.GetDigits(1, 10, "ANY"); /* The first parameter is the number of digits to get, the second is the time to wait (in seconds). The third is which digits should cause the GetDigits() function to return. For any digit, you can pass in "ANY", or "@". */
string digit = m_VoiceResource.DigitBuffer; /* The DigitBuffer contains the digits from the last call to GetDigits. */
if(String.IsNullOrEmpty(digit)) /* Check if they've entered digits and respond appropriately */
{
 m_VoiceResource.PlayTTS("I didn't detect a digit");
}
else
{
 m_VoiceResource.PlayTTS("You entered " + digit);
}