Why are my messages not displaying?

Make sure the "From" phone number you purchased from Twilio supports both SMS and MMS messages. For instance, if you don't see images, then your "From" number doesn't support MMS.

You may be on Twilio's unsubscribe list. Text START to the "From" number and try again.

Make sure the phone number you are sending "To" is in E.164 format.

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

Can I send multimedia messages (MMS) as well?

Yes, as long as the "from" phone number supports MMS, you can add up to 10 media URLs in your SMS along with your text message. The message size shall not exceed 5MB though.

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

Other media formats including audio, video and other image and text formats are accepted, but the content will not be modified for device compatibility.

📘

Countries with MMS Support

• 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?

See Import Phone Numbers for details on all options for adding SMS Subscribers.

How can users STOP/ Unsubscribe/Resubscribe from SMS?

See SMS consent keyword management for details.

Does OneSignal support two-way SMS or incoming SMS from the subscribers?

We support double opt-in and opt-in use cases with text-to-subscribe keywords and double opt-in message replies. Set these up in your SMS Settings, under Consent Management.

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 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.

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

The following are different phone numbers you can send SMS from.

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

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 currently offers short codes in select countries, including the US, Canada, and the UK. An example of a short code:
Number: 894546
Short Code spells TWILIO

Toll-Free Number

A toll-free number is a 10 digit phone number that begins with 8XX. You also have the option to choose a vanity toll-free number.

Toll-free numbers can be submitted for carrier verification which then helps avoid any message filtering by the carriers. This is a huge benefit over a regular long code.
Toll-free numbers also have a higher throughput rate (three message segments per second) compared to regular long code phone numbers. You can also pay more to increase the throughput for toll-free numbers.

Alphanumeric sender IDs

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.

How do I get an AlphaSender ID?

For many countries where there is no registration required for AlphaSender IDs, you can begin using Alpha Sender ID immediately. Please check the full list of countries that support Alpha Sender ID, as well as which countries require pre-registration.

• If a country supports Alpha Sender ID and does not list pre-registration as "Required", you can start using Alpha Sender ID right away: just create and add your Alpha Sender ID to a Messaging Service. Selecting that Messaging Service in your “from” parameter on the dashboard or the API call.
  Please note, a valid Alpha Sender ID must be up to 11 alphanumeric characters including A-z, 0-9 and space (" "). No special characters are allowed.

• If a country you want to send SMS to has Alpha Sender ID registration listed as "Required," you need to follow the country-specific process. Refer to Twilio's getting started with Alpha Sender ID guide.

Does the AlphaSender ID need to be associated with a messaging service?

To use an AlphaSender ID to send SMS, you need to create one and add it to a Messaging Service on Twilio. You can use that Messaging Service to then send SMS to your users from OneSignal.

Additional details found in Using Alpha Sender ID with Messaging Services.

Twilio Messaging Service

Twilio offers functionality called Messaging Service that allows “bundling” of different types of senders (long code numbers, short codes, toll-free numbers, etc.) in a single pool based around a common set of senders, features, and configuration. The same settings and feature configuration applies to all of the phone numbers in the pool.
Sending a high volume of messages has a lot of complexity in terms of organizing the account, message logs, delivery planning. etc. Messaging Service helps solves a lot of these concerns such as:

• Scaler feature - distributes your outbound messaging traffic evenly across the phone numbers in your Messaging Service so that you can handle higher volumes of messages, basically load balancing across multiple numbers in the service.
• Country Code Geomatch - for Intelligent routing (uses local phone numbers to send SMS or re-route in case of failures)
• Short Code Reroute - prioritizes message delivery using a short code, if available
• MMS converter - changing the SMS to a link if the device or the carrier doesn’t support media.

Messaging Service is also required to be compliant with the new 10DLC regulation which will soon be enforced by all major US carriers. Businesses are required to register their company and campaigns and then associate their phone numbers with specific campaigns. Message delivery speed or throughput will be determined based on the brand’s trust score and campaign use cases. This will help improve the delivery speeds and reduce carrier filtering when you use regular 10digit long codes to send SMS.

Customers can create and register Messaging Services for these campaign registrations and pool different types of sender numbers to serve their needs. Even though the regulation doesn’t require sending messages using Messaging Service, the sender (or from) phone numbers would need to be linked to a Messaging Service.

What is A2P 10DLC?

A2P 10DLC refers to a system in the United States that allows businesses to send Application-to-Person (A2P) type messaging via standard 10-digit long code (10DLC) phone numbers. Carriers in the US consider all Twilio traffic to be A2P.

10-digit long codes have traditionally been designed for Person-to-Person (P2P) traffic only, causing businesses to be constrained by limited throughput and heightened filtering.

• For businesses, 10DLC regulation provides better delivery quality and lower filtering risk than long code SMS of the past, using the same phone numbers.
• For end users, it will help reduce the spam content.

SMS regulations

❗️

Important

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.