Guides
Log InSign Up

SMS SDK Methods

Collect SMS Numbers through your app or website.

Suggest Edits

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

🚧

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.

Setting the User's SMS Number

setSMSNumber Method

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("+11234567890");
});

OneSignal.setSMSNumber("+11234567890");

OneSignal.setSMSNumber("+11234567890")

OneSignal.setSMSNumber("+11234567890")

[OneSignal setSMSNumber:@"+11234567890"];

OneSignal.setSMSNumber("+11234567890");

OneSignal.shared.setSMSNumber(smsNumber: "+11234567890")

// Ionic 5 Capacitor may need to use (window as any).plugins.OneSignal
window.plugins.OneSignal.setSMSNumber("+11234567890");

OneSignal.Default.SetSMSNumber("+12345556789");

var result = await OneSignal.Default.SetSMSNumber("+12345556789");
if (result) {
    Debug.Log("success");
}
else {
    Debug.Log("error");
}

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.

Note that the SMS number is required to be in the E.164 format. Please see our SMS Troubleshooting guide for more details.

Logout Number

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()

// Ionic 5 Capacitor may need to use (window as any).plugins.OneSignal
window.plugins.OneSignal.logoutSMSNumber();

OneSignal.Default.LogOutSMS();

var result = await OneSignal.Default.LogOutSMS();
if (result) {
    Debug.Log("success");
}
else {
    Debug.Log("error");
}

Listening for subscription changes

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:

Event Object PropertyType
smsstring e.g: "+12149874829"
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) {
});

OneSignal.Default.SMSSubscriptionStateChanged += (current, previous) => {
    var smsSubscribed = current.isSubscribed;
};

OneSignal.on("smsSubscriptionChanged", event => {
   const { sms } = event;
   console.log("sms: ", sms);
});

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

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

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

var smsState  = OneSignal.Default.SMSSubscriptionState;
var smsUserId = smsState.smsUserId;
var smsNumber = smsState.smsNumber;

Updated over 1 year ago

What’s Next