Automatic SMS Verification with SMS User Consent

Sean McQuillan
Aug 6, 2019 · 4 min read

If you’re implementing SMS verification using one-time-codes into your app, check out the new SMS User Consent API.

SMS verification is a common way to add a second form of verification to apps. By sending an SMS message containing a one-time-code like “1234” or “481236” to the user’s phone number, they can then enter the code into your app to confirm that they received the SMS message.

From: SMS

Message: Your one-time code is 1234.

But — let’s be honest. No one actually enjoys typing out one-time-codes. It’s tedious and error prone. So, while it helps with verification for your app, it’s important to make the experience as seamless as possible.

The SMS User Consent API lets your app prompt the user for permission to read the text of a single SMS message containing a one-time-code. Your app can then parse the message and automatically complete the SMS verification flow!

Animated phone displaying one-time-code text message
Animated phone displaying one-time-code text message
Ask the user to read a single text message containing a one-time-code.

If you’re already using the SMS Retriever API — the SMS User Consent API does not deprecate or replace it. We’re adding a second API because there are times where apps can’t modify the message to support the SMS retriever API.

You should check out the SMS Retriever API before implementing SMS User Consent to see if it works for your app. If you can use it, it provides an even better user experience because the user can skip the prompt!

API Overview

Introducing the SMS User Consent API.

This post covers the basics for using the API — just enough to get you oriented. For a complete guide to the API (including a sample implementation) check out documentation!

The SMS User Consent API is part of Google Play Services. To use it you’ll need at least version 17.0.0 of these libraries:

implementation ""
implementation ""

Step 1: Start listening for SMS messages

SMS User Consent will listen for incoming SMS messages that contain a one-time-code for up to five minutes. It won’t look at any messages that are sent before it’s started.

SMS User Consent will never prompt for messages that don’t contain a one-time-code (4–10 characters with at least one number), or are from the users contacts.

If you know the phone number that will send the one-time-code, you can specify the senderPhoneNumber, or if you don’t null will match any number.

To start SMS User Consent, you use the SmsRetriever object:

senderPhoneNumber /* or null */)

Step 2: Request consent to read a message

Once your app receives a message containing a one-time-code, it’ll be notified by a broadcast. At this point, you don’t have consent to read the message — instead you’re given an Intent that you can start to prompt the user for consent.

Messaging asking permission for your app to read the message and enter a code
Messaging asking permission for your app to read the message and enter a code
Use the Intent passed to your BroadcastReceiver to show the SMS User Consent prompt.

Inside your BroadcastReceiver, you show the prompt using the Intent in the extras.

When you start that intent, it will prompt the user for permission to read a single message.

They’ll be shown the entire text that they will share with your app.

val consentIntent = extras.getParcelable<Intent>(

Step 3: Parse the one-time-code and complete SMS Verification

When the user clicks “Allow” — it’s time to actually read the message! Inside of onActivityResult you can get the full text of the SMS Message from the data:

val message = data.

You then parse the SMS message and pass the one-time-code to your backend!

Learn more

The SMS User Consent API helps you provide a great user experience for your users. By automatically parsing one-time-codes, users are able to complete SMS verification flows easily so they can get back to what they were doing.

To learn more, including a complete coding listing, check out the docs!

Android Developers

The official Android Developers publication on Medium

Sean McQuillan

Written by

Android Developer Advocate @Google

Android Developers

The official Android Developers publication on Medium

More From Medium

More from Android Developers

More from Android Developers

Now in Android #14


More from Android Developers

More from Android Developers

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade