This document describes Twilio's old 2008-08-01 API. See what we added in our latest revision: changelog.

Receiving a Twilio SMS Request

Your SMS-enabled incoming phone numbers will have a callback-url specified, so that if somebody SMS your phone number, Twilio will consult your URL with the Sid, From, To, and Body of the message. You can easily respond to the SMS by returning a text/plain or TwiML response to Twilio.

How Twilio Passes Data to Your Application

Twilio sends data to your application using either an HTTP POST or GET.

HTTP POST Variables

When an SMS is received by Twilio, we will perform an HTTP request to your webserver. The following fields will be sent (via POST, or via URL query parameters, depending on which HTTP method you've chosen):

SMS Request
SmsSidA 34 character unique identifier for the message. May be used to later retrieve this message from the REST API
AccountSidThe 34 character id of the [Account][account] this Message is associated with. (Your account!)
FromThe phone number that sent this message
ToThe phone number of the recipient
BodyThe text body of the SMS message. Up to 160 characters long.

Twilio also attempts to look up geographic data based on the caller and called phone numbers. The following fields are sent, if available:

FromCityThe city of the sender
FromStateThe state or province of the sender.
FromZipThe postal code of the called sender.
FromCountryThe country of the called sender.
ToCityThe city of the recipient.
ToStateThe state or province of the recipient.
ToZipThe postal code of the recipient.
ToCountryThe country of the recipient.

HTTP GET Variables

If you use HTTP GET instead of POST, Twilio passes metadata about the call as URL query string parameters. The names and behavior are the same as those values passed in a POST. Here's an example query string with the above parameters: