Twilio Verify Push Android Client Library Quickstart

You can sign up for a free Twilio trial account here.

• When you sign up, you'll be asked to verify your personal phone number. This helps Twilio verify your identity.
• Once you verify your number, you'll be asked to create a project. For the sake of this tutorial, you can click on the "Learn and Explore" template. Give your project a name, or just click "skip remaining steps" to continue with the default.
• Once you get through the project creation flow, you'll arrive at your project dashboard in the Twilio Console. This is where you'll be able to access your Account SID, an authentication token, create a Push Credential, create a Verify Service and more.

To configure push notifications, follow these instructions to set up a Firebase Cloud Messaging client app on Android:

1. Create a Firebase project for your app
2. Register your app with Firebase
3. Add a Firebase configuration file
4. Add Firebase SDK to your app
5. Edit your app manifest

For Verify Push to send push notifications to your Android app, you will need to create a Firebase Cloud Messaging (FCM) Push Credential that contains your FCM secret.

1. In your app's Firebase project, go to Project settings and Cloud Messaging tab
2. Copy the Server key in the Project credentials section

Expand image

Follow these steps to do it in the Twilio Console.

• Go to Twilio Console > Account > Keys & Credentials > Credentials > Push Credentials:

Expand image

• Click the "Create new Credential" button to add a new credential and a form will pop-up:

Expand image

• Enter a friendly name, such as "Verify Quickstart App Credentials"
• Select FCM push credentials as type
• Enter the FCM Secret. The value is your Android app's Server key.
• Click the Create button

• Go to Twilio Console > Verify > Services and create a new Service.

  • Alternatively, you can select any existing Service. However, we recommend creating a new service for testing so you don't accidentally interfere with a production environment.

• From Twilio Console > Verify > Services, select your Service to access its Settings. Under the Push section, select the Credential SID(s) that you want this Service to use for sending push notifications. One SID can be selected for your Android app (FCM) and one for your iOS app (APN).

Follow the installation steps in the README file of the Twilio Verify Android repo. The installation steps will explain how to add the Android library to your build.gradle file and setup your Android app to work with Firebase Cloud Messaging (FCM).

After you import the Twilio Verify Android library, you can start to integrate your existing app with Verify Push.

To get started, you will need to create an instance of the TwilioVerify class, using its Builder. Type or paste the sample code.

1
TwilioVerify twilioVerify = new TwilioVerify.Builder(applicationContext).build();

Full Kotlin source

Full Java source

Your Android app needs to obtain an Access Token (technically an Enrollment JWE, similar to a JSON Web Token (JWT)) to make direct requests to the Verify Push API in the future. This Access Token request needs to be brokered by your app backend. To do this, you need to:

1. Expose an API endpoint in your app backend for your Android app to request the Access Token

2. Have your app backend request an Access Token from Verify Push API

3. Return the Access Token, identity and Verify Service SID to the Android app

Check out our Sample Backend using Twilio functions for an implementation example. In a production web application, you would restrict access token retrieval to the currently authenticated user, using whatever type of authentication your service already uses.

In the sidebar to the right (or below) is sample code for requesting an access token from the Verify Push API in all languages supported by Twilio helper libraries. You will need the Verify service_sid, as well as the user id (such as a GUID or the user's primary key in your database table) you use as the identity with this Verify service.

1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3

4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9

10
async function createAccessToken() {
11
  const accessToken = await client.verify.v2
12
    .services("VAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
13
    .accessTokens.create({
14
      factorType: "push",
15
      identity: "User_UUID",
16
    });
17

18
  console.log(accessToken.sid);
19
}
20

21
createAccessToken();

1
{
2
  "sid": "YKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4
  "service_sid": "VAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
5
  "entity_identity": "ff483d1ff591898a9942916050d2ca3f",
6
  "factor_type": "push",
7
  "factor_friendly_name": "John Doe iPhone",
8
  "ttl": 300,
9
  "date_created": "2015-07-30T20:00:00Z",
10
  "token": "eyJ6aXAiOiJERUYiLCJraWQiOiJTQVNfUzNfX19LTVNfdjEiLCJjdHkiOiJ0d2lsaW8tZnBhO3Y9MSIsImVuYyI6IkEyNTZHQ00iLCJhbGciOiJkaXIifQ..qjltWfIgQaTwp2De.81Z_6W4kR-hdlAUvJQCbwS8CQ7QAoFRkOvNMoySEj8zEB4BAY3MXhPARfaK4Lnr4YceA2cXEmrzPKQ7bPm0XZMGYm1fqLYzAR8YAqUetI9WEdQLFytg1h4XnJnXhgd99eNXsLkpKHhsCnFkchV9eGpRrdrfB0STR5Xq0fdakomb98iuIFt1XtP0_iqxvxQZKe1O4035XhK_ELVwQBz_qdI77XRZBFM0REAzlnEOe61nOcQxkaIM9Qel9L7RPhcndcCPFAyYjxo6Ri5c4vOnszLDiHmeK9Ep9fRE5-Oz0px0ZEg_FgTUEPFPo2OHQj076H1plJnFr-qPINDJkUL_i7loqG1IlapOi1JSlflPH-Ebj4hhpBdMIcs-OX7jhqzmVqkIKWkpPyPEmfvY2-eA5Zpoo08YpqAJ3G1l_xEcHl28Ijkefj1mdb6E8POx41skAwXCpdfIbzWzV_VjFpmwhacS3JZNt9C4hVG4Yp-RGPEl1C7aJHRIUavAmoRHaXbfG20zzv5Zu0P5PcopDszzoqVfZpzc.GCt35DWTurtP-QaIL5aBSQ",
11
  "url": "https://verify.twilio.com/v2/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/AccessTokens/YKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
12
}

Register a user and their device in Verify Push by creating and verifying a Factor. Type or paste the code samples for both of these steps.

1
Map<String,String> metadata = new HashMap<>(); // Custom metadata associated with the factor. Optional
2
metadata.put("os", "Android");
3
FactorPayload factorPayload = new PushFactorPayload(factorName, verifyServiceSid, identity, pushToken, accessToken, metadata);
4
twilioVerify.createFactor(factorPayload,
5
  new Function1<Factor, Unit>() {
6
    @Override public Unit invoke(Factor factor) {
7
      // Success
8
      return Unit.INSTANCE;
9
    }
10
  }, 
11
  new Function1<TwilioVerifyException, Unit>() {
12
    @Override public Unit invoke(TwilioVerifyException error) {
13
      // Error
14
      return Unit.INSTANCE;
15
    }
16
  });

Full Kotlin source

Full Java source

1
VerifyFactorPayload verifyFactorPayload = new VerifyPushFactorPayload(factorSid);
2
twilioVerify.verifyFactor(verifyFactorPayload,
3
  new Function1<Factor, Unit>() {
4
    @Override public Unit invoke(Factor factor) {
5
      // Success
6
      return Unit.INSTANCE;
7
    }
8
  }, 
9
  new Function1<TwilioVerifyException, Unit>() {
10
    @Override public Unit invoke(TwilioVerifyException error) {
11
      // Error
12
      return Unit.INSTANCE;
13
    }
14
  });

Full Kotlin source

Full Java source

Configure a webhook callback for your app backend to be notified of events such as when a Factor has been verified or when a Challenge has been approved, so that it knows to advance the user to the next step in your flow. This is more real-time and efficient than constantly polling the Verify Push API for the status of a Factor or Challenge.

Follow the steps in this Verify Webhooks page.

1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3

4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9

10
async function createWebhook() {
11
  const webhook = await client.verify.v2
12
    .services("VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13
    .webhooks.create({
14
      eventTypes: ["*"],
15
      friendlyName: "My Webhook",
16
      webhookUrl: "https://mywebsite.com/webhook",
17
    });
18

19
  console.log(webhook.sid);
20
}
21

22
createWebhook();

1
{
2
  "url": "https://verify.twilio.com/v2/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Webhooks/YWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3
  "sid": "YWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
5
  "service_sid": "VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
6
  "friendly_name": "My Webhook",
7
  "event_types": [
8
    "factor.deleted",
9
    "factor.verified"
10
  ],
11
  "webhook_method": "POST",
12
  "webhook_url": "https://mywebsite.com/webhook",
13
  "status": "enabled",
14
  "version": "v2",
15
  "date_created": "2015-07-30T20:00:00Z",
16
  "date_updated": "2015-07-30T20:00:00Z"
17
}

Congratulations! Verify Push consists of two user sequences, and you've just completed the first one: user and device registration. The second sequence is to challenge and verify (authenticate) a user with their registered device. Read on for the step-by-step instructions.

Your web application backend needs to call the Verify Push API to create a Challenge using the Factor that you've just created. When the challenge is created, Verify Push sends a push notification to the registered device using the configured Push Credential.

The code in the sidebar to the right/bottom demonstrates how to create those challenges using the Twilio helper libraries.

1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3

4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9

10
async function createChallenge() {
11
  const challenge = await client.verify.v2
12
    .services("VAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
13
    .entities("User_UUID")
14
    .challenges.create({
15
      "details.fields": [
16
        {
17
          label: "msg",
18
          value: "Challenge details shown to user",
19
        },
20
      ],
21
      "details.message":
22
        "Message shown to the user when the push notification arrives",
23
      expirationDate: new Date("2020-07-30 21:00:00"),
24
      factorSid: "YFXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
25
      hiddenDetails: {
26
        msg: "Challenge details not shown to user",
27
      },
28
    });
29

30
  console.log(challenge.sid);
31
}
32

33
createChallenge();

1
{
2
  "sid": "YC03aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4
  "service_sid": "VAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
5
  "entity_sid": "YEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
6
  "identity": "User_UUID",
7
  "factor_sid": "YFXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
8
  "date_created": "2015-07-30T20:00:00Z",
9
  "date_updated": "2015-07-30T20:00:00Z",
10
  "date_responded": "2015-07-30T20:00:00Z",
11
  "expiration_date": "2020-07-30T21:00:00Z",
12
  "status": "pending",
13
  "responded_reason": "none",
14
  "details": {
15
    "message": "Hi! Mr. John Doe, would you like to sign up?",
16
    "date": "2020-07-01T12:13:14Z",
17
    "fields": [
18
      {
19
        "label": "Action",
20
        "value": "Sign up in portal"
21
      }
22
    ]
23
  },
24
  "hidden_details": {
25
    "ip": "172.168.1.234"
26
  },
27
  "metadata": null,
28
  "factor_type": "push",
29
  "url": "https://verify.twilio.com/v2/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Entities/ff483d1ff591898a9942916050d2ca3f/Challenges/YC03aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
30
  "links": {
31
    "notifications": "https://verify.twilio.com/v2/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Entities/ff483d1ff591898a9942916050d2ca3f/Challenges/YC03aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Notifications"
32
  }
33
}

Now that the pending Challenge has been created in the Verify API, your mobile app needs to become aware of it. This can be done by telling your user to open up your mobile app on the registered device, and then having your app check (poll) the Verify API for any pending Challenges whenever it's opened.

Example implementation

1. Display a message for your user to open your app on the registered device: "Approve this login/transaction by opening the [App name] app and tapping [Approve button text]

2. Know when the app is opened and in foreground, then automatically poll for pending challenges.

   1. Android: Use the onResume() method of your activity or subscribe to a lifecycle observer.
   2. iOS: Use the applicationWillEnterForeground method in your application delegate or sceneWillEnterForeground if your app supports scenes, see more info here.

3. Alternatively, you can display to the user an "inbox" menu item to manually check for "pending verification requests" (challenges)

4. To get the pending challenges you can call the getAllChallenges method in the SDK, passing Pending as ChallengeListPayload's status and Desc as ChallengeListPayload's order

5. You can define the number of challenges to be returned using ChallengeListPayload's pageSize. To show only one challenge, pass 1 as ChallengeListPayload's pageSize

6. You can display the pending challenge(s) as a pop-up, just like if your app had received a push notification

7. Alternatively, you can show multiple pending challenges in an "inbox" menu item. You can display a badge number in the inbox to let the user know how many pending challenges are waiting for them.

1
ChallengeListPayload challengeListPayload = new ChallengeListPayload(factorSid, PAGE_SIZE, Pending, Desc);
2
twilioVerify.getAllChallenges(challengeListPayload,
3
  new Function1<List<Challenges>, Unit>() {
4
    @Override
5
    public Unit invoke(List<Challenges> challenges) {
6
      // Show pending challenge(s)
7
      return Unit.INSTANCE;
8
    }
9
  },
10
  new Function1<TwilioVerifyException, Unit>() {
11
    @Override public Unit invoke(TwilioVerifyException error) {
12
      // Error
13
      return Unit.INSTANCE;
14
    }
15
});

If you setup FCM push notifications as instructed in a previous section, then a push notification will be automatically sent when the pending Challenge is created. Your Android app then needs to read the contents of the push notification payload to obtain the challengeSid, factorSid, and message parameters.

The following Kotlin and Java code snippets run when there is an incoming FCM push notification, and if the type is verify_push_challenge, read the parameters out of the notification.

1
@Override public void onMessageReceived(@NonNull RemoteMessage remoteMessage) {
2
  String type = remoteMessage.getData().get("type");
3
  if ("verify_push_challenge".equals(type)) {
4
    String factorSid = remoteMessage.getData().get("factor_sid");
5
    String challengeSid = remoteMessage.getData().get("challenge_sid");
6
    String message = remoteMessage.getData().get("message");
7
    if (factorSid != null && challengeSid != null) {
8
      // Show push notification or update challenge
9
    }
10
  }
11
}

Once your app receives the push notification containing the challengeSid, it needs to retrieve the challenge details that correspond to that sid. Type/paste the sample code below. This step is not necessary if you have already retrieved the challenge details via the getAllChallenges method as previously instructed in the "poll for the challenge" section.

1
twilioVerify.getChallenge(challengeSid, factorSid,
2
  new Function1<Challenge, Unit>() {
3
    @Override public Unit invoke(Challenge challenge) {
4
      // Success
5
      return Unit.INSTANCE;
6
    }
7
  }, 
8
  new Function1<TwilioVerifyException, Unit>() {
9
    @Override public Unit invoke(TwilioVerifyException error) {
10
      // Error
11
      return Unit.INSTANCE;
12
    }
13
  });

Full Kotlin source

Full Java source

In an actual implementation, your Android app should either display the Challenge details to the user and request confirmation that the Challenge is expected, or silently approve the Challenge, because your app already knows that the user is trying to login on the same device as the registered device that is being challenged.

In either case, the next step is for your app to call the Verify Push API directly and update the Challenge status as approved or denied. Type/paste the sample code below into your Android app.

1
UpdateChallengePayload updateChallengePayload = new UpdatePushChallengePayload(factorSid, challengeSid, newStatus);
2
    twilioVerify.updateChallenge(updateChallengePayload,
3
        new Function0<Unit>() {
4
          @Override
5
          public Unit invoke() {
6
            // Success
7
            return Unit.INSTANCE;
8
          }
9
        },
10
        new Function1<TwilioVerifyException, Unit>() {
11
          @Override public Unit invoke(TwilioVerifyException error) {
12
            // Error
13
            return Unit.INSTANCE;
14
          }
15
        });

Full Kotlin source

Full Java source

By optionally implementing Silent Device Approval within the Verify Push Client Library, you can silently approve challenges without push notifications when your app already knows that the user is trying to complete an action (actively logging in, making a transaction, etc.) on the same device as the registered device that is being challenged. This results in an authentication that is completely invisible to the user. While implementation details will vary, here are some suggested steps:

• In order to be confident about the user's intent, the challenge approval should be done when the app is in foreground during the flow of the action that is being approved (e.g. immediately after the user taps "login").

• Identify the device starting the action and create a challenge for the factor linked to that device (a factor only represents one device).

• If you want to send challenges for multiple devices (factors) or if you want to be sure that you're approving the correct challenge, there are two options:

  • Include the associated challenge sid for the action in the response to the device and validate that it's the expected challenge sid before approving it.
  • Assign a transaction id to the started action and include it in the response to the device, and add the transaction id to the challenge's hidden details, so before approving the challenge you can get the challenge's hidden details to validate it is the expected challenge

• To receive the challenge on the client-side, you can:

  • Implement a strategy to listen for incoming push notifications when the app is in foreground and after some seconds, poll for pending challenges just in case the push notification did not arrive.
  • Poll for the latest pending challenge for an immediate approval, if your backend implementation can guarantee that the challenge was already created.

For additional suggestions, see:

• Getting challenge's hidden details
• Full source for listening to incoming push notifications when the app is in foreground
• Poll for the challenge

Once Verify Push API receives a Challenge update from your Android app, it will forward the update by sending a webhook callback (challenge.approved or challenge.denied) to your app backend, so that it knows to take your user to the next step in your flow. If you don't have a webhook configured, you can poll the Verify Push API for the status of the Challenge.

This completes the second user sequence of Verify Push: Challenge and verify a user.

Now that you've verified your first user, check out the following resources to continue your Verify Push journey with Twilio:

• Add Verify Push to your iOS app by following the iOS SDK Quickstart
• Prepare to go-live by reviewing Verify Push Best Practices for Production use
• Explore adding Verify's other verification channels beyond Push

We can't wait to see what you build!