react-native-truecaller

Expo module for Truecaller SDK authentication on Android and iOS.

• Android — OAuth 2.0 with PKCE via truecaller-sdk:3.2.1
• iOS — Signed profile verification via TrueSDK
• Graceful fallback (verification_required) when Truecaller is not installed or user declines
• Typed API matching the native SDK constants exactly

Installation

yarn add github:superkalam/react-native-truecaller
# or
npm install github:superkalam/react-native-truecaller

Add the config plugin to app.config.js / app.json:

{
  "plugins": ["react-native-truecaller"]
}

Then rebuild:

npx expo prebuild --clean
npx expo run:android   # Android
npx expo run:ios       # iOS

Environment variables

Variable	Platform	Required	Description
EXPO_PUBLIC_TRUECALLER_CLIENT_ID	Android	✅	Client ID from Truecaller developer console
EXPO_PUBLIC_TRUECALLER_APP_KEY	iOS	✅	App key from Truecaller developer console
EXPO_PUBLIC_TRUECALLER_APP_LINK	iOS	✅	Universal link registered with Truecaller

Usage

import TruecallerModule, {
  type TruecallerResult,
  type TruecallerAndroidOptions,
} from 'react-native-truecaller';
import { Platform } from 'react-native';

// 1. Initialize (call once, e.g. in useEffect on mount)
TruecallerModule.initialize(
  process.env.EXPO_PUBLIC_TRUECALLER_APP_KEY ?? '',
  process.env.EXPO_PUBLIC_TRUECALLER_APP_LINK,
  Platform.OS === 'android'
    ? { footerType: 'another_method', ctaText: 'continue', consentMode: 'bottomsheet' }
    : undefined
);

// 2. Check availability
const available = TruecallerModule.isAvailable();

// 3. Request authentication
const result: TruecallerResult = await TruecallerModule.requestAuth();

if (result.type === 'verification_required') {
  // Truecaller not available — fall back to OTP
} else if (Platform.OS === 'android') {
  // result.authorizationCode, result.codeVerifier, result.state
  // Exchange authorizationCode on your server
} else {
  // result.payload, result.signature, result.requestNonce
  // Verify signed payload on your server
}

API

TruecallerModule.initialize(appKey, appLink?, androidOptions?)

Initializes the native SDK. Must be called before requestAuth().

TruecallerModule.isAvailable(): boolean

Returns true if Truecaller is installed and the OAuth flow is usable.

TruecallerModule.requestAuth(): Promise<TruecallerResult>

Launches the Truecaller consent screen. Resolves — never rejects — for expected fallback cases.

Types

TruecallerResult

Discriminated union on type:

type TruecallerResult =
  | { type: "truecaller_user"; authorizationCode: string; codeVerifier?: string; state: string }  // Android
  | { type: "truecaller_user"; accessToken?: string; payload?: string; signature?: string; requestNonce?: string; firstName: string; lastName: string; phoneNumber: string }  // iOS
  | { type: "verification_required" }  // fallback

TruecallerAndroidOptions

All fields optional — see type definitions in src/index.ts for the full list of footerType, ctaText, consentMode, and buttonShape values.

Platform support

Platform	Status
Android	✅ OAuth 2.0 + PKCE
iOS	✅ Signed profile

License

MIT