expo-truecaller

One-tap phone verification powered by the Truecaller SDK. Android returns an OAuth authorization code for backend token exchange; iOS returns the user's Truecaller profile directly.

Installation

npx expo install expo-truecaller

Add the config plugin to your app.json / app.config.ts:

{
  "plugins": [
    [
      "expo-truecaller",
      {
        "androidClientId": "YOUR_ANDROID_CLIENT_ID",
        "iosAppKey": "YOUR_IOS_APP_KEY",
        "iosAppLink": "https://your-app-link.com"
      }
    ]
  ]
}

All fields are optional. Omit a platform's fields to skip its native setup.

This module requires a development build. It will not work in Expo Go.

Usage

Android

import { initializeAsync, verifyUserAsync, TruecallerErrorCodes } from "expo-truecaller";

const { isUsable } = await initializeAsync({
  consentMode: "bottomsheet",
  heading: "logInTo",
  theme: "dark",
});

if (isUsable) {
  try {
    const { authorizationCode, codeVerifier } = await verifyUserAsync();
    // Exchange authorizationCode + codeVerifier on your backend
    // https://docs.truecaller.com/truecaller-sdk/android/latest-oauth-sdk-3.2.1/integration-steps/integrating-with-your-backend
  } catch (e) {
    if (e.code === TruecallerErrorCodes.USER_CANCELLED) {
      // User cancelled — fall back to OTP
    }
  }
}

iOS

import { initializeAsync, requestProfileAsync } from "expo-truecaller";

const { isUsable } = await initializeAsync();

if (isUsable) {
  const profile = await requestProfileAsync();
  console.log(profile.firstName, profile.phoneNumber);
}

API

initializeAsync(options?)

Initialize the Truecaller SDK. Returns { initialized, isUsable }.

On Android, accepts optional customization options. On iOS, reads credentials from Info.plist (set by the config plugin).

verifyUserAsync(options?) — Android

Trigger the Truecaller OAuth flow. Options: scopes (defaults to ["profile", "phone"]).

Returns { authorizationCode, codeVerifier, scopesGranted, state }.

requestProfileAsync() — iOS

Request the user's Truecaller profile.

Returns { firstName, lastName, phoneNumber, countryCode, email, gender, avatarUrl, city, isVerified }.

clear()

Clear the SDK instance. Rejects any pending promise with ERR_CLEARED.

Handling errors

Import TruecallerErrorCodes for the full list.

| Code | Meaning | |------|---------| | ERR_USER_CANCELLED | User dismissed the consent screen | | ERR_USER_DISMISSED | User dismissed while loading (Android) | | ERR_USER_PRESSED_BACK | User pressed the footer button (Android) | | ERR_NOT_INSTALLED | Truecaller is not installed | | ERR_NOT_AVAILABLE | OAuth flow is not usable | | ERR_SDK_ERROR | Internal SDK error | | ERR_SDK_TOO_OLD | SDK or device not compatible | | ERR_MISSING_CLIENT_ID | Invalid partner credentials (Android) | | ERR_VERIFICATION_REQUIRED | Additional verification required (Android) | | ERR_NETWORK_FAILURE | Network error occurred (iOS) | | ERR_UNKNOWN_ERROR | Unknown Truecaller error | | ERR_NOT_INITIALIZED | initializeAsync() was not called | | ERR_PKCE_FAILED | Failed to generate PKCE verifier or challenge | | ERR_CLEARED | clear() was called while pending | | ERR_INIT_FAILED | Failed to initialize the Truecaller SDK | | ERR_VERIFICATION_FAILED | Failed to start or complete verification | | ERR_ALREADY_IN_PROGRESS | A request is already pending | | ERR_IOS_APP_KEY_MISSING | TruecallerAppKey is missing from Info.plist (iOS) | | ERR_IOS_APP_LINK_MISSING | TruecallerAppLink is missing from Info.plist (iOS) | | ERR_IOS_USER_NOT_SIGNED_IN | User is not signed in to Truecaller (iOS) | | ERR_IOS_UNAUTHORIZED_DEVELOPER | Developer account is unauthorized (iOS) | | ERR_IOS_UNIVERSAL_LINK_FAILED | Universal Link resolution failed (iOS) | | ERR_IOS_URL_SCHEME_MISSING | URL scheme not configured (iOS) |