Programmable SMS

Any device connected by a Twilio SIM can send and receive Programmable SMS messages. This requires the device itself to support SMS messaging and the SIM's Rate Plan to have messaging_enabled set to true.

SMS messages to or from a device are programmatically controlled using TwiML.

For machine-to-machine (m2m) SMS, specifically for cloud-to-device and device-to-cloud communications, see the Commands API.

Mobile-originated SMS messages: when a device attempts to send an SMS message, your software will be asked for TwiML to control the routing outcome of the message. See "Messages from the Device".

Mobile-terminated SMS messages: any SMS that arrives to Twilio via an Incoming Phone Number can be routed to a device. See "Messages to the Device".

Messages from the Device

Every time a device attempts to send an SMS message, your server can control the routing outcome using TwiML.

The first step is to set a "SMS Request URL" on the SIM's detail page in the Console. The URL should point to your TwiML, which could be a dynamic application server, a simple static XML file, or a hosted TwiML Bin.

SMS Request URL

Twilio's Request

The HTTP request that retrieves TwiML from your server will conform to the standard SMS TwiML Request schema.

Unlike other SMS TwiML requests, you will see a Twilio SIM Sid in the 'From' parameter:

From=sim:DE467fb57a0cba9641a8208136d42545f8

The To parameter contains the phone number that the device is attempting to send the message to:

To=+14154898625

In the above example, the device, or the person operating the device, is attempting to send an SMS to +14154898625 using the device's standard SMS messaging application.

The message body sent from the device is contained in the Body parameter.

Your Response

Your server must respond using valid TwiML.

In the examples that follow, substitute {{Parameter}} for the value of the HTTP request parameter of the same name in the TwiML request.

<?xml version="1.0" encoding="UTF-8"?>
<!-- deliver the message as intended by the device -->
<Response>
    <Message from="+14154898625" to="{{To}}">{{Body}}</Message>
</Response>

With the power of TwiML at your disposal, there's no reason that you need to route the SMS message exactly as the device has intended.

Using the TwiML below, any time the device attempts to send a message to any phone number, with any message body, the sending device will receive a response saying "Destination unreachable". The original message will not be delivered to its desired recipient.

<?xml version="1.0" encoding="UTF-8"?>
<!-- reject all message sending attempts -->
<Response>
    <Message from="{{To}}" to="{{From}}">Destination unreachable.</Message>
</Response>

Sender ID

When sending a Wireless SMS message from a device to an external party using <Message>, a sender ID must be provided, e.g.: <Message from="+15558675309">. The sender ID can be any SMS-capable Twilio Incoming Phone Number.

TwiML Bin

A quick and simple way to host TwiML is to use TwiML Bin. The example below uses a TwiML Bin to route all SMS Messages coming from the device as the device intended:

Wireless SMS TwiML Bin

Messages to the Device

SMS messages received from the outside world to an IncomingPhoneNumber can be delivered to a device using the <Message> verb with the SIM Sid in its to attribute.

The simplest example of delivering an incoming SMS to a device:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Message to="sim:DE567fb57a0aca9641a8209136d42545f4" from="{{From}}">
         {{Body}}
    </Message>
</Response>

In this scenario, {{From}} must be one of either: the original incoming message Sender ID, or an SMS-capable IncomingPhoneNumber.

Logs and Billing

Logs

Logs for Wireless SMS are found in the global SMS logs section of the Console.

Billing

Most communications workflows that involve a SIM will include two independent SMS messages: one SMS message between Twilio and an external party, and the other between Twilio and the SIM-connected device. The SMS message from Twilio to the external party is billed at standard Twilio Programmable SMS rates, which vary based on the destination country and operator. The other SMS message (between Twilio and the SIM) is billed at the Programmable SMS rate for the United States.

Known Limitations

Non-programmable SMS Messages to the Device

There is a phone number on the SIM known as the MSISDN that is not used by Programmable SMS and that can change if the underlying mobile network operator changes. The presence of the MSISDN means that some (potentially unwanted) SMS Messages may arrive straight to your SIM without routing via Twilio. In these cases, Twilio cannot yet offer programmatic control over the SMS Messages, and you won't see them in your Twilio SMS logs. However, 100% of SMS messages sent from the SIM are programmatically routed by Twilio.

US-only

Programmable SMS is currently only offered when connected in the USA. This is expected to change during the beta.

Trial Accounts

Currently, Wireless Programmable SMS requires an upgraded Twilio account.

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.