TwiML™ Message: <Message>

The <Message> verb supports the following attributes that modify its behavior:

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.

For details on sending to a Wireless SIM, see "Messages to the Device" in the Wireless Programmable SMS documentation.

The 'from' attribute takes a valid phone number or alphanumeric sender ID as an argument. If a phone number is used, it must be a number that you've purchased from or ported to Twilio.

Alphanumeric sender IDs can only be used when sending messages to countries where the feature is supported. Alphanumeric sender IDs are limited to 11 characters. Accepted characters include both upper- and lower-case ASCII letters, the digits 0 through 9, and space: [A-Za-z0-9]. The sender ID must represent or be associated with your company brand.

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.

The 'statusCallback' attribute takes a URL as an argument. Like the StatusCallback parameter when sending an outbound message via the REST API, this URL will receive an HTTP request with the status of a message sent in response to an inbound message.

The possible statuses for a message are queued, failed, sent, delivered, or undelivered. Twilio will send the MessageSid along with the other standard request parameters as well as MessageStatus and ErrorCode. Non-relative URLs must contain a valid hostname (underscores are not permitted).

The HTTP method used to make the request is configured in the method property.

The 'action' attribute takes a URL as an argument. Like the StatusCallback parameter when sending an outbound message via the REST API, this URL will receive an HTTP request with the status of a message sent in response to an inbound message.

The possible statuses for a message are queued, failed, sent, delivered, or undelivered. Twilio will send the MessageSid along with the other standard request parameters as well as MessageStatus and ErrorCode. Non-relative URLs must contain a valid hostname (underscores are not permitted).

The HTTP method used to make the request is configured in the method property.

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

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.

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

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

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>:

Here, Twilio sends an SMS with the location of your wonderful retail establishment.

1
const MessagingResponse = require('twilio').twiml.MessagingResponse;
2

3

4
const response = new MessagingResponse();
5
response.message('Store Location: 123 Easy St.');
6

7
console.log(response.toString());

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
    <Message>
4
        Store Location: 123 Easy St.
5
    </Message>
6
</Response>

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.

1
const MessagingResponse = require('twilio').twiml.MessagingResponse;
2

3

4
const response = new MessagingResponse();
5
const message = response.message();
6
message.body('Store Location: 123 Easy St.');
7
message.media('https://demo.twilio.com/owl.png');
8

9
console.log(response.toString());

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

In this use case, the 'action' and 'method' attributes are used. Now when the message is queued for delivery, Twilio will request the 'action' URL passing the parameter 'MessageStatus'. If the messages are 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>, the 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.

1
const MessagingResponse = require('twilio').twiml.MessagingResponse;
2

3

4
const response = new MessagingResponse();
5
response.message({
6
    action: '/SmsHandler.php',
7
    method: 'POST'
8
}, 'Store Location: 123 Easy St.');
9

10
console.log(response.toString());

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
    <Message action="/SmsHandler.php" method="POST">
4
        Store Location: 123 Easy St.
5
    </Message>
6
</Response>

You can't nest any verbs within <Message> and you can't nest <Message> in any other verbs. The only elements that can be nested within a <Message> are the nouns <Body> and <Media>.

Nest nouns inside a <Message> verb like so:

1
const MessagingResponse = require('twilio').twiml.MessagingResponse;
2

3

4
const response = new MessagingResponse();
5
const message = response.message();
6
message.body('Hello friend');
7
message.media('https://demo.twilio.com/owl.png');
8

9
console.log(response.toString());

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
    <Message>
4
        <Body>Hello friend</Body>
5
        <Media>https://demo.twilio.com/owl.png</Media>
6
    </Message>
7
</Response>