TwiML™ Voice: <Sms>

The <Sms> TwiML verb is deprecated.

To reply to incoming text messages with another text message, use the <Message> verb. To send a text message in response to an incoming phone call, use a webhook to trigger your own application code and use the REST API to send a text message.

The <Sms> verb sends an SMS message to a phone number during a phone call.

Verb Attributes

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

Use one or more of these attributes in a <Sms> verb like so:

Loading Code Samples...
Language
SDK Version:
  • 5.x
SDK Version:
  • 7.x
SDK Version:
  • 3.x
SDK Version:
  • 5.x
SDK Version:
  • 6.x
SDK Version:
  • 5.x
Format:
  • TwiML
const VoiceResponse = require('twilio').twiml.VoiceResponse;

const response = new VoiceResponse();
response.sms(
  {
    from: '+14105551234',
    to: '+14105556789',
  },
  'The king stay the king.'
);

console.log(response.toString());
using Twilio.TwiML;
using System;


class Example
{
    static void Main()
    {
        var response = new VoiceResponse();
        response.Sms("The king stay the king.", from: "+14105551234",
            to: "+14105556789");

        Console.WriteLine(response.ToString());;
    }
}
<?php
require_once './vendor/autoload.php';
use Twilio\TwiML;

$response = new TwiML();
$response->sms('The king stay the king.', ['from' => '+14105551234',
    'to' => '+14105556789']);

echo $response;
require 'twilio-ruby'

response = Twilio::TwiML::VoiceResponse.new
response.sms('The king stay the king.', from: '+14105551234',
                                        to: '+14105556789')

puts response
from twilio.twiml.voice_response import VoiceResponse, Sms

response = VoiceResponse()
response.sms(
    'The king stay the king.', to='+14105556789', from_='+14105551234'
)

print(response)
import com.twilio.twiml.VoiceResponse;
import com.twilio.twiml.voice.Sms;
import com.twilio.twiml.TwiMLException;


public class Example {
    public static void main(String[] args) {
        Sms sms = new Sms.Builder("The king stay the king.")
            .from("+14105551234").to("+14105556789").build();
        VoiceResponse response = new VoiceResponse.Builder().sms(sms).build();

        try {
            System.out.println(response.toXml());
        } catch (TwiMLException e) {
            e.printStackTrace();
        }
    }
}
<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Sms from="+14105551234" to="+14105556789">The king stay the king.</Sms>
</Response>
Using the SMS verb

to

The 'to' attribute takes a valid phone number as a value. Twilio will send an SMS message to this number.

When sending an SMS during an incoming call, 'to' defaults to the caller. When sending an SMS during 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.

Phone numbers should be formatted with a '+' and country code e.g., +16175551212 (E.164 format). For 'to' numbers without a '+', Twilio will use the same country code as the 'from' number. Twilio will also attempt to handle locally formatted numbers for that country code (e.g. (415) 555-1212 for US, 07400123456 for GB). If you are sending to a different country than the 'from' number, you must include a '+' and the country code to ensure proper delivery.

If you are sending an SMS from a trial account, the 'to' phone number must be verified with Twilio.

from

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 during an incoming call, 'from' defaults to the called party. When sending an SMS during an outgoing call, 'from' defaults to the calling party. This number must be an SMS-enabled phone number assigned to your account. If the phone number isn't SMS-enabled, then the <Sms> verb will not send an SMS message.

action

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 call. Any TwiML verbs occurring 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 verb in the document. If there is no next verb, Twilio will end the phone call. Note that this is different from the behavior of <Record> and <Gather>. <Sms> does not make a request to the current document's URL by default if no 'action' URL is provided.

Request Parameters

Twilio will pass the following parameters in addition to the standard TwiML Voice request parameters with its request to the 'action' URL:

Parameter Description
SmsSid The Sid Twilio has assigned for the SMS message.
SmsStatus The current status of the SMS message. This is usually 'sending'. But if you provide an invalid number, this is 'invalid'.

method

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.

statusCallback

The 'statusCallback' attribute takes a URL as an argument. When the SMS message is actually sent, or if sending fails, Twilio will make an asynchronous POST request to this URL with the parameters 'SmsStatus' and 'SmsSid'. Note, 'statusCallback' always uses HTTP POST to request the given url.

Request Parameters

Twilio will pass the following parameters in addition to the standard TwiML Voice request parameters with its request to the 'statusCallback' URL:

Parameter Description
SmsSid The Sid for the Sms message
SmsStatus The current status of the Sms message. Either 'sent' or 'failed'

