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.
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!
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!
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:
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
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.
BroadcastReceiver, you show the prompt using the
Intent in the
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!
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!