This post is a follow up to one done previously demonstrating how to use the C# library for the Tropo WebAPI to send outbound SMS messages.

We’ll walk through the process of setting up a Tropo account, loading in the start URL for your application and invoking the Tropo Session API to send a message.

The first thing you’ll need to do, is get the Tropo C# library – follow the instructions in the previous post for cloning the GitHub repo for this library. If you’d rather not use Git, you can simply download the ZIP file and extract the contents to a convenient location.

Either way, once you get this source for the library, fire up Visual Studio and follow the instructions for obtaining project dependencies and successfully building the solution.

Setting up Your Application

In order to send outbound SMS messages, you will need two things:

1. A “starter” component that will initiate outbound messages by invoking the Tropo Session API and include any information needed to compose a message to an end user. (This component could be a Windows service, a WCF application, etc. The only requirement is that it must be able to make an HTTP request to the Tropo Session API.) Note – do not set this starter component as the start URL for your application.
2. A “catcher” component that will use information submitted with your API request to compose the text of an outbound message and instruct the Tropo platform to send it. This component must return valid JSON to the Tropo platform in response to an HTTP POST.

Our “catcher” application for this example will be a simple ASP.NET page – it’s included in the Tropo Samples project within the Tropo C# library solution, called OutboundSMS.aspx. If you look at the code behind for this page, you’ll see that it uses the Tropo Session object to get parameters that are submitted by Tropo. These parameters are sent to Tropo by your “starter” application – we’ll get to that in a moment.

Note that the exception handlers in this example will attempt to write an entry into the event viewer using a log source of “TROPOWEBAPI”. You can use entries in your event viewer to help you debug problems that you might be having as you develop your Tropo application.

This “catcher” app needs to be in a location that can be accessed by the Tropo platform. Tropo will make an HTTP request (using the POST method) for this script, sending along a JSON payload. the structure of this payload can be seen here. In addition, any parameters that you use when invoking the Tropo Session API will be included in this JSON payload.

You can stage this ASP.NET application on a public server, on a hosting platform like AppHarbor, or on your lcoal development machine (if you have set up a way for external HTTP requests to be received, i.e., with Tunnlr). Once you’ve done this, log into your Tropo Account and create a new WebAPI application.

Enter the URL for your ASP.NET application in the Start URL field. Click “Create Application” to create your application and view settings.

Make note of the voice and messaging tokens provisioned for your application. We’ll need those in the next step.

Also, make sure you provision a phone number for your application – applications without a provisioned phone number will not be able to send outbound SMS messages.

For the purposes of this post, our “starter” application (which will be used to invoke the Tropo Session API) will be a simple console application. The code for this example is in the TropoOutboundSMS project in the Tropo C# library solution.

The code for this console application looks like this.

using System;
using System.Collections.Generic;
using System.Web;
using System.Xml;
using TropoCSharp.Structs;
using TropoCSharp.Tropo;

namespace OutboundTest
{
    class Program
    {
        static void Main(string[] args)
        {
            // The voice and messaging tokens provisioned when your Tropo application is set up.
            string voiceToken = "your-voice-token-here";
            string messagingToken = "your-messaging-token-here";

            // A collection to hold the parameters we want to send to the Tropo Session API.
            IDictionary<string, string> parameters = new Dictionary<String, String>();

            // Enter a phone number to send a call or SMS message to here.
            parameters.Add("sendToNumber", "15551112222");

            // Enter a phone number to use as the caller ID.
            parameters.Add("sendFromNumber", "15551113333");

            // Select the channel you want to use via the Channel struct.
            string channel = Channel.Text;
            parameters.Add("channel", channel);

            string network = Network.SMS;
            parameters.Add("network", network);

            // Message is sent as a query string parameter, make sure it is properly encoded.
            parameters.Add("msg", HttpUtility.UrlEncode("This is a test message from C#."));

            // Instantiate a new instance of the Tropo object.
            Tropo tropo = new Tropo();

            // Create an XML doc to hold the response from the Tropo Session API.
            XmlDocument doc = new XmlDocument();

            // Set the token to use.
            string token = channel == Channel.Text ? messagingToken : voiceToken;

            // Load the XML document with the return value of the CreateSession() method call.
            doc.Load(tropo.CreateSession(token, parameters));

            // Display the results in the console.
            Console.WriteLine("Result: " + doc.SelectSingleNode("session/success").InnerText.ToUpper());
            Console.WriteLine("Token: " + doc.SelectSingleNode("session/token").InnerText);
            Console.Read();
        }
    }
}

Sending SMS Messages

You’ll want to replace the default values in the above script with the voice and messaging tokens provisioned for your application in the last step. You’ll also want to replace the values for sendToNumber (the number where the SMS message will be sent) and the sendFromNumber (the caller ID that will be used for the outbound SMS).

An important note – the value of sendFromNumber must be the same as a phone number provisioned for your application in your account settings. Otherwise, your SMS message may be dropped. Carriers have very specific rules regarding caller ID settings on outbound SMS messages, and unless the caller ID on the messages match the number set up in your account the message will not be delivered properly.

Once you have made these changes, just run the console application (Program.cs). The easiest way to do this is to make the TropoOutboundSMS project the startup project for your solution. Simply right mouse click on the project and select “Set as Startup Project”‘. Once this is done, you can hit F5 to run it.

That’s it!

If you run into issues, there are two places you can look for information – first, have a look in the event viewer on the host running your ASP.NET web app. (Remember, we’re logging information there when exceptions get thrown.)

You can also open the real time Application Debugger in your Tropo account when you run your console application. This will display any errors or exceptions and allow you to identify something that might have gone wrong.

Because the Tropo C# library for WebAPI 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!