The <Sms> verb sends a SMS message to the current caller during a phone call.
The "Noun" of a Twilio verb is the body of the element, the thing the verb
acts upon. In the case of <Sms>, the noun is the SMS text you wish to be
sent.
If an action verb is provided, Twilio will submit the status of the SMS message to
the action URL. If no action is provided, <Sms> will fall through to the next
verb in the document without providing status back. Note: this is different than the
behavior of <Record> and <Gather>. <Sms> does not
submit back to the current document URL if no action is provided. Instead, it continues
executing the next TwiML verb below.
If an action URL attribute is provided, <Sms> will submit the following parameters to your
application on completion of <Sms> execution.
| Parameter | Description |
|---|---|
| SmsSid | The Sid for the Sms message |
| SmsStatus | The current status of the Sms message. Sending, Failed, Received, Sent |
| Value | Description |
|---|---|
| sending | The message is in the process of being sent |
| invalid | Twilio was unable to deliver the message because one or more attributes you provided were not valid |
Twilio SMS Messages Resource - Sending outbound SMS messages
The following optional XML attributes may be used with the <Sms> verb to change 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 pick a default. When sending an Sms on an incoming call, 'to' defaults to the caller. When sending an Sms on an outgoing call, 'to' defaults to the called party. The value of 'to' must be a valid phone number. NOTE: sending to short codes is not currently supported.
Note: If your account is a Free Trial account, the provided 'To' phone number must be validated with Twilio. You can however, send an SMS to any caller without explicitly specifying a 'To' number.
The 'from' attribute takes a valid phone number as an argument. This number must be a phone number that you've
purchased from Twilio. If no 'from' attribute is provided, Twilio will pick a default: When sending an SMS on
an incoming call, 'from' defaults to the called party. When sending an Sms on an outgoing call, 'from' defaults to the calling party.
This number 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>,
Twilio will make a GET or POST request to this URL with the form parameters "SmsStatus" and "SmsSid". Using an 'action,'
your application can receive synchronous feedback as to if the message was successfully enqueued.
If no action is provided, <Sms> will unconditionally move on to the next verb in the document. If there
is no next verb, Twilio will end the phone call.
The method attribute takes the value GET or POST. This tells Twilio whether to submit the action URL as a GET or POST method. 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 message is actually sent, or if sending fails, Twilio will make POST request to this URL with the form parameters 'SmsStatus' and 'SmsSid'. Note, statusCallback always uses HTTP POST to request the given url.
Twilio SMS Messages REST Resource - Using REST to retrieve and send SMS messages
The <Sms> verb can be nested in the following elements:
No elements may be nested within <Sms>
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Say>Our store is located at 123 Easy St.</Say>
<Sms>Store Location: 123 Easy St.</Sms>
</Response>
This is the simplest case for <Sms>. Twilio first tells the caller
where the store is located, and then sends the caller an SMS with the
location as the message.
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Say>Our store is located at 123 Easy St.</Say>
<Sms action="/smsHandler.php" method="POST">Store Location: 123 Easy St.</Sms>
</Response>
In this use case, we have provided an action url and method. Now when the message is queued for delivery, Twilio will submit to the action URL with the parameter 'SmsStatus'. If the messages is queued and waiting to be sent, SmsStatus=sending. If an invalid attribute was provided, then SmsStatus=invalid.
Your web application can look at the SmsStatus parameter and decide what to do next.
If an action URL is provided for <Sms>, flow of your application will continue at that URL.
All verbs remaining in the document will be unreachable and ignored.
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Say>Our store is located at 123 Easy St.</Say>
<Sms statusCallback="/smsHandler.php">Store Location: 123 Easy St.</Sms>
</Response>
In this use case, we have provided a statusCallback url. When the message is finished sending (not just enqueued), Twilio will asynchronously submit to the action URL with the parameter SmsStatus. If the messages was successfully sent, SmsStatus=sent. If the message failed to send, SmsStatus=failed.