Nouns

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.

Nesting Rules

You can't nest any verbs within <Sms> and you can't nest <Sms> in any other verbs.

See Also

Want to send an SMS without waiting for an inbound call? See our outbound SMS documentation.

Examples

Example 1: Simple SMS sending

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.

Loading Code Samples...
Language
SDK Version:
  • 5.x
SDK Version:
  • 7.x
SDK Version:
  • 3.x
SDK Version:
  • 5.x
SDK Version:
  • 6.x
SDK Version:
  • 5.x
Format:
  • TwiML
const VoiceResponse = require('twilio').twiml.VoiceResponse;

const response = new VoiceResponse();
response.say('Our store is located at 123 Easy St.');
response.sms('Store Location: 123 Easy St.');

console.log(response.toString());
using Twilio.TwiML;
using System;


class Example
{
    static void Main()
    {
        var response = new VoiceResponse();
        response.Say("Our store is located at 123 Easy St.");
        response.Sms("Store Location: 123 Easy St.");

        Console.WriteLine(response.ToString());;
    }
}
<?php
require_once './vendor/autoload.php';
use Twilio\TwiML;

$response = new TwiML();
$response->say('Our store is located at 123 Easy St.');
$response->sms('Store Location: 123 Easy St.');

echo $response;
require 'twilio-ruby'

response = Twilio::TwiML::VoiceResponse.new
response.say('Our store is located at 123 Easy St.')
response.sms('Store Location: 123 Easy St.')

puts response
from twilio.twiml.voice_response import VoiceResponse, Say, Sms

response = VoiceResponse()
response.say('Our store is located at 123 Easy St.')
response.sms('Store Location: 123 Easy St.')

print(response)
import com.twilio.twiml.VoiceResponse;
import com.twilio.twiml.voice.Say;
import com.twilio.twiml.voice.Sms;
import com.twilio.twiml.TwiMLException;


public class Example {
    public static void main(String[] args) {
        Say say = new Say.Builder("Our store is located at 123 Easy St.")
            .build();
        Sms sms = new Sms.Builder("Store Location: 123 Easy St.").build();
        VoiceResponse response = new VoiceResponse.Builder().say(say).sms(sms)
            .build();

        try {
            System.out.println(response.toXml());
        } catch (TwiMLException e) {
            e.printStackTrace();
        }
    }
}
<?xml version="1.0" encoding="UTF-8"?>
<!-- page located at http://example.com/simple_sms.xml -->
<Response>
    <Say>Our store is located at 123 Easy St.</Say>
    <Sms>Store Location: 123 Easy St.</Sms>
</Response>    
Simple SMS sending

Example 2: SmsStatus reporting

In this use case, we provide 'action' URL and 'method' attributes. Now when the message is queued for delivery, Twilio will make a request to the 'action' URL passing the parameter 'SmsStatus'. If the message 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 to do next.

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 are unreachable and ignored.

Loading Code Samples...
Language
SDK Version:
  • 5.x
SDK Version:
  • 7.x
SDK Version:
  • 3.x
SDK Version:
  • 5.x
SDK Version:
  • 6.x
SDK Version:
  • 5.x
Format:
  • TwiML
const VoiceResponse = require('twilio').twiml.VoiceResponse;

const response = new VoiceResponse();
response.say('Our store is located at 123 Easy St.');
response.sms({
    action: '/smsHandler.php',
    method: 'POST'
}, 'Store Location: 123 Easy St.');

console.log(response.toString());
using Twilio.TwiML;
using Twilio.Http;
using System;

class Example
{
    static void Main()
    {
        var response = new VoiceResponse();
        response.Say("Our store is located at 123 Easy St.");
        response.Sms("Store Location: 123 Easy St.", action: new Uri("/smsHandler.php"),
            method: HttpMethod.Post);

        Console.WriteLine(response.ToString());;
    }
}
<?php
require_once './vendor/autoload.php';
use Twilio\TwiML;

$response = new TwiML();
$response->say('Our store is located at 123 Easy St.');
$response->sms('Store Location: 123 Easy St.', ['action' => '/smsHandler.php',
    'method' => 'POST']);

echo $response;
require 'twilio-ruby'

response = Twilio::TwiML::VoiceResponse.new
response.say('Our store is located at 123 Easy St.')
response.sms('Store Location: 123 Easy St.', action: '/smsHandler.php',
    method: 'POST')

puts response
from twilio.twiml.voice_response import VoiceResponse, Say, Sms

