<Sms>The <Sms> verb sends an SMS message to a phone number.
The <Sms> verb supports the following attributes that modify its behavior:
| Attribute Name | Allowed Values | Default Value |
|---|---|---|
| to | phone number | see below |
| from | phone number | see below |
| action | relative or absolute URL | none |
| method | GET, POST | POST |
| statusCallback | relative or absolute URL | none |
The 'to' attribute takes a valid phone number as an argument. Twilio will send the SMS to the number provided. If no 'to' attribute is provided, Twilio will send the SMS as a reply to the current sender.
Phone numbers should be formatted with a '+' and country code e.g.,
+16175551212 (E.164 format). Twilio will also accept unformatted US
numbers e.g., (415) 555-1212 or 415-555-1212.
The 'from' attribute takes a valid phone number as an argument. This number must be a phone number that you've purchased from or ported to Twilio.
When sending an SMS in response to an incoming SMS, 'from' defaults to the
Twilio number that received the message. If you specify a 'from' value, it must
be an SMS-capable local phone number assigned to your account. If the phone
number isn't SMS-capable, then <Sms> will not send an SMS message.
The 'action' attribute takes a URL as an argument. After processing the <Sms> verb,
Twilio will make a GET or POST request to this URL with the form parameters 'SmsStatus' and 'SmsSid'. Using an 'action' URL,
your application can receive synchronous notification that the message was successfully enqueued.
If you provide an 'action' URL, Twilio will use the TwiML received in your response to the 'action' URL request to continue the current TwiML SMS session. Any TwiML SMS verbs occuring after an <Sms> which
specifies an 'action' attribute are unreachable.
If no 'action' is provided, <Sms> will finish and Twilio will move on to the next TwiML SMS verb
in the document. If there is no next verb, Twilio will end the SMS session.
Note that <Sms> does not make a request to the current document's URL by default if no 'action' URL is provided.
Twilio will pass the following parameters in addition to the standard TwiML SMS request parameters with its request to the 'action' URL:
| Parameter | Description |
|---|---|
| SmsStatus | The current status of the SMS message. This is usually 'sending'. But if you provide an invalid number, this is 'invalid'. |
The 'method' attribute takes the value 'GET' or 'POST'. This tells Twilio whether to request the 'action' URL via HTTP GET or POST. This attribute is modeled after the HTML form 'method' attribute. 'POST' is the default value.
The 'statusCallback' attribute takes a URL as an argument. When the SMS message is actually sent, or if sending fails, Twilio will make a POST request to this URL with the usual TwiML SMS request parameters plus the additional parameters below. Note, 'statusCallback' always uses HTTP POST to request the given url.
Twilio will pass the following parameters in addition to the standard TwiML SMS request parameters with its request to the 'statusCallback' URL:
| Parameter | Description |
|---|---|
| SmsStatus | The current status of the Sms message. Either 'sent' or 'failed' |
The "noun" of a TwiML verb is the stuff nested within the verb that's not a verb itself; it's the stuff the verb acts upon. These are the nouns for <Sms>:
| Noun | Description |
|---|---|
| plain text | The text of the SMS message you want to send. Must be less than 160 characters. |
You can't nest any verbs within <Sms> and you can't nest <Sms> in any other verbs.
Twilio SMS Messages REST Resource
This is the simplest case for <Sms>. Twilio sends an SMS with the location of your wonderful retail establishment.
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Sms>Store Location: 123 Easy St.</Sms>
</Response>
In this use case, we have provided 'action' URL and 'method' attributes. Now when the message is queued for delivery, Twilio will request the 'action' URL passing the parameter 'SmsStatus'. If the messages is queued and waiting to be sent, 'SmsStatus' will have the value 'sending'. If an invalid attribute was provided, then 'SmsStatus' will be 'invalid'.
Your web application can look at the 'SmsStatus' parameter and decide what TwiML to return.
If an 'action' URL is provided for <Sms>, flow of your application will continue with the TwiML received in response to the 'action' request.
All verbs remaining in the document will be unreachable and ignored.
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Sms action="/SmsHandler.php" method="POST">Store Location: 123 Easy St.</Sms>
</Response>
In this example we provide a 'statusCallback' URL. When the message is finished sending (not just enqueued), Twilio will asynchronously request the 'statusCallback' URL with the parameter 'SmsStatus'. If the messages was successfully sent, 'SmsStatus' will be 'sent'. If the message failed to send, 'SmsStatus' will be 'failed'.
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Sms statusCallback="/SMSHandler.php">Store Location: 123 Easy St.</Sms>
</Response>