electricimp / Twilio

A wrapper class for the Twilio API

Twilio 2.0.0

The Twilio library wraps Twilio’s API for sending and receiving SMS message. To get started with this library, you will need a Twilio developer account.

Once you’ve created your account and set up a Project, note down your Twilio Phone Number, and the project’s Account SID and Auth Token.

To include this library in your project, add #require "Twilio.agent.lib.nut:2.0.0" at the top of your agent code

Class Usage

Constructor: Twilio(AccountSID, AuthToken, TwilioNumber)

To create a new Twilio object, pass in your Account SID, Auth Token and Twilio Phone Number to the constructor.

twilio <- Twilio(TWILIO_SID, TWILIO_AUTH, TWILIO_NUM);

Class Methods

send(numberToSendTo, message[, callback])

This method is used to send an SMS message via Twilio.

An optional callback can be specified: in this case, the message will be sent asynchronously, and the callback will fire when the HTTP request completes. The callback function must have a single parameter into which will be passed an a Squirrel table containing three fields: statuscode, headers and body. If you don’t pass a callback, the library will send the request synchronously and return the table outlined above.

Parameters

Parameter	Data Type	Required?	Description
numberToSendTo	String	Yes	The phone number the SMS should be sent to
message	String	Yes	The body of the SMS
callback	String	No	An optional function called when the message has been transmitted. Default: none

Returns

Table — the response table, or null if a callback was specified.

Example

numberToSendTo <- "15555555555";
message <- "Hello World!";

// Synchronous send
local response = twilio.send(numberToSendTo, message);
server.log(response.statuscode + ": " + response.body);

// Asynchronous send
twilio.send(numberToSendTo, message, function(response) {
    server.log(response.statuscode + ": " + response.body);
});

respond(response, message)

You can respond to Twilio text messages by using this method, which will generate the necessary headers and XML for Twilio to parse your response. You must pass in an impOS HTTPResponse object, which will be used to respond to Twilio. Your agent code will need to set up a suitable handler for incoming HTTP requests from Twilio webhooks that you have set up in your Twilio project. This is demonstrated in the example below.

Parameters

Parameter	Data Type	Required?	Description
response	HTTPResponse object	Yes	A pre-prepared object used to respond to Twilio
message	String	Yes	An SMS message to return to the message source via Twilio

Returns

Table — the response table, or null if a callback was specified.

Example

In this example, we send back a message of "You just said '{original message}'", where {original message} is whatever the user sent to your Twilio phone number. The code uses the HTTPResponse object automatically generated by impOS on receiving an HTTP request.

Before the example will work, you need to configure your Twilio phone number:

• Click on the phone number you would like to configure on the Active Numbers dashboard page.
• Scroll down to Messaging and under A Message Comes In, select Webhook and enter your agent’s URL suffixed with /twilio, then click Save.

// Set up a handler for HTTP requests send to the agent
// NOTE This could alternatively be done using the Rocky library
//      (https://developer.electricimp.com/libraries/utilities/rocky)
http.onrequest(function(request, response) {
    local path = request.path.tolower();
    // The Webhook will be set up to post to '<YOUR_AGENT_URL>/twilio'
    if (path == "/twilio" || path == "/twilio/") {
        // Twilio request handler
        try {
            local data = http.urldecode(request.body);
            twilio.respond(response, "You just said '" + data.Body + "'");
        } catch (err) {
            local message = "Sorry, could not decode the incoming message -- error: " + err;
            twilio.respond(response, message);
        }
    } else {
        // Default request handler
        response.send(200, "OK");
    }
});

License

This library is licensed under the MIT License.