response = VoiceResponse()
response.say('Our store is located at 123 Easy St.')
response.sms(
    'Store Location: 123 Easy St.', action='/smsHandler.php', method='POST'
)

print(response)
import com.twilio.twiml.VoiceResponse;
import com.twilio.twiml.voice.Say;
import com.twilio.twiml.voice.Sms;
import com.twilio.twiml.TwiMLException;
import com.twilio.http.HttpMethod;

public class Example {
    public static void main(String[] args) {
        Say say = new Say.Builder("Our store is located at 123 Easy St.")
            .build();
        Sms sms = new Sms.Builder("Store Location: 123 Easy St.")
            .action("/smsHandler.php").method(HttpMethod.POST).build();
        VoiceResponse response = new VoiceResponse.Builder().say(say).sms(sms)
            .build();

        try {
            System.out.println(response.toXml());
        } catch (TwiMLException e) {
            e.printStackTrace();
        }
    }
}
<?xml version="1.0" encoding="UTF-8"?>
<!-- page located at http://example.com/sms_status.xml -->
<Response>
    <Say>Our store is located at 123 Easy St.</Say>
    <Sms action="/smsHandler.php" method="POST">
        Store Location: 123 Easy St.
    </Sms>
</Response>
SmsStatus reporting

Example 3: statusCallback reporting

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'.

Loading Code Samples...
Language
SDK Version:
  • 5.x
SDK Version:
  • 7.x
SDK Version:
  • 3.x
SDK Version:
  • 5.x
SDK Version:
  • 6.x
SDK Version:
  • 5.x
Format:
  • TwiML
const VoiceResponse = require('twilio').twiml.VoiceResponse;

const response = new VoiceResponse();
response.say('Our store is located at 123 Easy St.');
response.sms({
    statusCallback: '/smsHandler.php'
}, 'Store Location: 123 Easy St.');

console.log(response.toString());
using Twilio.TwiML;
using System;


class Example
{
    static void Main()
    {
        var response = new VoiceResponse();
        response.Say("Our store is located at 123 Easy St.");
        response.Sms("Store Location: 123 Easy St.",
            statusCallback: new Uri("/smsHandler.php"));

        Console.WriteLine(response.ToString());;
    }
}
<?php
require_once './vendor/autoload.php';
use Twilio\TwiML;

$response = new TwiML();
$response->say('Our store is located at 123 Easy St.');
$response->sms('Store Location: 123 Easy St.',
    ['statusCallback' => '/smsHandler.php']);

echo $response;
require 'twilio-ruby'

response = Twilio::TwiML::VoiceResponse.new
response.say('Our store is located at 123 Easy St.')
response.sms('Store Location: 123 Easy St.', status_callback: '/smsHandler.php')

puts response
from twilio.twiml.voice_response import VoiceResponse, Say, Sms

response = VoiceResponse()
response.say('Our store is located at 123 Easy St.')
response.sms('Store Location: 123 Easy St.', status_callback='/smsHandler.php')

print(response)
import com.twilio.twiml.VoiceResponse;
import com.twilio.twiml.voice.Say;
import com.twilio.twiml.voice.Sms;
import com.twilio.twiml.TwiMLException;


public class Example {
    public static void main(String[] args) {
        Say say = new Say.Builder("Our store is located at 123 Easy St.")
            .build();
        Sms sms = new Sms.Builder("Store Location: 123 Easy St.")
            .statusCallback("/smsHandler.php").build();
        VoiceResponse response = new VoiceResponse.Builder().say(say).sms(sms)
            .build();

        try {
            System.out.println(response.toXml());
        } catch (TwiMLException e) {
            e.printStackTrace();
        }
    }
}
<?xml version="1.0" encoding="UTF-8"?>
<!-- page located at http://example.com/sms_status_callback.xml -->
<Response>
    <Say>Our store is located at 123 Easy St.</Say>
    <Sms statusCallback="/smsHandler.php">Store Location: 123 Easy St.</Sms>
</Response>
statusCallback reporting

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.

Loading Code Samples...
SDK Version:
  • 5.x
SDK Version:
  • 7.x
SDK Version:
  • 3.x
SDK Version:
  • 5.x
SDK Version:
  • 6.x
SDK Version:
  • 5.x
Format:
  • TwiML
const VoiceResponse = require('twilio').twiml.VoiceResponse;

const response = new VoiceResponse();
response.sms(
  {
    from: '+14105551234',
    to: '+14105556789',
  },
  'The king stay the king.'
);

console.log(response.toString());
using Twilio.TwiML;
using System;


