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 :
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 :
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.
Please note that the Truecaller verification flow for mobile websites is currently supported for browsers on Android OS only. You can gracefully handle invoking Truecaller SDK only on Android and not iOS, by using either of the below to detect the iOS platform:
1) Looking for User Agent
var iOS = /iPad|iPhone|iPod/.test(navigator.userAgent) && !window.MSStream;
2) Another way is relying on navigator.platform:
var iOS = !!navigator.platform && /iPad|iPhone|iPod/.test(navigator.platform);
iOS will be either true or false
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.
As a good practice, we recommend you to implement periodic polling with 5 polling cycles at an interval of 3 seconds each.
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).
Please note that once users click 'Continue' on the Truecaller profile dialog, the entire verification process might take a few seconds to complete. This includes the time taken for your backend to receive the access token callback and then fetch the user's profile info and then finally send it to your client. As a good practice, we recommend you to show proper wait message (and a loader) to your users so that they are aware on the progress and ensure that they don't feel stuck.
For example, you may refer to some implementations .
Also, for a scenario when a user sees the Truecaller verification screen, but doesn't takes any action before the configured timeout has elapsed, your implementation may treat this UX behaviour in the same way as you would treat the absence of Truecaller app on the device, and invoke an alternate custom flow.
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 :
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.
NOTE : The minimum length of the request ID parameter should be 8 characters and maximum length can be 64 characters
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 :
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 :
Please note that for using the hex codes of any color in the deep link parameter, you need to add %23 before your hexcode. For example: if you are using hex code for #F75D34, then in the deep link you need to configure the value %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 :
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 :
"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.
If you haven't already completed for your app, we recommend you to complete that first before proceeding with the integration.
Language | locale value to use |
english | en |
hindi | hi |
marathi | mr |
telugu | te |
malayalam | ml |
urdu | ur |
punjabi | pa |
tamil | ta |
bengali | bn |
kannada | kn |
swahili | sw |
arabic | ar |
string to use | "loginPrefix" parameter value |
To get started | getstarted |
To continue | continue |
To place order | placeorder |
To complete your order | completepurchase |
To checkout | checkout |
To complete your booking | completebooking |
To proceed with your booking | proceedwithbooking |
To continue with your booking | continuewith |
To get details | getdetails |
To view more | viewmore |
To continue reading | continuereading |
To proceed | proceed |
For new updates | newupdates |
To get updates | getupdates |
To subscribe | subscribe |
To subscribe and get updates | subscribeforupdates |
string | "loginSuffix" parameter value |
please login | login |
please signup | signup |
please login/ signup | loginsignup |
please register | register |
please sign in | signin |
please verify mobile number | verifymobile |
Footer CTA string to use | "skipOption" parameter value |
Use another number | useanothernum |
Use another method | useanothermethod |
Enter details manually | manualdetails |
Later | later |
Button text to use | "ctaPrefix" parameter value |
Use | use |
Continue with | continuewith |
Proceed with | proceedwith |
Button shape | "btnShape" parameter value |
Round | round |
Rectangle | rect |
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
Please note that the optional attributes in the user profile as defined above, wouldn't exist in the response if not updated by user
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 :
Parameter [Type] | Required | Description | Example |
Authorization | yes | Bearer {token} | Bearer WcB |
