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.

📘

Understanding SMS & MMS Pricing

Before sending SMS or MMS messages, it's important to understand how pricing works. Twilio (and all carriers) charge based on the number of message segments a single message is split into. (Note: These "segments" are different from OneSignal Segments.)

The number of message segments depends on:

• The total number of characters in your message
• The type of character encoding used

If a message exceeds a certain character limit, carriers will split it into multiple message segments, and each segment incurs a separate charge. You can check how SMS character count is calculated here.

OneSignal's form provides an estimate of character usage, helping you gauge SMS costs before sending. More details below.

Content

SMS is very limited when it comes to their design. They do support both text and emojis. Text formatting options like bold and italics are not supported.

Character Encoding and Emojis

A standard text message has a character limit based on the encoding used:

• GSM-7: Up to 160 characters per message segment.
• UCS-2: Up to 70 characters per message segment.

Encoding Differences

• GSM-7: Supports English letters, numbers, some Greek characters, and special symbols. It allows for more characters per message. See the full list of supported characters on Wikipedia or Twilio.
• UCS-2: Used for non-GSM-7 characters, including emojis and certain languages. MMS messages also use UCS-2 encoding.

When composing your SMS/MMS messages, keep track of:

• The number of characters used.
• The type of encoding required.

Since longer messages are split into multiple message segments, this can increase costs.

OneSignal's Character Estimation
To help manage costs, OneSignal automatically estimates how many message segments your message will use.

When composing your message in the OneSignal dashboard, you'll see an estimate of:

• The number of characters used
• The number of message segments required
• This ensures better cost control before sending messages to your users.

As you add more characters—especially those requiring UCS-2 encoding—your message may be split into multiple segments.

Instead of sending one message to each device, you could be sending two or more, increasing overall costs.

To avoid unexpected charges, monitor character usage and message segmentation in the OneSignal dashboard before sending.

.

URLs

You can send URLs within SMS messages. Shortening those URLs is highly recommended. However, using public URL shorteners like TinyUrl or Bitly is forbidden by many carriers.

If you want to send shortened URLs, it is recommended to use your own dedicated shortened domain. More details.

Personalization & Dynamic Content

OneSignal supports Liquid tags to personalize your text messages. For example, if you’ve set a first_name tag for users, you can personalize messages like this:

{{ first_name | default: 'customer' }}

If a user's first name is unavailable, "customer" will be used as a default. Learn more in our Message Personalization guide.

Dynamic Content

With Dynamic Content, you can create a single message that automatically personalizes itself for each recipient. This feature is available for Email, SMS, and Push Notifications.

⚠️ Important Note
Personalizing messages may increase the character count, causing your SMS to exceed the limit and be split into multiple segments—leading to higher costs.

✅ Best Practice: Always test your SMS by sending it to yourself before sending it to your audience.

Media

OneSignal supports 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!