class Example
{
    static void Main()
    {
        var response = new VoiceResponse();
        response.Sms("The king stay the king.", from: "+14105551234",
            to: "+14105556789");

        Console.WriteLine(response.ToString());;
    }
}
<?php
require_once './vendor/autoload.php';
use Twilio\TwiML;

$response = new TwiML();
$response->sms('The king stay the king.', ['from' => '+14105551234',
    'to' => '+14105556789']);

echo $response;
require 'twilio-ruby'

response = Twilio::TwiML::VoiceResponse.new
response.sms('The king stay the king.', from: '+14105551234',
                                        to: '+14105556789')

puts response
from twilio.twiml.voice_response import VoiceResponse, Sms

response = VoiceResponse()
response.sms(
    'The king stay the king.', to='+14105556789', from_='+14105551234'
)

print(response)
import com.twilio.twiml.VoiceResponse;
import com.twilio.twiml.voice.Sms;
import com.twilio.twiml.TwiMLException;


public class Example {
    public static void main(String[] args) {
        Sms sms = new Sms.Builder("The king stay the king.")
            .from("+14105551234").to("+14105556789").build();
        VoiceResponse response = new VoiceResponse.Builder().sms(sms).build();

        try {
            System.out.println(response.toXml());
        } catch (TwiMLException e) {
            e.printStackTrace();
        }
    }
}
<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Sms from="+14105551234" to="+14105556789">The king stay the king.</Sms>
</Response>
SDK Version:
  • 5.x
SDK Version:
  • 7.x
SDK Version:
  • 3.x
SDK Version:
  • 5.x
SDK Version:
  • 6.x
SDK Version:
  • 5.x
Format:
  • TwiML
const VoiceResponse = require('twilio').twiml.VoiceResponse;

const response = new VoiceResponse();
response.say('Our store is located at 123 Easy St.');
response.sms('Store Location: 123 Easy St.');

console.log(response.toString());
using Twilio.TwiML;
using System;


class Example
{
    static void Main()
    {
        var response = new VoiceResponse();
        response.Say("Our store is located at 123 Easy St.");
        response.Sms("Store Location: 123 Easy St.");

        Console.WriteLine(response.ToString());;
    }
}
<?php
require_once './vendor/autoload.php';
use Twilio\TwiML;

$response = new TwiML();
$response->say('Our store is located at 123 Easy St.');
$response->sms('Store Location: 123 Easy St.');

echo $response;
require 'twilio-ruby'

response = Twilio::TwiML::VoiceResponse.new
response.say('Our store is located at 123 Easy St.')
response.sms('Store Location: 123 Easy St.')

puts response
from twilio.twiml.voice_response import VoiceResponse, Say, Sms

response = VoiceResponse()
response.say('Our store is located at 123 Easy St.')
response.sms('Store Location: 123 Easy St.')

print(response)
import com.twilio.twiml.VoiceResponse;
import com.twilio.twiml.voice.Say;
import com.twilio.twiml.voice.Sms;
import com.twilio.twiml.TwiMLException;


public class Example {
    public static void main(String[] args) {
        Say say = new Say.Builder("Our store is located at 123 Easy St.")
            .build();
        Sms sms = new Sms.Builder("Store Location: 123 Easy St.").build();
        VoiceResponse response = new VoiceResponse.Builder().say(say).sms(sms)
            .build();

        try {
            System.out.println(response.toXml());
        } catch (TwiMLException e) {
            e.printStackTrace();
        }
    }
}
<?xml version="1.0" encoding="UTF-8"?>
<!-- page located at http://example.com/simple_sms.xml -->
<Response>
    <Say>Our store is located at 123 Easy St.</Say>
    <Sms>Store Location: 123 Easy St.</Sms>
</Response>    
SDK Version:
  • 5.x
SDK Version:
  • 7.x
SDK Version:
  • 3.x
SDK Version:
  • 5.x
SDK Version:
  • 6.x
SDK Version:
  • 5.x
Format:
  • TwiML
const VoiceResponse = require('twilio').twiml.VoiceResponse;

const response = new VoiceResponse();
response.say('Our store is located at 123 Easy St.');
response.sms({
    action: '/smsHandler.php',
    method: 'POST'
}, 'Store Location: 123 Easy St.');

console.log(response.toString());
using Twilio.TwiML;
using Twilio.Http;
using System;

class Example
{
    static void Main()
    {
        var response = new VoiceResponse();
        response.Say("Our store is located at 123 Easy St.");
        response.Sms("Store Location: 123 Easy St.", action: new Uri("/smsHandler.php"),
            method: HttpMethod.Post);

        Console.WriteLine(response.ToString());;
    }
}
<?php
require_once './vendor/autoload.php';
use Twilio\TwiML;

