Twilio for .NET Developers Part 4: Using the Twilio.TwiML Helper Library

Time to read: 4 minutes

February 02, 2012
Written by
Devin Rader
Twilion

Twilio Bug Logo

This is a series of blog posts that introduce and walk you through using the different .NET Helper Libraries that Twilio provides.

These libraries simplify using the Twilio REST API for .NET developers, and provide as set of utilities that make it easy to work with TwiML and Twilio Client. Take a look at part one,  two, and three of the series.

Using the Twilio.TwiML Helper Library

In the last post we looked at how you can use the Twilio REST API Helper library to initiate outbound phone calls or to send SMS messages.  In the fourth post of this series we’ll look at using the Twilio.TwiML helper library to generate TwiML responses to Twilio requests.

TwiML is a set of XML that is used to instruct Twilio how to handle inbound or ongoing voice calls and SMS messages.  For example, the basic flow between Twilio and your application might look something like this for an inbound voice call:

  1. Twilio receives an inbound voice call and requests TwiML from your application.
  2. Your application returns TwiML instructing Twilio to perform a text-to-speech action, and then wait for user input
  3. Twilio executes those instructions
  4. Twilio receives user input in the form of DTMF codes.  Twilio requests TwiML form your application, this time including the user input value.
  5. Your application uses the user input to perform a database lookup and dynamically generates TwiML instructions which Dial another phone number, bridging the two calls together

This back and forther between Twilio and your application can be quite extensive in complex applications, but it always follows this basic pattern.  A complete reference to TwiML can be found on the Twilio website.

The Twilio TwiML generator simplifies the process of creating TwiML by freeing you from having to manually create well-formed XML responses.  Instead the library provides you with a set of simply methods which you can use to generate TwiML elements an attributes.

To use the Twilio.TwiML helper library add a reference to the library from NuGet:

Once the references are added,  you will create an instance of the TwilioResponse class.  This class represents the root TwiML tag.  The TwilioResponse class exposes methods that let you add TwiML verbs and nouns.  For example, if in a basic ASP.NET Web Application I wanted to return a basic verb as my TwiML response I would call the Say method, passing in the text I wanted to say.

Note that the sample shown here is designed for use in an ASP.NET Web Application.  For developers using the ASP.NET MVC framework that simplify returning TwiML from controller actions.  We’ll look at those in a future blog post.

var twiml = new Twilio.TwiML.TwilioResponse();
twiml.Say(“Hello Monkey!”);

Now to return the generated TwiML, I simply call ToString on the TwilioResponse object and pass the resulting string to the Response object:

var twiml = new Twilio.TwiML.TwilioResponse();
twiml.Say("Hello Monkey!");

Response.ContentType = "text/xml";
Response.Write(twiml.ToString());
Response.Close();

Notice that I’ve also set the Response.ContentType property to text/xml.  This changes the default MIME type of the response so that the requesting client understands that the response content is XML.

The Twilio.TwiML helper library also allows you to fluently chain together multiple method calls.   For example, to create a Gather that includesa Say, I can create fluent method chain:

var twiml = new Twilio.TwiML.TwilioResponse();

twiml.BeginGather(new { action = “directions.cshtml”, numDigits = “1″ })
.Say(“Hello this is a call from Twilio.  You have an appointment tomorrow at 9 AM.”)
.Say(“Please press 1 to repeat this menu.  Press 2 for directions.  Or press 3 if you are done.”);
twiml.EndGather();

Notice in this example that we use an anonymous type to add the action and numDigits parameters to the Gather verb.  This is a common pattern used throughout the Twilio.TwiML helper library for verbs and nouns allow for attributes to be included, and follows API patterns established by the ASP.NET MVC helpers.

Once you’ve got an application generating TwiML, you need to be able to test that Twilio can properly request and receive valid TwiML, which means that you need to host your TwiML on a publicly accessible URL.  There are lots of inexpensive .NET hosting solutions available from traditional paid .NET hosting companies to companies like AppHarbor, who will both build and host your application for you for free.  In a future blog post we’ll go into more detail on different hosting options.

In the next post will look at the remaining helpers libraries available, including helpers for ASP.NET MVC applications, helpers for Razor syntax, and helpers for working with Twilio Client.

Read the rest of the .NET series:
Twilio for .NET Developers Part 1: Introducing the Helper Libraries 
Twilio for .NET Developer Part 2: Adding Twilio Helper Libraries to your Project
Twilio for .NET Developers Part 3: Using the Twilio REST API Helper Library

This series is written by Twilio Developer Evangelist Devin Rader. As a co-founder of the St. Louis .NET User Group, a current board member of the Central New Jersey .NET User Group and a former INETA board member, he’s an active supporter of the .NET developer community. He’s also the co-author or technical editor of numerous books on .NET including Wrox’s Professional Silverlight 4 and Wrox’s Professional ASP.NET 4. Follow Devin on Twitter @devinrader

Related Posts

Related Resources

A newspaper article

Twilio Docs

From APIs to SDKs to sample apps

API reference documentation, SDKs, helper libraries, quickstarts, and tutorials for your language and platform.
An Open book

Resource Center

The latest ebooks, industry reports, and webinars

Learn from customer engagement experts to improve your own communication.
User group reactions

Ahoy

Twilio's developer community hub

Best practices, code samples, and inspiration to build communications and digital engagement experiences.