Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

Send and receive text messages with Programmable SMS

Programmable Voice and Programmable SMS is offered as a developer preview for Wireless SIMs. (See the section "Known Limitations" below).

Any device connected by a Twilio SIM can send and receive Programmable SMS messages. This requires the device itself to support SMS messaging. It also requires the SIM's Rate Plan to have Messaging selected as an Enabled Service.

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.

SIMs can only send and receive SMS messages with a 160 character message limit.

SIMs cannot send or receive MMS message.

iMessage is not supported.

Purchase an SMS-enabled Twilio phone number

You first need to purchase a Twilio phone number that is SMS enabled.

  1. Point your browser to the Buy a Number section of the Console.
  2. Optionally, enter an area code of your choice in the input field.
  3. Check at least SMS from the Capabilities selections. Additional options are available by clicking Advanced Search.
  4. Click Search.
  5. You should see a list of available numbers to purchase.
  6. Click Buy to buy this number.
  7. Select a number of your choice.


You now have a Twilio phone number that you can associate with a SIM.

In the Console, you want to make sure the Programmable Wireless icon is visible in the side menu. If not, click All Products and Services and add it by pinning it to the dock.

  1. From Programmable Wireless click SIMs.
  2. Select the SIM that is in your phone. (Need help registering a SIM? See Ordering and registering your first SIM.)
  3. Click the Programmable Voice & SMS tab.
  4. In the Programmable SMS section, select TwiML from SMS URL.
  5. Click the red + button to the right of the input field.
  6. You should see a popup dialog appear with a TwiML template for routing messages.
  7. You can rename the Friendly Name.
  8. In the Message element, replace +YOUR_E164_Number_Here with the Programmable Number.
  9. Click Add TwiML Bin.
  10. Click Save.


You can learn about E164 number formatting at What is E.164?

That’s it! You can now send text messages from your phone. Feeling creative? Use functions or set up your own TwiML server to dynamically set the Caller ID.

How to receive a text message to a phone that has a Programmable Wireless SIM

You can now send SMSs from your cellphone with a Programmable Wireless SIM but you can't receive SMSs. This section will help you set up your SIM to receive text messages.

Create TwiML for incoming SMSs

In the Console, you want to make sure the Runtime icon is visible in the side menu. If not, click All Products and Services and add it by pinning it to the dock.

  1. From Runtime open TwiML Bins.
  2. Click the Red + Button to create a new TwiML Bin.
  3. Enter a name in the Friendly Name input field.
  4. For the TwiML Response, you can use the example shown below.
  5. In the Message element, enter the SIM Sid in place of YOUR_SIM_SID_HERE.
    Note: You can find your SIM Sid in the SIMs section under Programmable Wireless. The SIM Sid begins with the DE prefix. The to attribute starts with “sim:”
  6. Click Save.
<?xml version="1.0" encoding="UTF-8"?>
    <Message to="sim:YOUR_SIM_SID_HERE" from="{{From}}">


Associate TwiML with an SMS-enabled Twilio phone number

  1. From Phone Numbers section of the Console, select the programmable number you wish to associate with your SIM. (See Purchase an SMS-enabled Twilio phone number above if you don’t have a number.)
  2. From Configure With under Messaging, select Webhooks, TwiML Bins.
  3. Select TwiML from A message comes in.
  4. Select the TwiML you created in the previous section using its Friendly Name.
  5. Click Save.

SMS Set Incoming TwiML

Well Done! Now you can try sending a message to the phone number. If everything was set up correctly, you should receive the SMS message on your SIM-connected device.

Logs and Billing


You can view Call Logs for Wireless calls by selecting in the Console an Active Number, from Phone Numbers, then clicking the Calls Log tab.


Most call flows that involve a SIM will include two independent call legs: one call between Twilio and the non-SIM party, and the other between Twilio and the SIM-connected device.

The call leg from Twilio to the non-SIM party (PSTN, SIP, Client, etc.) is billed at standard Twilio voice rates, depending on the connectivity method used. The other call leg between Twilio and the SIM is billed at Programmable Wireless voice rates.

Known Limitations

Non-programmable SMS messages to the device

A phone number is provided on the SIM known as the MSISDN which is not used by Programmable Voice or Programmable SMS. The presence of the MSISDN means that some (potentially unwanted) calls may arrive straight to your SIM without routing via Twilio. If this occurs, Twilio cannot yet offer programmatic control over the calls and you won't see them in your Twilio call logs. However, 100% of calls and messages originating from the SIM are programmatically routed by Twilio.

Trial Accounts

Currently, Wireless Programmable SMS requires an upgraded Twilio account.

What’s Next?

You’ve followed all the guides in the Getting Online section and you’re ready to dive deeper into Programmable Wireless. From here, you can learn more from our API documentation, continue on to the next section, or check out the Blueprints.

Jon Davis Glenn Lea Kat King Evan Cummack
Rate this page:

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.