The methods below require the OneSignal SDK versions 3 & 4.It is recommended to upgrade to our latest version 5 SDKs for User Model APIs.See Update to User Model for migration steps.

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 and Push subscribers will have separate OneSignal Subscription IDs (user records). This is to manage the case where a user opts-out of one you can still send messages to the other.

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. See SMS setup 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 Property	Type
`sms`	`string` 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 Subscription 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;

Developer Documentation

Mobile SDKs

Web SDKs

Live Activities

Desktop & Watch Setup

Legacy SDK reference

v3-4 SDK SMS SDK Methods

Setting the User’s SMS Number

`setSMSNumber` Method

Logout Number

`logoutSMSNumber` Method

Listening for subscription changes

`getSMSId` Method

​Setting the User’s SMS Number

​setSMSNumber Method

​Logout Number

​logoutSMSNumber Method

​Listening for subscription changes

​getSMSId Method

Setting the User’s SMS Number

`setSMSNumber` Method

Logout Number

`logoutSMSNumber` Method

Listening for subscription changes

`getSMSId` Method