App Verification with Twilio SMS

Verify Android Phone Numbers with Twilio

Does your Android application need to verify users' phone numbers using a one time password (OTP)? Using the new Android SMS Retriever API from Google Play Services and the Twilio Programmable SMS API, you can verify phone numbers without requiring a code to be typed in. Your application also won't have to ask for permission to read SMS messages.

Automating this stage in the onboarding funnel for your application could lead to happier end users, less customer support inquiries, and higher conversion rates. 

What is Twilio? Twilio provides an easy-to use API for sending and receiving SMS messages with a global reach. With one integration you can send text messages to users all over the world. 

What does that integration look like to send messages? One line of code to authenticate with Twilio and one line of code to send an SMS message. Want to try it yourself? Hop on over to the Twilio API Explorer, where you can use the Twilio REST API without writing any code.

Want to learn more about sending text messages with Twilio? Try one of the SMS quickstarts for Twilio, such as the Programmable SMS Quickstart for Node.js.

Twilio Verification SDK for Android

Looking for an easier way to integrate this API with Authy? Use the Twilio Verification SDK for Android to get all the benefits of the SMS Retriever API with your Authy integration. Follow our guide to get started!

Getting Started With SMS Verification

Let's get started with your first SMS Verification! There are a couple of things you will need to have to build SMS verification into your application.

For development and testing, you will need:

  • Android Studio (Download Android Studio from Google)
  • Twilio Account - create a Twilio account here. Unfortunately, trial accounts can not be used with this API - the message that gets prepended to all trial SMS messages will conflict with the requirements for the SMS Retriever API.
  • An Android phone, with an active phone number that can receive SMS messages, with Google Play Services 10.2 or above. You can check the version of Google Play Services on your phone under the Apps menu item in the Settings app.

Once you've assembled all of that, it's time to dig into some code samples! 

Download the Server Code

To get your solution up and running, you'll need a server. We've created quick start server applications that will provide a back end for your application.

Download the Android Sample Application

Google created a sample application for you to use as a reference to get started. You'll need to follow the README for the sample app to get it properly configured:

SMS Verify App GitHub Repo

One note - you'll need URLs for your web application to go into the sensitive.xml string values file in your Android app. You won't have those available until you get the web application up and running and either deploy it to the cloud, or use a localhost tunnel like ngrok to make a publicly accessible URL. 

Luckily, that's the very next set of steps to get this up and running!

Setting up the Server

Our sample server is written in Node.js, so you will need to have Node installed locally or on the server you plan to deploy too. Need to set up Node? Download an installer from the Node.js web site, or use your operating system's package manager.

The Node install comes with npm, the node package manager. After you download the server and unzip it, install the required Node modules from the command line with this command:

npm install

If you're curious about what modules the server is using (including the Twilio Helper Library for Node), take a look at the package.json file. 

Server Configuration

Once you have your server downloaded, you will need several configuration values. If you are using the Node.js server, copy the .env.example file to .env, and then fill in these values. You will need all of them for a successful installation.

Config Value Description
TWILIO_ACCOUNT_SID The account SID is your primary Twilio account identifier. You will be able to find this value in the Twilio Console.
TWILIO_API_KEY The Twilio SDK uses API Key and Secret pairs to make REST calls to the Twilio API. You can create a new API Key and Secret pair on the API Keys page in the Console.

TWILIO_API_SECRET The API Secret will only be shown once when you generate an API Key and Secret pair, so be sure to download it.
SENDING_PHONE_NUMBER  You will need a verified phone number to use to send SMS messages to the phone. You can verify your own phone number with Twilio, or use a phone number you purchased through Twilio.
APP_HASH The Android app hash is very important, as the existence of this hash in the SMS Message is what the SMS Retriever API  will look for. See Google's documentation on how to Compute your app's hash string. You can also find it under the Settings menu item in the sample application.
CLIENT_SECRET Matches the Android application to the server - you can set this in the sensitive.xml file in the sample Android application. It must match the server's config value. 

Running the Server

Run the application using the npm start command.

npm start

Your application should now be running at http://localhost:3000/

Creating a Publicly Accessible URL

Your phone won't be able to access localhost directly. You'll need to create a publicly accessible URL using a tool like ngrok to send HTTP/HTTPS traffic to a server running on your localhost. Use HTTPS to make web connections that retrieve a Twilio access token.

ngrok http 3000

Another alternative is to deploy this server to the cloud (such as Google App Engine) - you will need to configure the environment variables used above for your cloud provider.

