Twilio Cloud Communications - Discover Our Web Services API for Making & Receiving Phone Calls & Text Messages, Cloud Telephony

How To Receive SMS Messages Without Responding

When you purchase a new phone number with Twilio, the URL for voice and SMS is not configured so until you set this up you won't be able to receive any incoming messages or calls. But what if you want to receive inbound text messages without sending anything back?

This morning I got a call on the Twilio support line from someone looking to receive inbound SMS messages to his Twilio numbers, without sending any responses back.  To keep things as simple as possible, he just wanted to collect the information sent in via the call logs, and not deal with any complex hosting of his Twilio application.  I realized this is something many customers look to do each day, so I've written up a step-by-step guide on how to configure your application and hosting with Twilio and Dropbox in just 5 minutes.

Creating Your Twilio Application

First, create your "application", which in this case is really just going to be a blank XML file formatted so Twilio will understand it.  We'll call ours sms.xml (make sure you save your file with the ".xml" file extension).  You can write this using any text editor.

sms.xml

<Response>

</Response>

Yep that's right, just two lines of XML is all you need.  This will let Twilio know that it is a legitimate application, but also instruct Twilio not to send any response.

 

Sending a Simple Response Message

 

If you want to send a simple response to each person who messages your Twilio number instead, try this:

sms-response.xml

<Response>

<Sms>Thanks for your message!</Sms>

</Response>

Hosting Static Files with Dropbox

Dropbox is a simple and free solution for hosting static files without having to set up a servier, and in this case we're going to save a simple XML file using TwiML, or Twilio Markup Language.  To get started, create a free Dropbox account.

Once you're account has been created and you're logged into Dropbox, we need to upload the application that you created so that we can get a URL for the file and configure your Twilio number for SMS.  From within your Dropbox account, select the folder called Public.  This is where we will host your application.

Select the "Upload" button and upload the file from your computer.  Once the file is uploaded, it will show up in the Dropbox web UI as one of the files within the Public folder.  Now we need to get the URL for this file so that we can configure your Twilio number.

To get this URL, click on your file in the list and copy the URL from your browser, it should be something like this: https://dl.dropbox.com/u/1234567/sms.xml

Configuring Your Twilio Number for SMS

Now we have a URL for our SMS application, so all we need to do it visit our Twilio.com account and tell Twilio where what to do whenever a text message is received.  

Log into your Twilio account and navigate to the Phone Numbers page, and select "edit" next to the number you wish to update.

 

 

You will see the options to configure voice and SMS applications, so check the box indicating your want to use this number for SMS and paste the URL of your application into the box:

Photo credit: Dougvr6 on Flickr

How To: Port Your Landline to Twilio, Forward to Your Mobile Phone

I read a post today in the Wall Street Journal about how early adopters want to get 212 numbers, one of the earliest area codes in New York City, for their cell phones.  Across the United States there are regions where literally all numbers in an area code have been allocated.  As the logic goes, there is a vanity element to having an older number -- in the case of New York City that number begins with 212.

