Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

Usage and Migration Guide for Twilio's C#/.NET Helper Library 5.x

Deprecation notice: New functionality will only be added to the new library (C# 5.x). The old library (C# 4.x) is deprecated and Twilio will no longer provide bug fixes. Support might ask you to upgrade before debugging issues. The old library will remain available indefinitely on GitHub.

The open source Twilio C#/.NET SDK has undergone significant changes from version 4.x to 5.x - we'll break down the major changes here to make migrating to the new version as painless as possible. If you're integrating Twilio in your C#/.NET app for the first time, you can skip straight to the install 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
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
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, for 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

The older version of the library contained a single client class that had hundreds of methods to perform various tasks (sending messages, retrieving call logs, etc.). Now, 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 resources. Where a method isn’t supported by Twilio for a given resource, it is omitted from the class.


Many resources can be created. Do 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."

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 return variable message.


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");


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)


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 of the resources you needed. Now, paging is handled automatically. In the example above -- and any time you use Read -- you can simply 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)

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 methods allow you to modify a specific resource. To use an Update method you’ll need to know the resource’s unique identifie.. 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 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:


Passing 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 a large number of 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 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 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("")
    return call;

Handling errors

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



        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 library to generate the TwiML is a good way to make sure you’re generating well-formed TwiML and a smart editor like Visual Studio or VS Code can tell you what verbs, nouns, and attributes are available when constructing your response.

        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.


        To build TwiML to handle a phone call, just 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 greeting in a specific language:


              And an example with nested verbs:



                    Generating TwiML for SMS responses is done in much the same way, but with the MessagingResponse class. Having different classes makes it easy for you to know what methods are supported in the two different contexts.

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


                          And an example sending a message with Media attached:


                                Debugging 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
                                            UTC Date/Time:
                                            2/1/2018 11:19:02 PM

                                            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

                                                  ASP.NET MVC Helpers

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

                                                  Where to Find Help

                                                  All of the Quickstarts, Tutorials, and API Reference documentation will have example code in both the older 4.x library and the new 5.x library. There are hundreds of samples just 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. Just contact us directly for support.

                                                  Rate this page:

                                                  Need some help?

                                                  We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.