Integrating the SMS Retriever API into your Android Application

You'll also probably need to integrate the SMS Retriever API into your existing Android application, either by replacing your existing verification process, or adding it as a new step. Check out Google's guide for how to Request SMS Verification in an Android App.

Android App Configuration

The sample Android application also needs to be configured to communicate with your server. Make sure you have an externally accessible URL for your application first (not localhost). If you need to create an external URL for your server application running on your local computer, download and install ngrok

Go ahead and open up the application in Android Studio, and then create a sensitive.xml file in the res/values folder. 

In the sensitive.xml file, add these values - you will need to replace your-server.com in the below code snippet with your server's domain name or IP address.

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string name="server_client_secret">0000000000</string>
    <string name="server_client_secret_v8">0000000000</string>
    <string name="url_verify">https://your-server.com/api/verify</string>
    <string name="url_request">https://your-server.com/api/request</string>
    <string name="url_reset">https://your-server.com/api/reset</string>
</resources>

You will also need to find and edit the server client secret lines in the sensitive.xml file. Make the secret the same string that you configured on the server.

Running the Android App

Once you've got everything all set up, build the app on Android Studio, and run it on your phone!

Double check that the App Hash (In the menu, under Settings) matches the value you have in your .env file - if it's different, go ahead and change it in .env and restart the server. 

Press the Sign Up button at the bottom of the app to get started with the verification process. On the next screen, when you tap the edit text input for the phone number, the Android app will use the hint picker to detect your phone's number, and then offer to fill that in for you.

Android SMS Verify App 1

 

After pressing the Submit button, the app will make an HTTP POST request to the server, and you will see a progress indicator and several toasts indicating the status of your application. If the app fails to connect, double check that the URLs in the strings.xml file in your Android app are correct.

 

Android SMS Verify App 2

 

Communication Between App and Server

The Android application sends an HTTP POST to the server with an application secret (that the app and the server both share) and a phone number to verify.

The server creates a one time password (OTP), and associates it with the user's phone number (for instance, in a cache or in a database).

The server then asks Twilio to send that phone number an SMS message with the OTP and the app hash. The app hash is required so that the SMS Retriever API can look up SMS messages specifically for that application. The SMS Retriever API also requires one of two specific headers at the beginning of the SMS - either:

[#]

or 

\u200b\u200b - which are invisible Unicode characters

The end of the SMS message must be an eleven-character app hash. The OTP can go anywhere in between these two required pieces, along with a short message from your app. 

Sample SMS Message

[#] Thank you for signing up for the app! Your code is 865235.
K4J3FRDUbDB

Common Problems and Debugging

SMS Verification on the Android Device Never Completes

One of the most common errors you might run into is that the hash of your Android application's package signature doesn't match the app hash that you send in your SMS message. If these two don't match, the Android application will not be able to read the incoming SMS from your inbox, and the verification process will never complete.

Double check that App signature has for the Android app matches the hash you set in the configuration variable for the server.

This may also not complete if you are using a trial Twilio account, as the trial SMS messages will have a preset prefix on each message, and the SMS Retriever API on the Android device will not process the message.

SMS Message doesn't come through

Another common type of error would be that the SMS message does not come through - it never gets sent to your phone. This usually indicates that some of the configuration values in your .env file are not set up correctly. Be sure to check the console logs for your server application to see if there are any runtime errors. You can also check the Twilio Debugger to see if there are any errors. 

Next Steps

You've got everything up and running, your Android app is now verifying its phone number via a Twilio SMS message, and it all works together - what's next?

Other Server Languages

We used Node.js for this quick start, but maybe you prefer Java, C#, Ruby, Python, or PHP! That's great because we support all of those languages for sending SMS messages as well. See the Twilio documentation for Sending an SMS Message with the REST API.

Storing the One Time Code

This quick start is pretty simple - the one time codes are stored in memory, and only accessible by this process. Unfortunately, if you were to restart the server or have more than one server application instance (for instance, behind a load balancer), all of those one-time codes would be lost, and the verification process wouldn't complete.

You'll want to store these one time codes in something with a persistence engine, such as Memcache, Redis, or your favorite database. Inside the quickstart, you would simply replace the references to the Cache object (note - this is not Memcache, although the name is similar) with calls to your storage engine.

Ramping Up the SMS Volume

If you expect more than a few users to be logging in at the same time, consider using Copilot or purchasing a short code to increase your outbound SMS throughput. 

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.