While these numbers are scarce and coveted by some, they actually aren't unattainable.  They're available for purchase on Ebay, and even occasionally come up for inventory here at Twilio (we've constantly got an open order for more).  But what's the best way to get one?

Take Your Landline Number With You

For many New Yorkers, and people around the world, having a landline phone is becoming less important.  But why give up that awesome number you've had for years when you disconnect your landline service and go completely digital?  You can simply port the number to Twilio, and then forward it to your mobile phone.  Want to give out the 212 to friends, put it on your business card, and then forward to whatever number is on your mobile?  Done, and we'll show you just how easy it is to set up call forwarding in this post as well.

How to Port a Number

Porting a number into Twilio is free, and usually takes 2-3 weeks depending on what carrier you're porting from.

To get started with porting, log into your Twilio account and make sure you've upgraded to a paid account.  Once the number is in, it will cost $1/month to hold onto it, so you'll need some funds to cover that.  Once you're in and have added funds, head over to the phone numbers page and select the "Port a Number" button.

Fill out the porting form and submit it to get things rolling.  Later on, you'll get an email from Twilio asking for a recent phone bill and a signed letter of authorization for us to move your number from your current carrier to Twilio.  At that point, our porting team takes over and moves things along, and gives you updates along the way.

Edit: If you don't have a phone number you want to port, or just want to try out call forwarding first, you can buy U.S. local Twilio numbers for just a dollar a month, and when you upgrade to a paid account and put in $20, you keep your $30 free trial as well. 

How to Configure Call Forwarding

Once you've got your number ported to Twilio, you'll probably want to set it up to receive inbound calls and forward them to your mobile phone.  There are several ways to do this:

• * code up a call forwarding application of your own using TwiML
• * configure a simple hosted call forwarding app or "Twimlet" from Twilio Labs
• * set up a call forwarding flow using Twilio's OpenVBX drag-and-drop interface

Building Your Own App

It's literally 3 lines of XML, hosted on your server and publicly accessible with a URL that you can use to configure your Twilio number. You might just try using a public Dropbox, since its a static file.

forwardcall.xml

<Response>

<Dial>415-390-2337</Dial>

</Response>

Setting Up the Call Forwarding Twimlet

Twimlets are simple stateless applications hosted by Twilio.  Multiple Twimlets can be chained together to create sophisticated apps (great for rapid prototyping), and the Forward Twimlet is a simple app you can use to send incoming calls to your Twilio out to your mobile phone.

In this example, I'm going to forward calls to my Twilio number on to the Twilio company phone, but you can do this with any number you wish.  Each Twimlet comes with a simple URL generator, just fill out the form and copy the URL it creates.

You'll paste this URL into the voice application box next to your Twilio number.

Configuring Call Forwarding Using OpenVBX

We recently launched an open source project called OpenVBX, which provides a simple drag-and-drop user interface for building voice applications.  I think of it kind of like self-hosted Wordpress, for the phone.  To use it, you'll need a hosting environment that runs PHP... or you can take advantage of one-click installs from Dreamhost or Standing Cloud to make things super easy.

To set up call forwarding, add a new call flow and use the Dial applet to connect incoming calls to your Twilio number to your mobile phone, like this:

 

Photo credit: Flickr

Twilio Starter Kit for the Zend Framework by Michael Kimsal

Thank you to Michael Kimsal, who created a starter kit for developers using Twilio with the Zend Framework for PHP.  As he announced on the Twilio Developers Network on LinkedIn:

I was putting together some sample code for an upcoming presentation, and decided building it on top of zfkit made it possibly a bit more understandable to people looking to integrate twilio with a framework like ZF in the first place. 

It's pretty basic, but please have at it forking and contributing back :)

Download the kit on Github

Thanks Michael, and happy forking!

-----

Have you open sourced something that would benefit other Twilio developers?  Let us know and we'll help spread the word.  Drop a note to help@twilio.com, or send a message to us on Twitter.

.NET Twilio Server Library by Tony Gravagno

 We're fortunate at Twilio to have an amazing community of developers that openly share their work for the rest of the community to benefit from. One such developer is Tony Gravagno, President of Nebula Research and Development. Tony does a lot of work with .NET and wanted to simplify working with the Twilio APIs. Existing open source options were incomplete so Tony started work on Twilio Server Library (or TSL.NET for short).

TSL.NET covers both major use cases for working with Twilio: the REST API and TwiML responses. Lets take a look at a couple examples of how the library works.

REST API

With complete coverage of the Twilio REST API, TSL.NET makes sending a text message as easy as two lines of code:

var twilio = new TwilioRestClient("AC12345", "authTokenGoesHere");
var message = twilio.SendSMS("555-111-2222", "555-333-4444", "SMS from TSL.NET", "http://example.com/callback");

You can also easily initiate a call:

var twilio = new TwilioRestClient("AC12345", "authTokenGoesHere");
var call = twilio.PlaceCall("555-111-2222", "555-333-4444", "http://example.com/call");
var callSid = call.Sid;

That's just the beginning of what the TwilioRestClient supports. You can read more about the other features here.

TwiML

TSL.NET originally started out focusing on TwiML generation inspired the PHP Helper Library. These libraries are designed to make it easy to dynamically build TwiML from code. Let's take a look at a simple example.

Let's say we need some TwiML for a simple voicemail app:

<?xml version="1.0" encoding="UTF-8" ?> 
<Response> 
 <Say>Hello, please leave a message.</Say>
 <Record action="record.aspx" maxLength="30" />
</Response>

Generating this can be accomplished with the following C#:

var response = new Response();
response.AddSay("Hello, please leave a message.");
response.AddRecord(new RecordAction("record.aspx"), new RecordMaxLength(30));
response.Respond();
var xml = response.Xml;

If you're using Webforms, you can return that string using Response.Write from your generic handler or codebehind (just make sure you set the Response.ContentType = "application/xml"). If you're using ASP.NET MVC, you can return the XML from a controller action.

Nesting of verbs is also supported. For instance to nest a <Say> verb inside a <Gather<>

var response = new Response();
var gather = new Gather(new GatherAction("digits.aspx"), new GatherNumDigits(5));
var say = new Say("Hello, please enter your five digit zip code.");
gather.Append(say);
response.Append(gather);
response.Respond();
var xml = response.Xml;

Tony has done a great job of providing complete coverage for both the REST API and TwiML making it extremely easy to get started building your Twilio-based application, or integrating voice and SMS functionality into existing .NET applications. To learn more about the project, visit the project home page on CodePlex, check out the documentation or download the latest version and play with some of the included examples.

New CakePHP Twilio Datasource from Aaron Reisman

Aaron Reisman is a Media Specialist and Founder of Life is Content. While working on some Twilio projects Aaron developed a new CakePHP Datasource for accessing the Twilio API via standard model functions. The source code is freely available on GitHub. Let's take a look at an example of how it works.

You'll need PHP 5.x and CakePHP 1.3.x to use the datasource. Once you have that setup, installation is three easy steps:

1. Download and add the files to a new CakePHP Project.
2. Edit the database file and use your credentials.
3. Modify the texts controller to your needs.

Once configured, a sample controller might look like this:

<?php 
class TextsController extends AppController { 
    function index(){ 
		// Will use the username defined in the $twitter as shown above:
		$texts = $this->Text->find('all');
		// Create a new text (sends an SMS message)
		//$texts = $this->Text->save(array('To' => 4157175170, 'From' => 4152360978, 'Body' => 'This is an update'));
		// Finds texts by another username
		//$conditions= array('AccountSid' => 'AccountSid');
		//$otherTexts = $this->Text->find('all', compact('conditions'));
		debug($texts);
	} 
} 
?>		
	

If you use CakePHP, the Twilio Datasource can simplify working with the Twilio API. Head on over to GitHub, download it and give it a try in your apps!

twilio_mime makes returning TwiML in Rails even easier

Dale Cook is a Ruby programmer that was looking for an easier way to send back TwiML is his Rails applications. Like any good programmer seeking a better way to do things, Dale built a Rails plugin to take advantage of the framework's 'respond_to' feature. Using twilio_mime you can respond to Twilio requests using TwiML in the same way you'd handle other mime types.

An example of how this works is available in the project's readme file on GitHub. We start with the 'show' action of our sample 'Posts' controller:

def show
 @posts = Post.find :all

 respond_to do |format|
  format.html
  format.twiml
  format.xml { render :xml => @posts.to_xml }
 end
end

Then, create a view to generate the TwiML response called 'show.twiml.erb':

<?xml version="1.0" encoding="UTF-8" ?>
<Response>
 <% @posts.each do |post| %>
  <Say><%= post.title %></Say>
 <% end %>
</Response>		

To keep up with the project and read more of Dale's musings on Ruby, check out his Ruby blog called Little Shards of Ruby. twilio_mime has an MIT license and can be found on GitHub. Go check it out!

Photo credit: Carosaurus on Flickr

Managing Phone Numbers Using Twilio's REST API

For TechCrunch Disrupt going on this week in New York, Twilio was tasked with building an application that would allow attendees to vote on Startup Battlefield participants. To eliminate cheating or ballot stuffing we decided to give all 2000 attendees their own phone number to text to for voting. This limited voting to only those in attendance. 

We'll go into more detail about why we did it this way in a future post but this requirement highlighted an interesting use case: how do you quickly provision 2000 phone numbers for your app? The answer is the Twilio REST API.

Adding Numbers to Your Account via the REST API

If you're familiar with making calls via the REST API adding a phone number to your account follows a similar process. You add numbers to your account by making a POST request to either the Local or Toll-free LocalIncomingNumber resource. You can specify which area code you'd like a number for, the voice and SMS URLs and a variety of other options. These API methods are only available for full accounts so if you have a trial account you'll need to upgrade before you can do this.

For this example I'll be using the Twilio PHP Helper Library to make things even easier. Let's start by adding a local number to our account in the 415 area code.

<?php
 // Include the PHP TwilioRest library 
 require "twilio.php";
 
 // Set our AccountSid and AuthToken 
 $AccountSid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
 $AuthToken = "YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY";

 $data = array(
  "AreaCode" => "415", 	 
  "Url" => "http://example.com/voice",
  "SmsUrl" => "http://example.com/sms"
 ); 
 
 $response = $client->request("/2008-08-01/Accounts/$AccountSid/IncomingPhoneNumbers/Local", 
   "POST", $data); 
 
 // check response for success or error
 if($response->IsError)
  echo "No phone numbers available: {$response->ErrorMessage}\n";
 else
  echo "Phone number added: {$response->ResponseXml->IncomingPhoneNumber->PhoneNumber}\n";
?>

It's very important to check for errors when adding numbers. If Twilio doesn't have any phone numbers available in the area code requested you will receive an HTTP Status Code 400 back from the API. If you don't care which area code your number is in, just omit that parameter and we'll give you a number from somewhere in the US.

Retrieving Your Numbers

For Startup Battlefield we needed to print each of the 2000 numbers we created on a card to give to attendees. Thankfully the Twilio REST API provides an easy way to get a CSV (comma-separated values) file for any resource. To download a CSV of all your phone numbers, we constructed the proper URL and entered in our web browser (replace ACXXXXX with your Account SID).

 https://api.twilio.com/2008-08-01/Accounts/ACXXXXX/IncomingPhoneNumbers/Local.csv

When accessing this URL in your browser, you will be prompted for a username and password. Use your Account SID for the username and Auth Token for the password. If you omit the '.csv' at the end you'll get back a regular XML response that includes paging information. Since we just needed a file we could use in a mail merge, we went with the simpler CSV representation. You can learn more about alternate representations in the Tips & Tricks section of our docs.

More to Come

We'll be doing a complete write up of the Startup Battlefield voting app in the coming days. We'll cover the unique requirements of the app and how we went about building it. Stay tuned!

Touch Tone Telephony Control for Arduino

When someone takes Twilio technology and combines it with other geeky goodness, and then rolls all that into a blog post (and video!) its like Christmas morning to see it pass through the RSS reader.  Although this post is from over a week ago, its possible you haven't yet seen what Chris put together and we'd love to show you how he has used Twilio to enable touch tone controls for Arduino.

Video Demonstration

How It Works

To get a very detailed description of the materials used and steps required, please visit the original blog post.  Here is a brief run-through of how it works:

So... What's It Good For?

As Chris points out in his blog post, DTMF telephony is ubiquitous and one could easily control this device or other electronic devices with a mobile phone from anywhere in the world. Forget to turn of the lights or shut the garage door? In the future, you might be able to check them and change them using your phone.

Some readers might remember our developer contest category for Twilio integration with real-world devices awhile back.  David Bello built an application to turn on and off a light in his home using his telephone.  Read more here...

Extending Click-to-Call to Simultaneously Call Multiple Numbers

Did you know Twilio has an exhaustive list of HowTos and Example Code? Whether you're new to Twilio, or just looking to get a jump start on your latest project, this is a great place to see some how some of the most common use cases are actually built. I like to think of it as the Twilio Cookbook full of tasty recipes for you to try at home!

Simultaneously Call Multiple Numbers with Click-to-Call

Click-to-call is one of our most popular examples. With click-to-call you can allow visitors to your web site call you directly with a couple clicks. The process usually goes like this: the visitor enters their phone number on the web site and submits the form, a call is initiated to the visitor, once they answer the phone another call is initiated to the company and the two ends are connected.

Instead of having the application just call one number, what if we wanted to have it dial 5, 10, or more numbers simultaneously and let the first person who answers take care of the call? If no one answers after a short period of time, we'll prompt the caller to record a message. In this post I'll start with the existing click-to-call example and update it to support dialing multiple numbers simultaneously.

Key Changes in This Example

This example will update the current click-to-call example in a few key places:

1. After the visitor submits the form our application will call them first instead of calling the agent first.
2. Once the visitor answers the phone we will play a short message indicating that we are connecting their call.
3. After the message we'll use Twilio's simultaneous dial technique to connect the visitor to an agent.
4. If no agents respond after 30 seconds we'll prompt the caller to record a message.

Starting the Call

We'll start by adding a form to our HTML to collect the visitor's phone number.

<h3>Please enter your phone number, and you will be connected to an agent</h3>
<form action="makecall.php" method="post">
    <span>Your Number: <input type="text" name="called" /></span>
    <input type="submit" value="Connect me!" />
</form>

Once the user presses submit, the form sends the number (via POST) to makecall.php. Makecall.php uses the free Twilio PHP Helper library to call the company's phone number. I've removed some of the error handling in the original example for brevity.

<?php
require "twilio.php";

/* Set our AccountSid and AuthToken */
$AccountSid = "AXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
$AuthToken = "YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY";

/* Outgoing Caller ID you have previously validated with Twilio */
$number = 'NNNNNNNNNN';

/* Outgoing Number you wish to call */
$outgoing = $_REQUEST['called'];

/* Instantiate a new Twilio Rest Client */
$client = new TwilioRestClient($AccountSid, $AuthToken);

/* make Twilio REST request to initiate outgoing call */
$response = $client->request("/2008-08-01/Accounts/$AccountSid/Calls",
    "POST", array(
    "Caller" => $number,
    "Called" => $outgoing,
    "Url" => 'http://example.com/callback.php'
 ));
 
/* redirect back to the main page with CallSid */
$msg = urlencode("Connecting... ".$_REQUEST['called']);
header("Location: index.php?msg=$msg");
?>

Handling the Call Once Connected

At this point the web site visitor's phone will be ringing. When they answer, Twilio will process the TwiML returned from callback.php to direct the call. Again we'll use the Twilio PHP Helper library to generate and output the TwiML.

<?php
    require("twilio.php");
 
    $r = new Response();
    $r->append(new Say("Thank you for calling! Please wait a moment while we connect your call."));
    $d = new Dial(array("timeout" => "30"));
 
    $numbers = array(
         "555-555-1111",
         "555-555-2222",
         "555-555-3333",
         "555-555-4444",
         "555-555-5555",
         "555-555-6666",
         "555-555-7777",
         "555-555-8888",
         "555-555-9999",
    );

    for ($numbers as $number) {
         $d->append(new Number($number));
    }

    $r->append($d);

 // if no one answers, record a message
    $r->append(new Say("We're sorry, no agents were available to take your call. Please leave a message."));
    $r->append(new Record(array("action" => "record.php"));
 
    $r->Respond();
?>

Simultaneous dial isn't the right solution in every situation. You should take care to use simultaneous dial in situations where you know the behavior of the called parties. Keep in mind that the first phone that picks up cancels all the other connections. If you dial an office phone system or a cellphone in airplane mode, it may pick up after a single ring, preventing the other phones from ringing long enough for a human to ever answer.

Photo credit: Chiot's Run on Flickr

Preventing Spam & Fraud with SMS Phone Verification

If you've used a service like Google Calendar that sends out reminders via SMS, you may recall that when you set up your mobile device to receive alerts, the application verified that you were the owner of the device. This is done by sending you a short verification code that you then entered on the web site. Once this process is complete, the application can safely send you alerts knowing that you are the owner of that number. Other applications have used this technique to help prevent spam and fraud as well.

In a previous post we walked through how to build a simple phone verification system that called a user and prompted them to enter in a code over the phone. Here's another take on that concept, this time around we're going to send the code via an SMS text message to their phone and have them type it in their web browser.

Basic Steps

1. User visits verification web page and enters phone number
2. A random verification code is generated and sent to the user's phone number via a text message
3. The web site prompts the user to enter the verification code
4. The code is checked against the one stored in the database and the appropriate response is returned.

Step One: Collect user's phone number

We start by creating an index.php page with two forms, one to collect the phone number, and one to verify the code.

<form id="enter_number">
    <p>Enter your phone number:</p>
    <p><input type="text" name="phone_number" id="phone_number" /></p>
    <p><input type="submit" name="submit" value="Verify" /></p>
</form>

<form id="verify_code" style="display: none;" action="status.php" method="post">
    <p>Sending you a text message with your verification code.</p>
    <p>Once received, enter it here:</p>
    <h1 id="verification_code"><input type="text" name="verification_code" maxlength="6" size="7" /></h1>
    <input type="hidden" value="" id="phone_number2" name="phone_number" />
    <p><input type="submit" value="Verify" /></p>
</form>

Using jQuery we intercept the submission of the first form and show the second one which was initially hidden. At the same time we also copy the phone number value entered into a hidden form field to use later on.

    <script type="text/javascript">
        $(document).ready(function(){
            $("#enter_number").submit(function(e) {
                e.preventDefault();
                initiateSms();
            });
        });

        function initiateSms() {
            $.post("sms.php", { phone_number : $("#phone_number").val() }, 
                    showVerifyForm, 
                    "json");
        }

        function showVerifyForm() {
            $("#phone_number2").val($("#phone_number").val());
            $("#enter_number").fadeOut("fast");
            $("#verify_code").fadeIn();
        }
    </script>

Step Two: Generate code, store it and send it to the user

When the first form is submitted we make a POST request to sms.php which contains our code for generating the random code, saving the code and phone number to our database and sending the text message to the user. We're using the Twilio PHP Helper Library again to make it even easier to send the text message.

<?php
    require("twilio.php");
    require("database.php");

    // require POST request
    if ($_SERVER['REQUEST_METHOD'] != "POST") die;

    // generate "random" 6-digit verification code
    $code = rand(100000, 999999);

    // save verification code in DB with phone number
    // does not check for duplicates like it should
    $number = mysql_real_escape_string($_POST["phone_number"]);
    db(sprintf("INSERT INTO numbers (phone_number, verification_code) VALUES('%s', %d)", $number, $code));

    mysql_close();

    // initiate phone call via Twilio REST API    
    // Set our AccountSid and AuthToken 
    $AccountSid = "ACxxxxxxxxxxxxxxxxxxxxxxx";
    $AuthToken = "xxxxxxxxxxxxxxxxxxxxxxxx";

    // Instantiate a new Twilio Rest Client 
    $client = new TwilioRestClient($AccountSid, $AuthToken);

    // call data
    $data = array(
        "From" => "555-111-2222", // Verified Outgoing Caller ID or Twilio number
        "To" => $number,          // The phone number you wish to dial
        "Body" => "Verification code: $code"
    );

    // send text message
    $response = $client->request("/2008-08-01/Accounts/$AccountSid/SMS/Messages", "POST", $data); 
?>

Steps Three and Four: Collect and validate user-entered code

Now that the user has been sent the text message with the verification code then can enter it in the second form we created above. That form is sent to status.php which checks the database for a match and let's the user know if the verification succeeded or failed.

<?php
    require("database.php");

    // require POST request
    if ($_SERVER['REQUEST_METHOD'] != "POST") die;

    $number = mysql_real_escape_string($_POST["phone_number"]);
    $code = mysql_real_escape_string($_POST["verification_code"]);
    $result = db(sprintf("select * from numbers where phone_number='%s'", $number));

    $msg = "Invalid code. Please try again.";
    if($line = mysql_fetch_array($result, MYSQL_ASSOC)) {
        if ($line["verification_code"] == $code) {
            db(sprintf("UPDATE numbers SET verified = 1 WHERE phone_number = '%s'", $number));
            $msg = "Verified!";
        }
    }

    mysql_close();
    die($msg);
?>

That's it!

SMS text messages are a great way to have your web application reach out and interact with people even when they're not sitting at their computers. With this simple verification technique you can confidently send messages to your users mobile devices knowing the messages are reaching their intended destination.

Download Complete Example

Download Twilio-sms-verification.zip