$response = new TwiML();
$response->say('Our store is located at 123 Easy St.');
$response->sms('Store Location: 123 Easy St.', ['action' => '/smsHandler.php',
    'method' => 'POST']);

echo $response;
require 'twilio-ruby'

response = Twilio::TwiML::VoiceResponse.new
response.say('Our store is located at 123 Easy St.')
response.sms('Store Location: 123 Easy St.', action: '/smsHandler.php',
    method: 'POST')

puts response
from twilio.twiml.voice_response import VoiceResponse, Say, Sms

response = VoiceResponse()
response.say('Our store is located at 123 Easy St.')
response.sms(
    'Store Location: 123 Easy St.', action='/smsHandler.php', method='POST'
)

print(response)
import com.twilio.twiml.VoiceResponse;
import com.twilio.twiml.voice.Say;
import com.twilio.twiml.voice.Sms;
import com.twilio.twiml.TwiMLException;
import com.twilio.http.HttpMethod;

public class Example {
    public static void main(String[] args) {
        Say say = new Say.Builder("Our store is located at 123 Easy St.")
            .build();
        Sms sms = new Sms.Builder("Store Location: 123 Easy St.")
            .action("/smsHandler.php").method(HttpMethod.POST).build();
        VoiceResponse response = new VoiceResponse.Builder().say(say).sms(sms)
            .build();

        try {
            System.out.println(response.toXml());
        } catch (TwiMLException e) {
            e.printStackTrace();
        }
    }
}
<?xml version="1.0" encoding="UTF-8"?>
<!-- page located at http://example.com/sms_status.xml -->
<Response>
    <Say>Our store is located at 123 Easy St.</Say>
    <Sms action="/smsHandler.php" method="POST">
        Store Location: 123 Easy St.
    </Sms>
</Response>
SDK Version:
  • 5.x
SDK Version:
  • 7.x
SDK Version:
  • 3.x
SDK Version:
  • 5.x
SDK Version:
  • 6.x
SDK Version:
  • 5.x
Format:
  • TwiML
const VoiceResponse = require('twilio').twiml.VoiceResponse;

const response = new VoiceResponse();
response.say('Our store is located at 123 Easy St.');
response.sms({
    statusCallback: '/smsHandler.php'
}, 'Store Location: 123 Easy St.');

console.log(response.toString());
using Twilio.TwiML;
using System;


class Example
{
    static void Main()
    {
        var response = new VoiceResponse();
        response.Say("Our store is located at 123 Easy St.");
        response.Sms("Store Location: 123 Easy St.",
            statusCallback: new Uri("/smsHandler.php"));

        Console.WriteLine(response.ToString());;
    }
}
<?php
require_once './vendor/autoload.php';
use Twilio\TwiML;

$response = new TwiML();
$response->say('Our store is located at 123 Easy St.');
$response->sms('Store Location: 123 Easy St.',
    ['statusCallback' => '/smsHandler.php']);

echo $response;
require 'twilio-ruby'

response = Twilio::TwiML::VoiceResponse.new
response.say('Our store is located at 123 Easy St.')
response.sms('Store Location: 123 Easy St.', status_callback: '/smsHandler.php')

puts response
from twilio.twiml.voice_response import VoiceResponse, Say, Sms

response = VoiceResponse()
response.say('Our store is located at 123 Easy St.')
response.sms('Store Location: 123 Easy St.', status_callback='/smsHandler.php')

print(response)
import com.twilio.twiml.VoiceResponse;
import com.twilio.twiml.voice.Say;
import com.twilio.twiml.voice.Sms;
import com.twilio.twiml.TwiMLException;


public class Example {
    public static void main(String[] args) {
        Say say = new Say.Builder("Our store is located at 123 Easy St.")
            .build();
        Sms sms = new Sms.Builder("Store Location: 123 Easy St.")
            .statusCallback("/smsHandler.php").build();
        VoiceResponse response = new VoiceResponse.Builder().say(say).sms(sms)
            .build();

        try {
            System.out.println(response.toXml());
        } catch (TwiMLException e) {
            e.printStackTrace();
        }
    }
}
<?xml version="1.0" encoding="UTF-8"?>
<!-- page located at http://example.com/sms_status_callback.xml -->
<Response>
    <Say>Our store is located at 123 Easy St.</Say>
    <Sms statusCallback="/smsHandler.php">Store Location: 123 Easy St.</Sms>
</Response>