SMS Quickstart

Setup instructions for SMS

OneSignal’s SMS feature allows you to create and send SMS easily to your users. To send SMS from OneSignal, you will need:

  1. An account with Twilio (SMS platform)
  2. Twilio SID and Auth Token to setup OneSignal
  3. Import Subscriber Phone numbers

Acquiring Phone Numbers

From phone numbers

Phone numbers to send SMS from.

Acquire From phone numbers on Twilio or use your phone numbers (but you can only send SMS within your country using your number).

👍

OneSignal SMS supports sending messages using regular 10 digit Long Codes, Short Codes, and Toll-Free numbers.
Support for AlphaSender IDs and Twilio Messaging Service IDs is coming soon.

To/Audience Phone Numbers

Phone numbers in which to send SMS.

Twilio and OneSignal require all user phone numbers to be in the E.164 format. More details on the format can be found on Wikipedia.

📘

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

Step 1 Platform Selection

For a new application, choose the SMS channel from the list of platforms.

To add SMS to an existing application, go to the Application Settings → Platform, choose the SMS channel from the list of platforms.

Step 2 Twilio Account Setup

Enter the Twilio Account SID and Auth Token to allow OneSignal to fetch the From phone numbers and send SMS.

OneSignal Configuration Screen - Twilio DetailsOneSignal Configuration Screen - Twilio Details

OneSignal Configuration Screen - Twilio Details

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

Twilio ConsoleTwilio Console

Twilio Console

Step 3 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 to send SMS. You can also choose a different From phone number on the SMS creation page if you prefer to not use the default From Number.

Test the Twilio-OneSignal configuration
If you wish to first test if the Twilio-OneSignal integration is successful, you can use the Send a Test SMS step to verify. Simply enter a phone number and click on Send Test Message to get an automated test SMS on the phone number entered.

Step 4 Add Phone Numbers

Before you send an SMS, you need to have registered phone numbers within OneSignal. You can add phone numbers by:

  1. Import Phone Numbers through our Dashboard or API.
  2. Collect Phone Numbers using our SDK.

setSMSNumber Method

If you have not done so, we always recommend updating the OneSignal SDK to the latest version to get access to the latest features.

If you have a website, you can prompt the user to provide their number using the Email & Phone Number Web Prompt.

🚧

SMS vs Push Records

SMS and Push subscribers will have separate OneSignal Player IDs (user records). This is to manage the case where a user opts-out of one you can still send messages to the other.

🚧

Note on Network Latency

If there are networking issues, functions may take 30+ seconds to return. In the code examples below we provide callbacks to track when these return.

Make sure to keep functions from blocking the user interface, otherwise your app may appear unresponsive to the user.

The setSMSNumber method allows you to set the user's SMS number with the OneSignal SDK. We offer several overloaded versions of this method.

OneSignal.push(function() {
  OneSignal.setSMSNumber("+123456789");
});
OneSignal.setSMSNumber("+123456789");
OneSignal.setSMSNumber("+123456789")
OneSignal.setSMSNumber("+123456789")
[OneSignal setSMSNumber:@"+123456789"];
OneSignal.setSMSNumber("+123456789");
OneSignal.shared.setSMSNumber(smsNumber: "+123456789")

If you have a backend server, we strongly recommend using Identity Verification with your users. Your backend can generate an SMS authentication token and send it to your app or website. The following code also includes callbacks:

String smsNumber = "+123456789";
String smsAuthHash = "..."; // SMS auth hash generated from your server
OneSignal.setSMSNumber(smsNumber, smsAuthHash, new OneSignal.OSSMSUpdateHandler() {
  @Override
  public void onSuccess(JSONObject result) {
    // SMS successfully synced with OneSignal
  }

  @Override
  public void onFailure(OneSignal.OSSMSUpdateError error) {
    // Error syncing SMS, check error.getType() and error.getMessage() for details
  }
});
NSString *smsHashToken = @"..."; //generated on your backend server
NSString *smsNumber = @"+123456789";
[OneSignal setSMSNumber:smsNumber withSMSAuthHashToken:smsHashToken withSuccess:^(NSDictionary *results) {
  // SMS successfully synced with OneSignal
} withFailure:^(NSError *error) {
  // Error syncing SMS, check error.getType() and error.getMessage() for details
}];
let smsHashToken = "..." //generated on your backend server
let smsNumber = "+123456789"
OneSignal.setSMSNumber(smsNumber, withSMSAuthHashToken: smsHashToken, withSuccess: {
    //The SMS number has successfully been set.
}) { (error) in
    //Encountered an error while setting the SMS number.
}
OneSignal.push(function() {
  var smsNumber = "+123456789";
  var smsAuthHash = "..."; // SMS auth hash generated from your server
  OneSignal.setSMSNumber(
    smsNumber,
    { identifierAuthHash: smsAuthHash }
  );
});
var smsNumber = "+123456789";
var smsAuthHash = "..."; // SMS auth hash generated from your server
OneSignal.setSMSNumber(smsNumber, smsAuthHash);
String smsNumber = "+123456789";
String smsAuthHash = "..."; // SMS auth hash generated from your server

OneSignal.shared.setSMSNumber(smsNumber: smsNumber, smsAuthHashToken: smsAuthHash).then((response) {
  // The SMS number has successfully been set.
}).catchError((error) {
   // Error syncing SMS
});

logoutSMSNumber Method

If your app or website implements logout functionality, you can call logoutSMSNumber to dissociate the SMS from the device:

OneSignal.push(function() {
  OneSignal.logoutSMS();
});
OneSignal.logoutSMSNumber();
OneSignal.logoutSMSNumber()
[OneSignal logoutSMSNumber];
OneSignal.logoutSMSNumber();
OneSignal.shared.logoutSMSNumber()

addSMSSubscriptionObserver Method

Mobile App only - The sms subscription observer tracks changes to SMS subscriptions (ie. the user sets their SMS number or logs out). In order to subscribe to SMS subscription changes you can implement the following:

OneSignal.addSMSSubscriptionObserver(stateChanges -> {
    // Work with state changes          
  });
[OneSignal addSMSSubscriptionObserver:self];
OneSignal.add(self as OSSMSSubscriptionObserver)
OneSignal.addSMSSubscriptionObserver((event) => {
  console.log("OneSignal: sms subscription changed: ", event);
});
OneSignal.shared.setSMSSubscriptionObserver((OSSMSSubscriptionStateChanges changes) {
});

Now, whenever the sms subscription changes, this method will be called:

OSSMSSubscriptionObserver subscriptionObserver = new OSSMSSubscriptionObserver() {
   @Override
   public void  public void onSMSSubscriptionChanged(OSSMSSubscriptionStateChanges stateChanges) {
   }
};
-(void)onOSSMSSubscriptionChanged:(OSSMSSubscriptionStateChanges *)stateChanges {
    
}
func onOSSMSSubscriptionChanged(_ stateChanges: OSSMSSubscriptionStateChanges!) { 
    
}

getSMSId Method

Web only - Get the OneSignal Player ID associated with the SMS Phone Number Record.

OneSignal.push(function() {
  OneSignal.getSMSId();
});

Did this page help you?