Usage and migration guide for Twilio's C#/.NET Helper Library 6.x

The 6.x version of the open source Twilio C#/.NET SDK has the same API as the previous 5.x version. Behind the scenes, the SDK is now generated with the help of Twilio's OpenAPI specification, but if you're currently using version 5.x of the Twilio C# SDK, you will not need to modify how you use the library.

If you're integrating Twilio in your C#/.NET app for the first time, you can skip straight to the installation page.

.NET Version Compatibility

The Twilio C# SDK supports .NET applications written in C#, VB.Net, and F# that utilize the .NET Framework version 3.5 or higher, or any .NET runtime supporting .NET Standard v1.4.

Client Initialization

Initializing the client for future REST API calls is now a static method. For most use cases, there is no need to directly create a client object.

// Find your Account Sid and Auth Token at twilio.com/user/account
var accountSid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
var authToken = "your_auth_token";
TwilioClient.Init(accountSid, authToken);

This only needs to be done once. All subsequent calls to the Twilio API will be authenticated using the credentials passed to the Init method.

Manual Client Initialization

For use cases that require different credentials per request, such as subaccounts, instantiate a new TwilioRestClient object directly instead of calling Init(). Then, pass the client object into the resource method via the optional client parameter.

// Find your Account Sid and Auth Token at twilio.com/user/account
var accountSid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
var authToken = "your_auth_token";
var client = new TwilioRestClient(accountSid, authToken);

// Pass the client into the resource method
var message = MessageResource.Create(
    to: new PhoneNumber("+15558675309"),
    from: new PhoneNumber("+15017250604"),
    body: "Hello from C#",
    client: client);

To ensure thread safety, create a new TwilioRestClient for each unique set of credentials.

Custom Client

The helper library methods that make REST API requests each have an optional client parameter. By default, the library will use the default TwilioRestClient object that gets created when you call TwilioClient.Init(). If you need to manipulate the HTTP requests in any way as they are made (for example, if using a proxy server), you can write your own class that implements ITwilioRestClient, and pass an instance of that class to the helper library method calls. For the majority of use cases, this will not be necessary.

Examples of using a custom client in the Twilio helper library are available for both .NET Framework and .NET Core.

Resource Classes

Each resource in the Twilio REST API has a corresponding C# class. Want to work with SMS messages? You need the MessageResource class. Phone calls? Check out CallResource.

Each resource class has a set of static methods you can call to Create, Fetch, Read (list), Update, and Delete the respective resources. Where a method isn’t supported by Twilio for a given resource, it is omitted from the class.

Create

Many resources can be created. To do so, call the Create static method on the class. For example, here’s how to create (send) a new SMS message:

var message = MessageResource.Create(
    to: new PhoneNumber("+15558675309"),
    from: new PhoneNumber("+15017250604"),
    body: "I am one with C# and C# is with me."
);
Console.WriteLine(message.DateCreated);

This will create a Message resource on Twilio (which sends the message), and you will have access to all the properties of the resource in the returned variable, in this case message.

Fetch

Use Fetch when you know the unique identifier of a specific resource, and you want to retrieve all of its properties. For example, you could retrieve information about your Twilio account:

var account = AccountResource.Fetch("ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX");
Console.WriteLine(account.DateCreated);

Read

Read methods fetch a list of resources. Often, the Read method will provide additional filtering parameters to narrow down the list of results you get back. Here’s how you might get a list of calls that were made to a specific number:

var calls = CallResource.Read(to: new PhoneNumber("+15558675309"));
foreach (var call in calls)
{
    Console.WriteLine(call.StartTime);
}

Paging

In prior versions of the helper library, you had to worry about paging. You would retrieve one page of results and then continue requesting pages until you’d retrieved all the resources you needed. Now, paging is handled automatically. In the example above -- and any time you use Read -- you can iterate through the results that come back, and any requests for additional pages of results will be made for you.

var thirtyDaysAgo = DateTime.UtcNow.AddDays(-30);
var messages = MessageResource.Read(dateSentAfter: thirtyDaysAgo);
// Iterating automatically requests additional pages 
// from the Twilio REST API
foreach (var message in messages)
{
    Console.WriteLine(message.Body);
}

If you wish to enforce a limit on the number of records returned, include a limit parameter. For example, here’s how to limit the number of records to 50:

var messages = MessageResource.Read(dateSentAfter: thirtyDaysAgo, limit: 50);

Update

Update methods allow you to modify a specific resource. To use an Update method, you’ll need to know the resource’s unique identifier. Here’s an example that redacts a previously sent or received SMS message by setting the Body to an empty string:

MessageResource.Update("MM5ef8732a3c49700934481addd5ce1659", "");

Delete

Delete methods remove the resource from Twilio’s servers. Like Fetch and Update methods, it takes the unique identifier of the resource to be deleted. For example, you may want to delete a recording of a call:

RecordingResource.Delete("RE557ce644e5ab84fa21cc21112e22c485");

Pass arguments

There are two ways each of the above methods can be called on a resource class. The first you’ve seen. You pass positional and/or named arguments to the methods. Optional arguments will have a default value of null. Take this example of the method signature for MessageResource.Create:

public static MessageResource Create(
        PhoneNumber to, 
        string accountSid = null, 
        PhoneNumber from = null, 
        string messagingServiceSid = null, 
        string body = null, 
        List<System.Uri> mediaUrl = null, 
        System.Uri statusCallback = null, 
        string applicationSid = null, 
        Decimal? maxPrice = null, 
        bool? provideFeedback = null, 
        ITwilioRestClient client = null)

Even though there are many arguments to the Create function, many are optional, so you can only pass in the arguments you need using named arguments:

var message = MessageResource.Create(
    to: new PhoneNumber("+15558675309"),
    from: new PhoneNumber("+15017250604"),
    body: "I am one with C# and C# is with me."
);

However, each of a resource’s Create, Update, Read and Delete methods can also be called using an Options class. Here’s the version of MessageResource.Create that takes a single CreateMessageOptions class.

Rather than specifying many individual arguments, you instead create a CreateMessageOptions class, set your message values using its properties, and then pass it to the Create method. If you were fetching, the class would be FetchMessageOptions. If you were deleting a recording, then it would be DeleteRecordingOptions. Sense a pattern forming?

When using an Options class, the constructor will contain each of the required properties for the resource you are using and action you wish to perform. For example, when creating an SMS, you must provide a to phone number, so that is an argument to the CreateMessageOptions constructor. Any remaining properties can be set on the Options object that you create:

var options = new CreateMessageOptions(new PhoneNumber("+15558675309"));
options.From = new PhoneNumber("+15017250604");
options.Body = "I am one with C# and C# is with me.";

var message = MessageResource.Create(options);

Asynchronous methods

If you’re using .NET Framework 4.5.1+ or .NET Core 1.0+, then you can use asynchronous versions of the Create, Fetch, Read, Update, and Delete resource methods. Predictably, these methods are named CreateAsync, FetchAsync, ReadAsync, UpdateAsync, and DeleteAsync. Here’s an example that creates a new call using CreateAsync:

public async Task<CallResource> PhoneHomeAsync()
{
    var call = await CallResource.CreateAsync(
        to: new PhoneNumber("+15558675309"),
        from: new PhoneNumber("+15017250604"),
        url: new Uri("http://demo.twilio.com/docs/voice.xml")
    );
    return call;
}

Handle errors

Instead of checking the response for a RestException, you now need to catch the ApiException exception, as shown in this example:

TwiML

The Twilio C# SDK now includes helper classes to generate TwiML. You may have previously generated the XML manually or perhaps used the separate Twilio.TwiML library. Using the helper library to generate your TwiML is a good way to make sure you’re generating well-formed TwiML. A quality IDE, like Visual Studio or VS Code, can also tell you what verbs, nouns, and attributes are available when constructing your TwiML.

There are two classes you can use to generate TwiML: Twilio.TwiML.VoiceResponse and Twilio.TwiML.MessagingResponse. You would use the former when handling a voice call, and the latter when responding to a text message.

VoiceResponse

To build TwiML to handle a phone call, create an instance of the VoiceResponse class and then call methods on the new object that correspond to the various TwiML verbs. For example, here’s code that plays a message in the Amazon Polly Mathieu voice (using <Say>'s voice attribute) in French (using <Say>'s language attribute):

MessagingResponse

Generating TwiML for SMS responses is done in much the same way, but with the MessagingResponse class. Having different classes clarifies what methods are supported in the two different contexts.

Here’s an example that replies with a simple message:

Debug API requests

To assist with debugging, the library allows you to access the underlying request and response objects. This capability is built into the default HTTP client that ships with the library.

For example, you can retrieve the status code of the last response like so:

Security Tokens for client SDK’s

The Twilio client-side SDK’s for JavaScript, iOS, and Android require authentication or capability tokens to be generated by your server-side code. Token generation for all client SDK’s is built into the helper library. There’s no need to pull in additional NuGet packages (e.g. Twilio.Auth or Twilio.Client). The following tutorials have been updated for the new helper library and show how to generate these tokens:

DateTime values

All DateTime values in the C# helper library are in your local timezone (Kind=Local), as illustrated by this code:

This code sample should create output similar to the following:

Local Date/Time:
2/1/2018 3:19:02 PM
Local

UTC Date/Time:
2/1/2018 11:19:02 PM
Utc

Get DateTime in UTC by default

If you would like all DateTime values returned from the Twilio API to be in UTC format, you may modify the JSON.NET default serializer settings as shown here.

This code would show output like so:

UTC Date/Time:
2/1/2018 11:19:02 PM
Utc

ASP.NET MVC helpers

You may have previously used the Twilio.Mvc library in your ASP.NET MVC projects with version 4.x of the SDK or older. When you migrate to v6.x of this library, you will need to remove the reference to the Twilio.Mvc package and replace it with the Twilio.AspNet.Mvc package.

Where to find help

All the Quickstarts, Tutorials, and API Reference documentation will have example code that works with the latest 6.x SDK methods. There are hundreds of samples waiting for you to copy and paste.

The Twilio C# helper library is open source software. Please visit us on GitHub to view the source, open issues, or submit pull requests.
Finally, we are always ready to help. Contact us directly for support.