🚧

Feature in Beta

We are still hard at work on this feature and welcome all feedback!

What is the E.164 format?

OneSignal (and Twilio) requires all user phone numbers to be in the E.164 format.
E.164 is an international standard that defines the numbering format for phone numbers. The format requires only digits with country code (1 to 3 digits) and subscriber phone number (max 12 digits). Typically, it looks like this:

• +(plus sign)
• international country code
• area code without leading 0
• local phone number

Here is an example of a US phone number:

• Phone number: 999 999 9999
• E.164 format: +19999999999

And in London, UK:

• Phone Number: 020 9999 9999
• E.164 format: +442099999999

Which SMS providers are supported?

Currently, OneSignal only supports Twilio. Please connect with OneSignal support to let us know if you want to use other SMS providers.

Do I need to have an SMS platform (Twilio) account and pay them separately?

Yes, you need to create an account with Twilio and make sure you have sufficient balance to send SMS. OneSignal provides a single integrated platform for your Push, Email, and SMS subscribers and a simple to use SMS creation and sending experience, along with detailed delivery analytics. Sending an SMS is handled by SMS providers such as Twilio.

Can I send multimedia messages (MMS) as well?

You can add up to 10 media URLs in your SMS along with your text message. The message size shall not exceed 5MB though. Twilio fully supports the following media types and formats them for delivery on destination devices.

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

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

📘

Countries with MMS Support

• Twilio only supports MMS in the US and Canada.
• MMS messages sent to other countries will be converted to SMS text messages with a URL link to the media.

How can I add SMS subscribers to OneSignal?

To add SMS subscribers, you will need to import your existing SMS users to OneSignal. The easiest way to do this is to upload a CSV with the phone numbers in the E.164 format and an external user id to uniquely identify the phone numbers.

How can I update SMS subscriber records?

You can add or update tags (customer attributes) to your existing OneSignal SMS subscribers by following these instructions.

What is GSM-7 and UCS-2 encoding?

SMS messages are encoded in either GSM-7 or UCS-2. GSM-7 encoding is more commonly used and supports numbers, English alphabets, some Greek characters, and also special characters. A list of GSM-7 supported characters can be found on Wikipedia or on Twilio.

For other languages or characters such as emojis, SMS messages are sent via UCS-2 encoding.

What is the SMS character limit and Message Segment?

The character limit for a single SMS message is 160 characters for messages using GSM-7 encoding and 70 characters if sent via UCS-2 encoding. However, most modern phones and networks support message segmenting, concatenation, and then rebuilding messages up to 1600 characters.

When you send an SMS message longer than 160 GSM-7 characters or 70 UCS-2 characters, the message will be split into multiple segments. Twilio then uses six bytes for the Data Header for re-assemble instructions. This leaves each message segment with 153 GSM-7 characters or 67 UCS-2 characters. Additional details on how Twilio handles the SMS character limit can be found here.

You can also use the Twilio provided message length calculator to verify the segment count.

How do you calculate character count for emojis?

Unfortunately, emojis don’t have a standard character count and therefore, it is difficult to estimate the effect on the message character count. Our recommendation is to test your SMS with emojis before sending out the message to your users.

How many SMS can I send?

OneSignal hasn’t put any cap on SMS sending. However, Twilio has set certain limits when you send multiple messages from a single From number (regular long code number or Alphanumeric Sender ID).
With US or Canada long code numbers, you can only send one SMS segment per second per sender phone number. For non-US, non-Canada long code numbers or Alphanumeric Sender ID, you can send up to 10 SMS segments per second per sender phone number.
Twilio will queue up messages for 4 hours for messages exceeding the above limits. For example, for a US long phone number with one message segment per second per sender phone number limit, Twilio will queue up 14,400 (4 hrs x 60 minutes x 60 seconds) message segments and throw an error for other messages.
For higher sending limits, you can use Twilio Messaging Service or apply for Short Codes where the limit is 100 messages per second.

How do I send international SMS?

You need to enable International texting on Twilio. On OneSignal, it is the same process to send SMS to users in your country or to international users. To turn ON the setting on Twilio, navigate to Programmable Messaging from All Products and Services on the right-hand side of the Twilio Console and then enable International texting from Geo Permissions under Settings.

How can users STOP/ Unsubscribe from SMS?

OneSignal doesn’t support two-way messaging. OneSignal will not capture users responding with “STOP/UNSTOP/CANCEL” etc messages to stop the SMS subscription. However, Twilio records such requests from your users and blocks any future SMS messages to be sent to the unsubscribed users.

What is a long code, short code, alphanumeric sender ID, and messaging service?

Note: You need to register for these numbers on Twilio. Phone number registration service is not provided by OneSignal.

* Long codes
A long code is a standard 10-digit phone number (in most countries) used for voice calls and SMS. Here is an example of a US long code phone number: 999-999-9999

* Short Code (Coming Soon)
A short code is a 5-6 digit phone number that can also be used for SMS and MMS messages to and from mobile phones. Short codes require approval from the carriers and the process typically takes 8-12 weeks. Short Codes are preferred for high-volume messages as they are carrier-approved and will not be marked as spam.
Twilio only offers short codes in the US, Canada, and the UK. An example of a short code:
Number: 894546
Short Code spells TWILIO

* Alphanumeric sender IDs (Coming Soon)
Alphanumeric sender IDs are custom strings used in the From field of a message, instead of an E.164 formatted phone number. These are preferred for branded one-way messaging where you can use the custom string as per your business branding.
Note: Alphanumeric sender IDs are currently not supported in the USA and Canada. Here is the list of countries that support this feature.

* Messaging Service (Coming Soon)
Twilio offers functionality called Messaging Service that allows bundling of messaging numbers. You can define configuration settings and rules for a messaging service and those settings will apply to all the phone numbers (long codes, short codes, toll-free numbers, etc.) associated with the messaging service.

This helps reduce the complexity when sending a high volume of messages as you can define common features, senders, etc to easily manage your account and message logs.

SMS Regulations

❗️

Warning: This section shall not be considered legal advice. You should seek the advice of your legal counsel for more detailed information on rules and regulations.

Here are a few basic guidelines you should follow for SMS:

• Send SMS to subscribers only and honor opt-outs
• Communicate clearly what users are subscribing to
• Maintain subscriber opt-in details including type of SMS they opted-in to, subscription time and current status, frequency, etc

Please also refer to Twilio's Messaging Policy and Acceptable Use Policy to make sure your SMS are not getting filtered by Twilio or the carriers.

Additional Resources for regulations in the US:

• Twilio
• CTIA (the trade association representing the wireless communications industry in the USA)

Note: Countries have different legal requirements for sending SMS. Twilio has shared country-wise guidelines here. However, for international messages, please research the rules and regulations in the receiver’s country before sending messages.