Using SMS as a Fallback Option for Push Notifications

Using SMS as a fallback communication channel for users who are not subscribed to push notifications can help you reach a larger portion of your audience while respecting their communication preferences.

For example, a coffee company may use mobile push notifications to let customers know when their order is ready for pickup. To deliver a seamless customer experience for all patrons, they could set up SMS as a fallback communication channel in the event that a customer is not subscribed to push notifications. Doing so will ensure that more customers receive order pickup alerts and also creates a more inclusive and customer-centric brand experience.

This 5-step guide will demonstrate how to compose OneSignal Web Push SDK with the OneSignal Rest API to enable SMS for users who are not subscribed to push notifications on your site. This example is based on the OneSignal + Next.js integration sample app. All of the components needed to implement this use case can be implemented using any web technology and are not limited to Next.js and React.

This guide assumes that you have already configured the OneSignal Twilio integration.

1. Check if the current user has subscribed to push notifications

The OneSignal Web Push SDK provides an asynchronous function, known as isPushNotificationEnabledCallBack, that returns a boolean value that describes if the current user has push notifications enabled. You’ll call this function on the client once the component mounts to the DOM.

2. Tag users who have push notifications disabled

If the user does not have notifications turned on, you'll need to tag the user with some metadata to target them via our Segments feature.

You can tag users by calling the sendTag function made available by our Web Push SDK. The tag name is arbitrary, so I’m using subscribed_to_push as the tag for this example. You can filter users based on these tag values — something you’ll take advantage of when creating a new audience segment.

To enable an SMS notification as a fallback to push notifications, apply the subscribed_to_push tag based on whether or not the user has push notifications enabled.

3. Create an API endpoint that creates an SMS

To control when a notification is sent to the user, you'll need to create an API route to request the OneSignal API to send a notification on demand. You can achieve this with the notifications endpoint on the OneSignal API.

To send a text message notification, construct a request with the following shape.

{
    include_phone_numbers: [“+18001234567”],
    name: "Identifier for SMS",
    sms_from: "Twilio phone number",
    contents: {
    en: "English message",
    cn: "Chinese message"
}

Because I’m using Next.js for this example, I need to add a file to pages/api that exports a function that accepts an HTTP request and response object. In this example, I will set up the route to pull the phone number from the request body, but you can look up your users’ phone numbers instead.

4. Call the API endpoint that creates an SMS

The final step to enable automatic fallback to SMS notifications is to post a request to the route responsible for creating the notification. I will make this request in the callback passed to isPushNotificationsEnabled only when the user does not have push notifications enabled.

A text message will now be sent to the numbers in the request body whenever a user navigates to a page using the OneSignal hook. The phone number is currently hard-coded for demo purposes; you may need to get the number from the app state or perform a server-side lookup for the user’s account information if your site requires that user’s login.

5. Push an SMS to the segment of users who are not subscribed to push notifications

To support sending SMS notifications to all users who have opted out of push notifications, you can create a segment in your OneSignal Dashboard and filter by the tag’s value: subscribed_to_push.

The first step to send messages to all users with push notifications disabled is to create a new segment. I’m naming the segment Opted-out of push notifications and filtering by subscribed_to_push is false and the device type is SMS.

Sending an SMS notification to all users in the segment requires creating a message to send and selecting this new segment as the target.

When you click send, the text message will be sent to everyone in the segment, completing the workflow.

Other Updates on the Horizon

We are in the process of developing a new push-to-SMS retargeting functionality that will enhance our SMS fallback delivery capabilities. If you're interested in trialing this feature and providing feedback to inform our product roadmap, click the link below to learn more about participating in our Beta Program.

>> Learn More About the OneSignal Beta Program

Additional Support

Have questions or need some support getting started? We're here to help. Reach out to us at support@onesignal.com or login to your OneSignal account and send us a message from your dashboard.