SMS Setup

Setup instructions for SMS

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 page explains how to setup and send SMS and MMS messages from our dashboard, but other options for sending include:


  • An account with Twilio or talk to our Sales Team and we will set this up for you!
  • Twilio SID and Auth Token.
  • Supported sending number. Make sure the number you purchased from Twilio supports 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.
  • Import Phone Numbers. You cannot send SMS without the phone number subscription added within OneSignal using the E.164 format.


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

Navigate to Settings > Platforms > SMS and click Activate.

Add your Twilio Account SID and Twilio Auth Token.


Don't have a Twilio account?

Talk to our Sales Team about options for us to set this up for you!


OneSignal Configuration Screen - Twilio Details

You can get these account details from your Twilio Account Dashboard.


Twilio Console

Select Next: Add Phone Numbers.

Select Default β€œFrom” Phone Number

Once the Twilio account is successfully verified, OneSignal 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 test if the Twilio-OneSignal integration is successful. If you don't get the message, make sure the default number selected supports SMS and check your Twilio logs for any errors.


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.

Select Next: Add Subscribers.

Add Audience Phone Numbers

Before you send an SMS, you need to have phone number records within your OneSignal account. You can add SMS subscribers using the following methods:


SMS Setup Complete!

Next let's send an SMS and/or MMS message from your OneSignal dashboard.

Send SMS & MMS from OneSignal Dashboard

Navigate to New Message > New SMS


Image, showing where button is to create a new SMS

1. Audience

Optional: Input a Message Name for internal recognition of the message. See Message Name for more details.

Your audience is the Segment(s) of users in which you wish to include and exclude from receiving this message.

There are two options for selecting which users are eligible to receive messages.

  • Send to "default segment" - Displays the segment name for default segment. Otherwise, this defaults to all "Subscribed Users". See Segments for details on setting a default segment.
  • Send to Particular Segment(s) - You can both include and exclude users within segments from receiving the message. Any users in the segments listed under should not are excluded and will not get the message.

Targeting multiple segments:

  • Segments are "OR" relations; all users in all segments will be included or excluded.
  • OneSignal will automatically filter out duplicate users so they only get one message.

2. Message

Set From Number

Select the phone number that will send the SMS message. We will auto-fetch the list of phone numbers registered with your Twilio account.

Note: If you have registered your own phone number on Twilio and want to use that number to send SMS then Twilio only allows sending domestic messages.

Create Message


SMS Costs

Twilio (and carriers) charges for the number of segments that a single message gets split into. If the character count is greater than the above-stated counts, then carriers will split the message into multiple segments. A single "message" will then be charged based on the number of 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.

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


OneSignal supports emojis in your SMS content. However, emoji rendering and character count are not standard so please test the SMS before sending it to understand how they render and if they impact the character limit.


You can send URLs within SMS messages. Shortening those URLs is also 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.


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.

Send Test SMS

To test how your SMS content looks on different devices or how the message is segmented, please use the "Send a Test SMS" functionality above the message preview. Simply enter your test phone number to receive the SMS content.


Tag Substitution Limitation

Tag Substitution will not work with Send Test Message. You will need to setup a segment to send to yourself to test or use the API.


Key considerations

Test messages will be charged against your Twilio account balance.

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

Delivery Schedule

SMS & MMS can be sent immediately or scheduled up to 30 days in advance.

When ready, click Review & Send to review your message and Send Message.

If you need more time or help, you can Save as Draft to come back to it later. A Draft is not reusable like a Template.


SMS Tutorial Complete!

You are now ready to collect more phone numbers and continue sending!

What’s Next