Image for post
Image for post

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 ""

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 */)

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

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

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store