There can be certain cases where users might not wish to share their Truecaller profile information with your mobile website, and may dismiss the profile dialog when invoked. For such cases, we pass appropriate error message to your callback URL so that you can accordingly take the next steps.

Other error scenarios might include cases where your backend fails to fetch user profile information from Truecaller probably due to some internal or network failure. These cases can be identified by having a threshold timeout ( recommended 30 seconds ) implemented with your client-server communication mechanism. In scenarios like above, where the user verification via Truecaller could not be completed, you should ideally show a proper error message to the users and take them to your alternate verification flow.

Once you have set the deep link parameters, you are ready to invoke the Truecaller verification on your mobile web page. You need to invoke the deep link using Javascript on your webpage. This will show the Truecaller verification dialog to the user if the Truecaller app is present on the user's mobile device. Please note that in case Truecaller app is not present on the user's device, the deep link won't trigger anything. To effectively handle this case, you should use the deep as suggested in the example below :

window.location = "truecallersdk://truesdk/web_verify?
                           type=btmsheet
                           requestNonce=UNIQUE_REQUEST_ID
                           &partnerKey=YOUR_APP_KEY
                           &partnerName=YOUR_APP_NAME
                           &lang=LANGUAGE_LOCALE
                           &privacyUrl=LINK_TO_YOUR_PRIVACY_PAGE
                           &termsUrl=LINK_TO_YOUR_TERMS_PAGE
                           &loginPrefix=TITLE_STRING_PREFIX
                           &loginSuffix=TITLE_STRING_SUFFIX
                           &ctaPrefix=BUTTON_TEXT_PREFIX
                           &ctaColor=BUTTON_FILL_COLOR
                           &ctaTextColor=BUTTON_TEXT_COLOR
                           &btnShape=BUTTON_SHAPE
                           &skipOption=FOOTER_CTA_STRING
                           &ttl=TIME_IN_MILLISECONDS";

setTimeout(function() {

  if( document.hasFocus() ){
     // Truecaller app not present on the device and you redirect the user 
     // to your alternate verification page
  }else{
     // Truecaller app present on the device and the profile overlay opens
     // The user clicks on verify & you'll receive the user's access token to fetch the profile on your 
     // callback URL - post which, you can refresh the session at your frontend and complete the user  verification
  }
}, 600);

This would trigger the deep link, and open the user's Truecaller profile dialog if the app is present on the device. And in case the app is not present, nothing opens. So now, using javascript, you can check for the document focus: a. If the truecaller dialog opened, the document would have lost focus and you'll be taken to the else condition in the above check. b. While in case the Truecaller app is not present on the device, the focus would always remain with the document and hence, you'll have the control in the 'if' condition. Accordingly, you can map the next action on your page based on the two conditions.

When you trigger the Truecaller verification flow, you would receive a prompt confirmation that the flow has been initiated successfully. When the Truecaller deeplink is invoked, and the user has the Truecaller application installed and logged in, a callback is sent to your configured URL. This callback includes the configured request nonce and status as "flow_invoked." Here is the sample of how the handshake callback looks like :

{
  "requestId": "<<Request_Nonce Value>>",
  "status": "flow_invoked"
}

Upon receiving the "flow_invoked" request notification, it is imperative for you to promptly reciprocate with an acknowledgment. This acknowledgment should be accompanied by a response code falling within the 2XX range, signifying successful communication.

This approach minimises reliance on "document.hasFocus". By leveraging the Handshake feature and receiving real-time callbacks, partners gain greater confidence and control in the user verification process, leading to a smoother user experience overall.

You can perform user verification via Truecaller at any touchpoint in your journey (for example - login, registration, checkout, verification, etc.).

To initiate the user verification, you need to trigger a deep link upon any user action, in the format mentioned below :

window.location = "truecallersdk://truesdk/web_verify?
                           type=btmsheet
                           requestNonce=UNIQUE_REQUEST_ID
                           &partnerKey=YOUR_APP_KEY
                           &partnerName=YOUR_APP_NAME
                           &lang=LANGUAGE_LOCALE
                           &privacyUrl=LINK_TO_YOUR_PRIVACY_PAGE
                           &termsUrl=LINK_TO_YOUR_TERMS_PAGE
                           &loginPrefix=TITLE_STRING_PREFIX
                           &loginSuffix=TITLE_STRING_SUFFIX
                           &ctaPrefix=BUTTON_TEXT_PREFIX
                           &ctaColor=BUTTON_FILL_COLOR
                           &ctaTextColor=BUTTON_TEXT_COLOR
                           &btnShape=BUTTON_SHAPE
                           &skipOption=FOOTER_CTA_STRING
                           &ttl=TIME_IN_MILLISECONDS";

Here, requestNonce should be a unique request ID that you need to associate with every verification request you trigger, so as to do the requisite mapping of the access token which we post to your callback URL once users share their consent.

Add the app key which you generated from your developer portal account in the partnerKey parameter, and the app name that you want users to see in the Truecaller profile dialog in the partnerName parameter.

The lang parameter refers to the language locale string corresponding to the language that you wish the user to see the profile dialog in ( For example - 'en' for English ). For complete list of supported languages in which you can show the profile dialog to the users, please refer below :

NOTE : In case the input locale is not supported, the profile will by default be shown in English language

The loginPrefix string option can be any one of the following parameters depending on what contextual title string prefix ( context/ goal ) you want to show to the user :

The loginSuffix string option can be any one of the following parameters depending on what contextual title string suffix ( action ) you want to show to the user :

The skipOption parameter enables you to add an optional footer string on the verification screen, which on being clicked by users, allows you to take them to your alternate verification flow. It can take any one of the following values:

The ctaPrefix parameter lets you choose the prefix string for the contextual text on the CTA button you want to show

The btnShape parameter lets you choose the shape of the CTA button you want to show

To customise the color of the CTA button on the verification screen, you need to configure the respective hex code in the "ctaColor" parameter as mentioned below :

ctaColor=%23f75d34

Similarly, in order to customise the color of the text on the CTA button on the verification screen, you need to configure the respective hex code in the "ctaTextColor" parameter as mentioned below :

ctaTextColor=%23f75d34

To add your privacy policy link on the verification screen ( optional ), you can configure the hyperlink string ( URL safe ) to your privacy policy page in the "privacyUrl" parameter as mentioned below :

privacyUrl="<<YOUR_PRIVACY_POLICY_LINK>>"

To add your terms of service link on the verification screen ( optional ), you can configure the hyperlink string ( URL safe ) to your terms of service page in the "termsUrl" parameter as mentioned below :

termsUrl="<<YOUR_TERMS_OF_SERVICE_LINK>>"

"Timeout" (ttl) parameter allows you to automatically dismiss the consent screen by adding the "ttl" value to the deeplink. The TTL feature enhances user flexibility and streamlines the verification process.

Here's how the TTL feature works:

• The default minimum value for the TTL is set to 8000ms (8s), ensuring a smooth user experience. If the "ttl" parameter is defined with a value less than 8000ms, it will automatically default to 8000ms. This means that if the user does not proceed with the flow within 8000ms, the consent screen will be automatically dismissed.

• There is no maximum value for the "ttl" parameter, giving you the freedom to set longer durations, if required. The timer value should be specified in milliseconds, allowing precise control over the consent screen duration.

• In cases where you do not specify the "ttl" parameter in the deeplink, the consent dialog will persist indefinitely, providing users with ample time to interact and proceed with the verification flow.

TTL based auto dismiss functionality would work if the end-user is having Truecaller app

While you start integrating Truecaller SDK, as the very first step, it is important to work on designing the right user flow, so that you can achieve desired results.

Truecaller SDK is a mobile number verification service, without the need for any OTP whatsoever.

The right way to implement Truecaller SDK on your mobile web, is to invoke mobile number verification via Truecaller at touch points, where you have your users to sign-up/ login/ checkout by verifying their mobile numbers.

Let us now see an example to understand how to effectively use Truecaller SDK at such touch points in your user journey

Users on CarDekho - India’s largest online auto discovery and classifieds platform, can browse for new cars, access details and more on CarDekho mSite. However, when users wish to take a test ride, get more details, request for car loan offers, and more, it requires users to verify their mobile number to ensure valid users are accessing such details.

From the above flow, we can see that for Truecaller users, signup is mere 1-step process without needing any OTP; while for non-Truecaller users the signup process is tedious, and involves many steps, and thus more possibilities of drop-offs.

Building for various touch points

a. User signup/ login via mobile number Example : Intrcity - India’s first SmartBus for safe inter-city travel

In order to complete your ticket booking on Intrcity’s mobile website, users need to verify their number in order to signup/ login into their accounts. Mobile number being an important part of the user profile, Intrcity uses Truecaller to quickly verify mobile number, and auto-fill certain parts of the user profile to reduce user effort and save time.

If you haven't already completed for your app, we recommend you to complete that first before proceeding with the integration.

Once you have received the user profile details at your backend, you need to complete the verification flow at your frontend. This requires you to essentially setup a proper communication mechanism in place between your frontend client and your backend. You can implement any of the below suggested methods to achieve the same :

Long Polling : As soon as you initiate the user verification flow at your frontend and get a successful check that Truecaller is present on the device, you can make a long polling request to your backend to check if the user's profile data has reached your backend or not. This kind of request can hold until a particular threshold time so that it waits for the profile response from your server Periodic Polling : Unlike long polling, you could also make a specific number of periodic requests [ say every 3 seconds ] to check if your backend has received the profile response or not and accordingly stop the polling as soon as you receive the response.

WebSocket Connection : With this approach, you establish a two-way, persistent connection between your client and the server to push the data back to the client as soon as the server receives the profile response. Unlike polling, this does not require the client to request or wait for the data. As soon as you receive the callback from Truecaller and fetch the user's profile, you can send the corresponding data to your frontend via the web socket connection. (In simpler terms, it's similar to a publish-subscribe system).

Truecaller app present and registration completed on Truecaller app

Ensure that the Truecaller app is present on your device and you have completed the profile creation step on Truecaller app. Open your mobile website and initiate the Truecaller verification flow. The user should see the Truecaller profile dialog. Click on continue to complete the verification flow and ensure that the verification is completed.

Truecaller app present but registration not completed on Truecaller app

Ensure that the Truecaller app is present on your device but you have not completed the profile creation step on Truecaller app. Open your mobile website and initiate the Truecaller verification flow. The user should see not the Truecaller profile dialog, and the user should ideally be redirected to your alternate verification flow.

Truecaller app not present on the device

Remove the Truecaller app from your device. Open your mobile website and try to initiate the Truecaller verification flow. The user should see not the Truecaller profile dialog and should be taken to either your alternate verification flow.

Ensure that you receive proper responses on your callback URL

Initiate the Truecaller verification flow in your mobile website ( Truecaller app should be present on device ) to invoke the Truecaller profile dialog. One by one, try the following scenarios and ensure that you should receive the appropriate response from Truecaller's backend stating the corresponding message as described below : - Click on 'Continue' button.

- Press the system back button - Click on 'Use another mobile number' OR 'Skip' on the truecaller dialog

We also recommend that you go through the to go through some of the commonly asked questions.

To ensure the authenticity of interactions between your web app and Truecaller, you need to generate an app key [ partner key ] from Truecaller developer account ( ) by adding your app name, domain and a callback URL.

To generate a new app key for your mobile website, go to the 'MANAGE APPS' section on the developer account dashboard and click on 'CREATE APP'. Select 'Web' in the App type and continue to enter your app details.

App domain corresponds to the domain link of your website

Callback URL corresponds to an endpoint on your backend where we will post the access token for you to fetch the user's profile. Every access token can be used to fetch the profile only of the related user granting the authorization to your app.

Once you input your app details and create the app, you will be able to see a unique "appKey" for your app which you need to include in your project to authorise all verification requests.

Once the user approves the verification on your app with their Truecaller profile ( by clicking the 'Continue' button on the dialog ), we will immediately post the user's accessToken and the requestID to your Callback endpoint. The sample response format would look like below :

Here, the request ID is the same string which you had earlier passed on in the deep link 'requestNonce' parameter. This parameter acts as a request-response correlation identifier and can be used by you to identify the correct source of the request. Once you receive the user's access token at your backend, you can fetch the respective user profile by making an API call to the endpoint that you receive in the above response in the following format :

Header Authorisation Parameters:

Get User Profile

Sample User Profile Response

Response Codes

• 200 OK

• 401 Unauthorised - If your credentials are not valid

• 5xx Server error - Any other error

Please note, in case users do not wish to share their Truecaller profile ( by dismissing Truecaller profile dialog ), you'll receive a user reject error response on your callback endpoint. The sample format for the same would look as below :

Quick guide on how to properly track and instrument funnel for the verification flow of users via Truecaller on your mobile website

For proper tracking of the verification funnel via Truecaller on your app, you should implement tracking events for the following states :

1. Total users coming to your verification flow.

2. Number of cases when the Truecaller app is present on your device - can be appropriately known using the javascript condition as described in the invoking verification section.

3. Number of users who proceed with this flow and click Continue on the Truecaller dialog [ for these cases, you receive a success response with user's access token on the callback URL configured by you ]. For details, refer here.

4. Number of cases where you received any error, where you receive an error response with 'user_rejected' message on the callback URL configured by you. For details, please refer here.

5. Number of successful profiles fetched by your backend post receiving the access token from Truecaller's backend on your callback URL. For details, refer here.

6. Number of successful communications between your backend and frontend post fetching the user's profile information to complete the verification flow.