SMS is a scalable channel for reaching users in real-time and outside of your app or website. SMS has among the highest open and engagement rates of all messaging channels. This guide explains how to setup SMS and MMS message and everything you need to know before you start sending.

If you haven't already, navigate to Settings > Platforms and activate your SMS channel.

Select the SMS provider

Currently there are 2 options for sending SMS and MMS messages: OneSignal or Twilio.

📘

Need someone from your team to help?

If you don't have access to Twilio, see Manage Team Members to invite them as admins and share this guide!

Option 1. OneSignal setup

OneSignal uses Twilio "under the hood" for sending SMS and MMS messages. This option is best if you do not have a Twilio account or want us to manage your Twilio account and you meet the following requirements:

• you send more than 5,000 SMS per month.
• you have a paid plan with OneSignal. See pricing page for details.

If you meet these requirements or have questions, click Book Demo with SMS Expert and follow the prompts. Our Support team will assist ASAP to help get you setup.

While you wait to get verified, continue with the next steps of this setup guide.

Option 2. Twilio setup

Use this option if you meet the following requirements:

• you send less than 5,000 SMS per month.
• you want direct access and control over your Twilio account.

This option is best if you are just testing out SMS, don't send too many SMS message pers month, and/or you want control over your Twilio account.

Details on direct Twilio setup (click to expand)

Twilio setup recommendations

The number you purchased from Twilio must support SMS (and MMS if you want to send images).

OneSignal SMS supports sending messages from regular 10 digit Long Codes, Short Codes, Toll-Free numbers, and Twilio Messaging Service IDs. AlphaSender IDs are supported if pooled under a Twilio Messaging Service. See SMS FAQ.

📘

Twilio trial accounts

For Twilio trial accounts (that is, if you have not upgraded your Twilio account), recipient phone numbers need to be registered on Twilio before they can receive SMS.

Configure SMS platform

In OneSignal, navigate to Settings > Platforms > SMS > Twilio.

Add your Twilio Account SID and Twilio Auth Token found in your Twilio Account Dashboard.

Select Next: Add Phone Numbers.

---

Set default “From” phone number

Once the app is successfully verified, we will automatically fetch all the From phone numbers associated with your Twilio account.

You can choose a “default” phone number from your registered numbers. You can always choose a different From phone number later or change them when sending messages.

Send a Test SMS

Enter your phone number and click Send Test SMS to send a test message.

If you don't get the message, make sure the default number selected supports SMS and check your Twilio logs for any errors.

If using a Twilio trial accounts, recipient phone numbers need to be registered on Twilio before they can receive SMS.

Select Next: Add Subscribers.

---

Users & sms subscriptions

Each phone number stored in your OneSignal app will be a unique Subscription. If the phone number does not have an accompanying External ID, then it will be considered a new User.

OneSignal (and Twilio) requires all user's phone numbers to be in the E.164 format. E.164 is an international standard that defines the numbering format for phone numbers.

You can add SMS subscriptions using the following methods. We also have a nice guide on creating your own custom opt-in flows. See SMS Opt-in and Collection for details.

CSV upload

This option is best when you have a list of phone numbers you want to upload into your OneSignal app quickly. See Import Phone Numbers for details.

API

Use our Create user API if you want to programmatically import phone numbers while also setting user properties and additional subscription details. If you already have users and just want to add SMS subscriptions to it, use the Create subscription (by alias) API.

Web prompt

If you have a website with us already, you can add a specific prompt to start asking users for their phone number. See Email & Phone Number Web Prompt for details.

SDK

Our web and mobile SDKs provide methods to both add and remove sms subscriptions from the app. These methods are recommended in most cases because it allows you to create and delete the phone number in real time along with associating it to the user. See SMS SDK Methods for details.

📘

Users, subscriptions & segments

See Users and Subscriptions for more details.

Once you start accumulating users, you can group them into Segments.

---

Configure double-opt in & keywords

With SMS, users can text back certain keywords to opt-in and out of SMS messages. You can configure these keywords in your OneSignal app following the SMS consent keyword management guide.

We also support double-opt in which means the user needs to respond to an initial text message before a subscription is created. See SMS Opt-in and Collection for details.

---

Design SMS & MMS

You can start building reusable SMS/MMS Templates or just start sending to your users.

📘

SMS & MMS can be expensive

Before you start sending SMS or MMS, it is important to be aware of how these are priced. Twilio (and all carriers) charge for the number of "segments" that a single message gets split into (these are not OneSignal's segments).

Depending on the amount of characters used in the message and the type of character encoding, carriers will split the message into multiple "message segments". A single "message" will then be charged based on the number of "message segments". See how SMS character count is calculated here.

OneSignal's form will help estimate the number of characters used so you can measure the costs of your SMS. More details below.

Content

SMS is very limited when it comes to their design. They do support both text and emojis, but not bold, italics or other formatting options.

Character encoding and emojis

A normal text message character count is limited to 160 characters for GSM-7 encoding and 70 characters for UCS-2 encoding.

• GSM-7 encoding allows for more characters to be sent. It supports numbers, English alphabets, some Greek characters, and some special characters. A list of GSM-7 supported characters can be found on Wikipedia or on Twilio.
• UCS-2 encoding is used for other languages or characters such as emojis. Also, MMS messages are sent via UCS-2 encoding.

When creating your SMS/MMS messages it is important to track how many and what type of characters you use. Depending on the encoding of the characters, you may be sending more than one "message segment" to all your users which will increase costs. OneSignal keeps this easy by telling you how many messages you will send based on the characters used and their counts.

When creating the message within your OneSignal dashboard you will see the estimated amount of messages (message segments) that will be sent based on the character count.

As you add more characters and/or characters with the UCS-2 encoding, then multiple messages may be needed. Instead of sending 1 message to x number of devices, you could be sending 2+ messages which can increase your spend.

URLs

You can send URLs within SMS messages. Shortening those URLs is recommended. However, using public URL shorteners like TinyUrl or Bitly have been forbidden by many carriers due to bad actors. If you want to send shortened URLs, it is recommended to use your own dedicated short domain. More details.

Personalization & dynamic content

OneSignal supports tags to personalize your text messages. For example, you can personalize SMS to each user with the {{ first_name | default: ‘default_value’ }} tag if you have added that previously. See Message Personalization for more details.

Dynamic Content enables editors to compose a single message that is dynamically personalized for each user who receives it. It is supported in Email, SMS, and Push Notification messaging.

Note: Personalizing message content can result in the SMS exceeding the character count limit. This can result in additional cost to you. Please test your SMS content before sending it.

Media

Multimedia Message (MMS). You can add up to 10 media URLs in an SMS with a total message size of less than 5MB. The following media types are fully supported.

• image/jpeg
• image/gif
• image/png

Twilio also accepts other media formats, but the content will not be modified for device compatibility.

Note: Twilio only supports MMS in the US and Canada.

👍

SMS setup complete!

See our SMS Messaging guide to get started!