Get Started

TwiMLTM Message: <Message>

The <Message> verb sends a message to a phone number.

Verb Attributes

The <Message> 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

to

The 'to' attribute takes a valid phone number as an argument. Twilio will send the message to the number provided. If no 'to' attribute is provided, Twilio will send the message as a reply to the current sender.

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 have a trial account, the 'to' phone number must be verified with Twilio. But you don't need to specify the 'to' attribute to just send a message reply to the current sender.

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 a message in response to an incoming message, 'from' defaults to the Twilio number that received the message. If you specify a 'from' value, it must be a message-capable local phone number assigned to your account. If the phone number isn't message-capable, then <Message> will not send a message.

action

The 'action' attribute takes a URL as an argument. After processing the <Message> verb, Twilio will make a GET or POST request to this URL with the form parameters 'MessageStatus' and 'MessageSid'. 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 Message session. Any TwiML Message verbs occuring after a <Message> which specifies an 'action' attribute are unreachable.

If no 'action' is provided, <Message> will finish and Twilio will move on to the next TwiML Message verb in the document. If there is no next verb, Twilio will end the Message session. Note that <Message> 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 MessageStatus parameter in addition to the standard TwiML Message request parameters with its request to the 'action' URL.

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 message is actually sent, or if sending fails, Twilio will make an asynchronous POST request to this URL with the usual TwiML Message request parameters plus the additional parameters below. Note, 'statusCallback' always uses HTTP POST to request the given url.

Request Parameters

Twilio will pass the MessageStatus parameter in addition to the standard TwiML Message request parameters with its request to the 'statusCallback' URL.

MessageStatus parameter

The MessageStatus parameter is sent with requests to the action URL or to the statusCallback URL. The parameter contains more information about the status of the message - whether it was successfully sent, or whether delivery failed (the number was invalid, or there was no message body, etc.)

Parameter Description
MessageStatus The current status of the message. Either queued, sending, 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 <Message>:

Noun Description
plain text The text of the message you want to send. Must be less than 1600 characters.
<Body> The text of the message you want to send. Must be less than 1600 characters. If more than one <Body> element is used in a single <Message> the contents of the two will be concatenated together into a single Body value.
<Media> A nested XML element that indicates the URL of a image to be sent in the message. If you wish to send more than one image please include more than one <Media> element. The maximum number of <Media> that can be included in a given message is 10.

See Also

Want to send a message without waiting for an inbound message? See our outbound message documentation.

Examples

Example 1: Simple sending of SMS

This is the simplest case for <Message>. Twilio sends an SMS with the location of your wonderful retail establishment.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Message>Store Location: 123 Easy St.</Message>
</Response>

Example 2: Sending of an Message with Media (MMS)

To add a picture to the message, you can specify a URL with the Media noun. You can also enclose the body in the Body noun. If you specify one or more Media nouns, the Body is optional.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Message>
        <Body>Store Location: 123 Easy St.</Body>
        <Media>https://demo.twilio.com/owl.png</Media>
    </Message>
</Response>

Example 3: MessageStatus reporting

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 'MessageStatus'. If the messages is queued and waiting to be sent, 'MessageStatus' will have the value 'sending'. If an invalid attribute was provided, then 'MessageStatus' will be 'invalid'.

Your web application can look at the 'MessageStatus' parameter and decide what TwiML to return.

If an 'action' URL is provided for <Message>, 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>
    <Message action="/SmsHandler.php" method="POST">Store Location: 123 Easy St.</Message>
</Response>

Example 4: 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 'MessageStatus'. If the messages was successfully sent, 'MessageStatus' will be 'sent'. If the message failed to send, 'MessageStatus' will be 'failed'.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Message statusCallback="/SMSHandler.php">Store Location: 123 Easy St.</Message>
</Response>

Nesting Rules

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

Nest nouns inside a verb like so:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Message>Hello Jenny
        <Media>https://demo.twilio.com/owl.jpg
        </Media>
    </Message>
</Response>