TwiML™ Message: Twilio's Request

How Twilio Passes Data to Your Application

Twilio makes HTTP requests to your application just like a regular web browser, in the format application/x-www-form-urlencoded. By including parameters and values in its requests, Twilio sends data to your application that you can act upon before responding. You can configure the URLs and HTTP Methods Twilio uses to make its requests via your account portal or using the REST API.

Creating a Twilio Application within your account will allow you to more-easily configure the URLs you want Twilio to request when someone sends a message to one of your phone numbers. Instead of assigning URLs directly to a phone number, you can assign them to an application and then assign that application to the phone number. This will allow you to pass around configuration between phone numbers without having to memorize or copy and paste URLs.

TwiML Message Requests

When Twilio receives a message for one of your Twilio numbers or Channels it makes a synchronous HTTP request to the message URL configured for that number or Channel, and expects to receive TwiML in response. Twilio sends the following parameters with its request as POST parameters or URL query parameters, depending on which HTTP method you've configured:

Request Parameters

Parameter Description
MessageSid A 34 character unique identifier for the message. May be used to later retrieve this message from the REST API.
SmsSid Same value as MessageSid. Deprecated and included for backward compatibility.
AccountSid The 34 character id of the Account this message is associated with.
MessagingServiceSid The 34 character id of the Messaging Service associated to the message.
From The phone number or Channel address that sent this message.
To The phone number or Channel address of the recipient.
Body The text body of the message. Up to 1600 characters long.
NumMedia The number of media items associated with your message

Twilio also sends the following parameters when there is media, such as images, associated with the message:

Parameter Description
MediaContentType{N} The ContentTypes for the Media stored at MediaUrl{N}. The order of MediaContentType{N} matches the order of MediaUrl{N}. If more than one media element is indicated by NumMedia than MediaContentType{N} will be used, where N is the zero-based index of the Media (e.g. MediaContentType0)
MediaUrl{N} A URL referencing the content of the media received in the Message. If more than one media element is indicated by NumMedia than MediaUrl{N} will be used, where N is the zero-based index of the Media (e.g. MediaUrl0)

Twilio also attempts to look up geographic data based on the 'From' and 'To' phone numbers. Twilio sends the following parameters, if available:

Parameter Description
FromCity The city of the sender
FromState The state or province of the sender.
FromZip The postal code of the called sender.
FromCountry The country of the called sender.
ToCity The city of the recipient.
ToState The state or province of the recipient.
ToZip The postal code of the recipient.
ToCountry The country of the recipient.

'STOP' and Opt Out

Twilio will handle opt outs on all long code phone numbers in accordance with industry standards. Opt out keywords are passed to your application to notify you that a user has opt out. All future messages to the user will result in error. 'Start' and 'Yes' keywords will also be passed to your application and to opt users back in.

When a user has opted out of a phone number that belongs to a Messaging Service, the user has also been opted out of receiving all messages sent from that particular Messaging Service.

Data Formats

Phone Numbers

All phone numbers in requests from Twilio are in E.164 format if possible. For example, (415) 555-4345 would come through as '+14155554345'. However, there are occasionally cases where Twilio cannot normalize an incoming caller ID to E.164. In these situations Twilio will report the raw caller ID string.

Dates & Times

All dates and times in requests from Twilio are GMT in RFC 2822 format. For example, 6:13 PM PDT on August 19th, 2010 would be 'Fri, 20 Aug 2010 01:13:42 +0000'

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.