Tropo is part of CiscoLearn More

Using C# to Send Outbound Calls and SMS Messages

Posted on November 8, 2010 by Adam Kalsey

“Choices are the hinges of destiny” — Pythagoras

From a developer’s perspective, one of the most attractive things about the Tropo platform is the array of choices it provides. Choice can empower developers.

In addition to supporting two different methods for running Tropo applications – Tropo Scripting and Tropo WebAPI – developers can use a wide variety of languages to build Tropo applications. Tropo scripting applications can be written in JavaSctipt, PHP, Ruby, Python or Groovy. The Tropo WebAPI lets developers write applications in any language that can parse JSON and speaks HTTP.

A number of libraries exist to assist developers in building WebAPI applications and also for interacting with the Tropo Session API – which lets developers initiate outbound messages over several different channels.

If you are a C# developer, one of the easiest ways to move into developing Tropo applications is to use the Tropo C# library. And while this library is currently focused on building Tropo WebAPI applications, it can also be used to interact with the Tropo Session API to initiate outbound telephone calls and SMS messages.

This post will introduce C# developers to the Tropo C# library and walk through a simple example of using C# to send outbound calls and SMS messages. To keep things simple, we’ll use a very simple Tropo scripting application written in JavaScript.

Getting the Tropo C# Library

The easiest way to get the Tropo C# library is to clone the GitHub repo where it is housed. (Note – If you don’t want to use Git, you can simply download the zip file and extract the contents to the desired location on your computer.)

You’ll find a very good Git client for Windows in the msysgit project, hosted on Google Code. There are a number of very good guides available on the Interwebs that detail how to get started using Git on Windows so I’ll skip them here.

Once you have your Git client installed, just clone the Tropo C# library to a location on your machine. In Windows explorer, right mouse click on the directory where you want to clone the repo and select “Git Bash here.” This will open up the Git shell.

Clone the repo by using the git clone command and the Git URL for the repo on GitHub.

Clone the GitHub repo

Follow the usage instructions in the library’s readme file to build the solution successfully. Once you have that done, you’re ready to set up an application in Tropo Scripting that will make outbound calls and send SMS messages.

Setting up an Application

For this example, we’re going to use a very simple Tropo script written in JavaScript. You can access this script for your own use on GitHub.

// If the channel selected is TEXT, send a message.
if(channel == 'TEXT')
{
log("*** Sending text message. ***");
message("Hello, " + customerName + ", " + msg, { to: sendToNumber, from: fromNumber, network: "SMS"} );
}
// If the channel selected is Voice, make a call.
else
{
log("*** Making outbound phone call. ***");
call('tel:+1' + sendToNumber, {
onAnswer: function() {
say("Hello, " + customerName + ", " + msg + ". This is a test message for a telephone.");
}
});
}

To set up this application in Tropo Scripting, log into your Tropo account and go to the “Your Applications” section. Create a new application, and when prompted select Tropo Scripting.

Create a New Application

During the application set up, you will be prompted to give the application a name and to identify the URL of the file that will run the application. And while you can certainly host this script ina location of your desire (even in your Tropo account), for this example we will use the JavaScript file discussed above that is hosted on GitHub. When viewing this file on GitHub, click on the “raw” link to see the raw text of this file. Copy and paste the URL to the raw view of the file into the application mapping for your Tropo application, as demonstrated below.

Once that is done, you’ll want to add a Voice and Messaging number to your application. When you first create a Tropo application, several types of numbers are automatically provisioned for your use – A Skype number, a SIP number and an iNUM. In order to make outbound telephone calls and send SMS messages from Tropo, you will need to have a PSTN number provisioned.

Simply click on the “Add a new phone number” link in your application settings to add a number.

Building a C# Application

Once you have the Tropo C# library successfully compiled and an application set up in your Tropo account, you’re now ready to start build a C# application. For this example, we’ll simply write a small console application that will kick of an outbound call or SMS message.

If you have the Tropo C# library solution open, you can simply add a new project in the “Solution Explorer” inside Visual Studio. Select a Windows Console Application from the template list.

It should come as no surprise at this point that you can obtain the sample code for this console application on GitHub. You’ll need to make sure you add the appropriate references to your project in order to test it successfully (note the using statements in the file). You will also want to add several details from your Tropo application settings:

  • Make sure you add the Voice and Messaging tokens that were provisioned for your application when you set it up. You should see them listed in your application settings below the provisioned phone numbers.
  • Add the phone number that you provided for Voice and Messaging calls (discussed above). This will allow you to use this number as the caller ID on outbound calls and SMS messages.

Once this is done, you can change the value of the sendToNumber parameter to the phone number you want to send a call or SMS message to.

You will note that our example application is using the CreateSession() method of the Tropo object to send an HTTP request with our tokens and parameters to the Tropo Session API. The response we get back is in XML format.

To run this demo application, simply hit F5 while the solution is open in Visual Studio (you may need to change the “Startup Project” in the Solution properties for this to work).

You may also change the other parameters in our example C# file to your liking as well – if you look at the names of these parameters, and compare them to the JavaScript file we loaded into our Tropo application above, you will see that they match the variables used in our JavaScript file. When you invoke the Tropo Session API and pass in parameters, variables with those same names that are in your Tropo script are assigned the values you send to the API.

The nice thing about having an application set up to manage how outbound messages get sent is that it provides the flexibility to customize the content that is delivered to specific channels. Some channels, like SMS and Twitter, have limitations that are not present with other channels (i.e., a fixed character limit). Other channels – i.e., voice – may require special formatting to ensure proper message delivery (e.g., phonetic replacement on specific words).

Conclusion and Further Thoughts

In this post, we used a very simple JavaScript file running on the Tropo Scripting platform. However, the Tropo C# library can do much more than simply invoke the Session API to send outbound messages.

This library is a rich, full featured tool set for building Tropo WebAPI applications with C#. There are times when using the Tropo Scripting platform is more ideal, and there are other times when building a WebAPI application make more sense. For example, applications that may need to access data in a backend system (a database or CRM system) might be a better fit for the WebAPI platform.

Whatever the specific requirements of your application, the Tropo C# library is a convenient tool that can make the job easier.

Because this library is housed on GitHub, it can be forked, modified and customized to your needs. If you have some ideas for changes or modifications that you’d like to see, let us know or simply fork the repo and have at it!

2 Responses

  1. Scott says:

    The javascript file hosted on GitHub has a different parameter name for the dialed number (numberToDial), causing the process to fail using the C# sample above, which uses sendToNumber as the parameter name. The javascript listed above is correct, so creating a hosted file on Tropo using that code allows everything to work.

  2. Mark Headd says:

    Good catch – thanks!

    I’ve updated the file on GitHub that is linked to from this post.

Leave a Reply