New C++ Twilio API Wrapper by Laurent Luce

Time to read: 3 minutes

December 15, 2010
Written by
John Sheehan
Contributor
Opinions expressed by Twilio contributors are their own

Twilio Bug Logo

One of the great things about REST is that all you need to know to use it is how to speak HTTP. It is the ultimate cross-platform technology as near every language or framework can make web requests these days. As an example of this, Laurent Luce has written a Twilio API wrapper in C++. Laurent is a software engineer with expertise in networking and web services using technologies such as Python, Django, Javascript, C++, MySQL and AWS.

The C++ Twilio REST SDK simplifies the process of making requests to the Twilio REST API, generating TwiML and validating HTTP request signatures using C++. The project is hosted on GitHub.

The library consists of the following files:

  • Rest.cpp: Twilio REST helper
  • TwiML.cpp: TwiML generation helper
  • Utils.cpp: Utils to validate a HTTP request signature: X-Twilio-Signature
  • Examples.cpp: Examples of usage
  • UnitTests.h: Unit tests
  • Makefile: makefile to build the library (requires libcurl and openssl), examples code and unit tests suite.

To build the library just run ‘make’. Run ‘make examples’ to build the examples and run ‘make unittests’ to build the unit tests suite and run it. When using the library, don’t forget to include Utils.h, Rest.h and TwiML.h at the top of your source code and to use the twilio namespace: “using namespace twilio;”.

Laurent put together the following code examples based on a restaurant dish recommendation service using SMS for communication. For all of the examples, we are going to use the C++ std namespace: “using namespace std;” and define the following constants:

// Twilio REST API version
const string API_VERSION = "2010-04-01";
// Twilio Account Sid
const string ACCOUNT_SID = "XXXX";
// Twilio Auth Token
const string ACCOUNT_TOKEN = "XXXX";
// Twilio SMS URL
const string SMS_URL = "http://www.example.com/sms";

Receiving and replying to a SMS asking for a restaurant dish recommendation.

When someone asks for a dish recommendation, he sends a SMS with a text such as “Burger in San Francisco”. Twilio issues a HTTP POST request to your server with the text in the POST parameter “Body”. The URL called is SMS_URL.

First, we need to validate the HTTP POST request to make sure it is coming from a Twilio server. We use the Utils class to help us with that.

Utils utils (ACCOUNT_SID, ACCOUNT_TOKEN);
// vars should contain the POST parameters received. It is a vector of Var structures: key/value.
vector<Var> vars;
vars.push_back(Var("AccountSid", "xxxx"));
vars.push_back(Var("Body", "xxxx"));
// [ add all POST parameters received ]
// signature is the hash we received in the X-Twilio-Signature header
bool valid = utils.validateRequest(signature, SMS_URL, vars);
if(!valid) {
// handle invalid request here
}

Then we need to reply with our dish recommendation. We use the classes TwiMLResponse and Sms to help us generate the XML.

TwiMLResponse response;
// Set SMS text based on what the user asked, which can be found in the "Body" POST parameter.
Sms sms ("Gigantic Burger at Twilio at 501 Folsom St San Francisco");
response.append(sms);  // reply with response.toXML()

response.toXML() returns the following:
<Response>
<Sms>
<![CDATA[Gigantic Burger at Twilio at 501 Folsom St San Francisco]]>
</Sms>
</Response>

Sending a daily recommendation to a list of subscribers using SMS.

We need to issue POST requests using the following URL: /2010-04-01/Accounts/{AccountSid}/SMS/Messages. In the following code, “subscribers” is a vector containing the phone numbers that we need to send to. We use the class Rest to help us send the SMS messages.

Rest rest(ACCOUNT_SID, ACCOUNT_TOKEN);
// Fill up the POST parameters vector
vector<Var> vars;
vars.push_back(Var("From", "xxx-xxx-xxxx"));
vars.push_back(Var("Body", "Deluxe Ramen at Twilio at 501 Folsom St San Francisco"));
vars.push_back(Var("To", ""));
string res;
// Go through the list of subscribers and issue a POST request for each one.
for(unsigned int i = 0; i < subscribers.size(); i++)
{
// vars[2] refers to the "To" parameter
vars[2].value = subscribers[i];
res = rest.request("/" + API_VERSION + "/Accounts/" + ACCOUNT_SID + "/SMS/Messages", "POST", vars);
// "res" contains the XML response returned by the Twilio server
}

Retrieving the list of SMS messages we sent and their status.

We need to issue a GET request using the following URL: /2010-04-01/Accounts/{AccountSid}/SMS/Messages. We use the class Rest to help us with the GET request.

Rest rest(ACCOUNT_SID, ACCOUNT_TOKEN);
// Fill up the GET parameters vector
vector<Var> vars;
vars.push_back(Var("From", "xxx-xxx-xxxx"));
// we can also set "To" and "DateSent" to filter more
string res;
res = rest.request("/" + API_VERSION + "/Accounts/" + ACCOUNT_SID + "/SMS/Messages", "GET", vars);

“res” should contain the list of SMS sent:

<TwilioResponse>
<SMSMessages page="0" numpages="6"...>
<SMSMessage>
<Sid>SM800f449d0399ed014aae2bcc0cc2f2ec</Sid>
<DateCreated>Mon, 10 Dec 2010 03:45:01 +0000</DateCreated>
...
</SMSMessage>
...
</SMSMessages>
</TwilioResponse>

Note that pagination might need to be handled if the number of SMS messages is too large for one HTTP response. See the paging documentation for more details.

There is a lot more you can do using the Twilio C++ library so go ahead and have fun with it. Laurent would love to get your feedback and ideas over on the GitHub project page as well.

Do you have a Twilio API library or other code the community may find useful? We want to hear from you! Let us know in the comments or email help@twilio.com so we can write about it.

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.