Using Twilio with SharePoint to send SMS messages

Twilio is a Software as a Service platform that you can use when you want to integrate voice or SMS text messages into your applications. There are a few instances where this could be interesting for SharePoint such as sending SMS messages when certain things happen in SharePoint either through event handlers or workflows. Let’s see how we can easily register for an account, setup a number and start getting SharePoint sending SMS messages using an Event Handler!

1, Visit www.twilio.com and click Try Twilio button – the good news is at the time of writing you get $30 of credit to try Twilio out!

2, Once logged in click on the ‘Upgrade Now’ link to add a credit card to your Twilio account and add a small amount, say $20. You can’t purchase a phone number to send messages from with the trial account (you still get $30 free though once you upgrade)

3, Once upgraded, click Numbers from the main menu and then the ‘Buy a new Twilio Number’ link.

4, You can put in an area code if you like for your number to be based off, or if like me you are in the UK just press search and it will give you numbers to chose from with a London area code

[click the images for a larger view]

5, Find the number you like the look of, and click the ‘Buy’ button to grab it!

6, We need to get our AccountId and Password to use later on in our code. Click on the Dashboard link in Twilio. At the top you’ll see your AccountId, and if you click the padlock to the right your account password will also be displayed. Copy these down for later…

7, The Twilio rest API all runs under https which is a good thing, but means a little extra configuration if you want to use it with SharePoint 2010. We’ll need to do an extra step of uploading the client certificate to SharePoint 2010 for SharePoint to trust the url. Open the following url in Firefox:

https://api.twilio.com/2010-04-01

8, Click on the Twilio icon in the address bar that indicates the certificate for this url is trusted

9, In the panel that opens up click on the ‘More Information’ button:

10, In the Page Information window that opens up click on ‘View Certificate’

11, In the certificate viewer window move to the details tab, and then click the top line in the ‘Certificate Hierarchy’ window and then click the ‘Export’ button. This should allow you to save the certificate.

12, Now we can add the certificate to SharePoint 2010. Open up Central Administration, Click on the Security Link and then ‘Manage Trust’.

13, Click on the New button in the ribbon and a dialog form will pop up. Give the trust relationship a name of Twilio and browse to the certificate file you downloaded in step 10. Finally click on OK.

14, Hurrah – now we can start writing some code. Open up Visual Studio 2010 and create a new SharePoint 2010 Event Receiver project.

15, In the proceeding windows that show as part of creating your Visual Studio project chose to deploy it as a Farm Solution.

16, When setting up the event receiver, pick List Item Events, the Announcement list type and finally the ‘An item was added’ event type – then click Finish

17, Open EventReceiver1.cs and paste in the following code:

private string CreateFormattedPostRequest(Dictionary<string, string> values)
{
    var paramterBuilder = new StringBuilder();
    var counter = 0;
    foreach (var value in values)
    {
        paramterBuilder.AppendFormat("{0}={1}", value.Key, HttpUtility.UrlEncode(value.Value));

        if (counter != values.Count - 1)
        {
            paramterBuilder.Append("&");
        }

        counter++;
    }

    return paramterBuilder.ToString();
}

private HttpWebRequest CreateWebRequest(string endPoint, Int32 contentLength)
{
    var request = (HttpWebRequest)WebRequest.Create(endPoint);

    request.Method = "POST";
    request.ContentLength = contentLength;
    request.ContentType = "application/x-www-form-urlencoded";

    return request;
}  

These two small helper methods will help us format out rest requests to the Twilio rest web service. Thanks to Derik for these two sections of code…

18, Add the following code to your ItemAdded method

string accountId = "";
string password = "";
string from = "";
string to = "";

string title = properties.ListItem["Title"].ToString();

string endPoint = string.Format("https://api.twilio.com/2010-04-01/Accounts/{0}/SMS/Messages.xml", accountId);


Dictionary<string, string> parameters = new Dictionary<string, string>();
parameters.Add("From", from);
parameters.Add("To", to);
parameters.Add("Body", title);

var populatedEndPoint = CreateFormattedPostRequest(parameters);
byte[] bytes = Encoding.UTF8.GetBytes(populatedEndPoint);

HttpWebRequest request = CreateWebRequest(endPoint, bytes.Length);

request.Credentials = new NetworkCredential(accountId, password);

using (var requestStream = request.GetRequestStream())
{
    requestStream.Write(bytes, 0, bytes.Length);
}

using (var response = (HttpWebResponse)request.GetResponse())
{
    if (response.StatusCode != HttpStatusCode.Created)
    {
        string message = String.Format("POST failed. Received HTTP {0}", response.StatusCode);
        throw new ApplicationException(message);
    }
}

base.ItemAdded(properties);

Set the values of accountId and password to the values we got in step 6. The value for ‘from’ should be the number you bought at Twilio, and the ‘to’ value is the number you want to send an SMS to.

19, Tada – we are good to go. Press F5 and Visual Studio will compile and deploy your event receiver to SharePoint. If you do not have an Announcements list at the site Visual Studio opens up simply create one. Then go ahead and add an announcement and wait for the SMS text message to come through! Woot!

Hopefully this has given you a taster to see how easy it is to use Twilio to send SMS text messages from SharePoint. If you have any other ideas how this service would be useful with SharePoint leave them in the comments!

<nickswan/>