REST API: Sending SMS Messages

Since initiating outbound SMS messages via the REST API is such a frequent task, it get its own section. Huzza!

HTTP POST to SMS/Messages

To send a new outgoing SMS message, make an HTTP POST to your SMS/Messages list resource URI:

/2010-04-01/Accounts/{AccountSid}/SMS/Messages

POST Parameters

Required Parameters

The following parameters are required in your POST to send the SMS:

Parameter Description
From A Twilio phone number enabled for SMS. Only phone numbers or short codes purchased from Twilio work here; you cannot (for example) spoof SMS messages from your own cell phone number. If you haven't purchased a Twilio number yet you can use the Sandbox Number to send SMS to verified numbers.
To The destination phone number. Format with a '+' and country code e.g., +16175551212 (E.164 format). Twilio will also accept unformatted US numbers e.g., (415) 555-1212, 415-555-1212.
Body The text of the message you want to send, limited to 160 characters.
Note that if you are sending SMS from the Twilio Sandbox Number, the 'To' phone number must be verified with Twilio. You must also include your Sandbox PIN (found in your Dashboard).
Optional Parameters

You may include the following parameters:

Parameter Description
StatusCallback A URL that Twilio will POST to when your message is processed. Twilio will POST the SmsSid as well as SmsStatus=sent or SmsStatus=failed.
ApplicationSid Twilio will POST SmsSid as well as SmsStatus=sent or SmsStatus=failed to the URL in the SmsStatusCallback property of this Application. If the StatusCallback parameter above is also passed, the Application's SmsStatusCallback parameter will take precedence.

Example

Send an SMS from 415-814-1829 to 415-935-2345 begging Jenny for a second chance:

Try it now

  • POST /2010-04-01/Accounts/AC5ef87.../SMS/Messages.Xml

    From=+14158141829&To=+14159352345&Body=Jenny%20please%3F%21%20I%20love%20you%20%3C3

    <TwilioResponse>
    <SMSMessage>
        <Sid>SM90c6fc909d8504d45ecdb3a3d5b3556e</Sid>
        <DateCreated>Wed, 18 Aug 2010 20:01:40 +0000</DateCreated>
        <DateUpdated>Wed, 18 Aug 2010 20:01:40 +0000</DateUpdated>
        <DateSent/>
        <AccountSid>AC5ef872f6da5a21de157d80997a64bd33</AccountSid>
        <To>+14159352345</To>
        <From>+14158141829</From>
        <Body>Jenny please?! I love you &lt;3</Body>
        <Status>queued</Status>
        <Direction>outbound-api</Direction>
        <ApiVersion>2010-04-01</ApiVersion>
        <Price/>
        <Uri>/2010-04-01/Accounts/AC5ef872f6da5a21de157d80997a64bd33/SMS/Messages/SM90c6fc909d8504d45ecdb3a3d5b3556e</Uri>
    </SMSMessage>
</TwilioResponse>

Handling SMS Replies

By specifying an SMS URL for your SMS enabled Twilio phone number, Twilio will make a request to your application to notify you when someone replies to a message you send. Twilio's request and your corresponding response are covered in the SMS portion of the TwiML documentation.

Helper Libraries for Java, Python, C#, Ruby, and PHP

This page explains the format for raw HTTP calls to the Twilio API. We also have helper libraries in a number of popular programming languages, which make it easy for you to get started with Twilio.