Freshdesk React Native SDK

"Modern ticketing software that your sales and customer engagement teams will love." React Native wrapper for the native Freshdesk iOS and Android SDKs — customer support, live chat, and knowledge base for your React Native app.

Features

• Live chat and support home
• Knowledge base / FAQ
• Open a specific topic
• Unread message count (one-shot and real-time)
• User and ticket properties
• JWT user authentication
• User event tracking
• Content configuration / localisation
• Custom link handling
• Push notifications (configured natively in the host app)

Requirements

• React Native >= 0.75 (peerDependencies.react-native is >=0.75.0). On RN < 0.75, stay on ~1.4.3 — that is where 1.4.x already sat in practice.
• New Architecture supported. The module is backward-compatible: a TurboModule when the New Architecture is enabled, the classic bridge module otherwise. No JavaScript API or code changes are required either way.
• iOS 15.0+ — the native SDK ships as a vendored FreshdeskSDK.xcframework (no Swift Package Manager / use_frameworks! requirement).
• Android API 26+ (minSdkVersion 26, compileSdkVersion 35, Android Gradle Plugin 8.6+)
• CocoaPods 1.12+ (iOS)

Upgrading from 1.4.x? See MIGRATION.md — the iOS Podfile / Gemfile changes are the main step.

A handful of methods (resetUser, enableDebugLogs, getUnreadCount) behave slightly differently on Android vs iOS because the two native SDKs don't expose the same capability — see PLATFORM_DIFFERENCES.md before relying on their exact runtime behavior.

Installation

npm install @freshworks/react-native-freshdesk-sdk
# or
yarn add @freshworks/react-native-freshdesk-sdk

The library uses autolinking — no manual linking is required for React Native 0.60+.

iOS

Set the deployment target in your Podfile and install pods — no use_frameworks! is required (the native SDK ships as a vendored xcframework and the podspec builds it as a static framework):

platform :ios, '15.0'

cd ios && pod install

Keep use_frameworks! only if your other dependencies need it — prefer :linkage => :static. Upgrading from 1.4.x? The 1.4.x Podfile / Gemfile needs the SPM lines removed first — see MIGRATION.md.

The full guide (deployment-target pinning, embedding the framework in your app bundle, push notification setup, and troubleshooting) ships with the package — see docs/integration/installation.md (i.e. node_modules/@freshworks/react-native-freshdesk-sdk/docs/integration/installation.md once installed), or browse it without installing at unpkg.com/browse/@freshworks/react-native-freshdesk-sdk/docs/integration/installation.md.

Android

Ensure mavenCentral() is in your repositories and minSdkVersion is 26+. The native dependency (com.freshworks.sdk:freshdesk) is included automatically.

allprojects {
  repositories {
    google()
    mavenCentral()
  }
}

Documentation

You get your credentials from the Freshdesk portal: Admin Settings → Mobile Chat SDK → your SDK (token, host, sdkId). For JWT-enforced SDKs you also need a per-user jwt.

Initialization

Initialize once, as early as possible in your app lifecycle. All other methods require initialization first.

Required: token, host, and sdkId from the Freshdesk portal. Optional: locale, jwt (JWT-enforced widgets only), debugMode (Android). Push notification setup (Firebase, APNs, portal push keys) is not part of initialization — the SDK works for in-app support without push; configure push separately when you need tray notifications.

The wrapper sets hostPlatform to reactnative internally for SDK telemetry headers (x-fd-mobile-sdk); apps do not pass or configure this.

import FreshdeskSDK from '@freshworks/react-native-freshdesk-sdk';

await FreshdeskSDK.initialize({
  token: 'your-account-token',
  host: 'your-host.freshdesk.com',
  sdkId: 'your-sdk-id',
  locale: 'en',        // optional, default 'en' (applied at init only)
  jwt: 'your-jwt',     // required only for JWT-enforced SDKs
  debugMode: false,    // optional, Android only
});

Push notifications are optional. For push, the SDK must also be initialized natively at app startup because the device token arrives before the JS layer runs. See Push notifications. In-app support works without push wiring.

Launch the support experience

// Support home
await FreshdeskSDK.openSupport();

// Knowledge base / FAQ
await FreshdeskSDK.openKnowledgeBase();

// A specific topic (topicId is optional)
await FreshdeskSDK.openTopic({ topicName: 'Orders', topicId: '12345' });

// Dismiss any open Freshdesk view
await FreshdeskSDK.dismiss();

Unread count

// One-shot value
const count = await FreshdeskSDK.getUnreadCount();

// Real-time updates
const sub = FreshdeskSDK.addUnreadCountListener((event) => {
  console.log('Unread count:', event.count);
});

// Clean up when done
sub?.remove();

User and ticket properties

For non-JWT-enforced SDKs, set user properties after initialization. (Properties must be whitelisted under the linked widget's Contact/Ticket fields.)

await FreshdeskSDK.setUserProperties({
  name: 'Jane Doe',
  email: '[email protected]',
  phone: '+1234567890',
});

await FreshdeskSDK.setTicketProperties({
  subject: 'Product Enquiry',
  priority: 3,
});

// Read current user
const user = await FreshdeskSDK.getUser();

For JWT-enforced SDKs, user properties are updated through the JWT payload — see below.

JWT authentication

Freshdesk uses JSON Web Tokens to allow only authenticated users to start a conversation.

1. Pass the jwt during initialize() (mandatory for JWT-enforced SDKs).
2. Listen for user state changes.
3. Update/refresh the token with authenticateAndUpdate.

const sub = FreshdeskSDK.addUserStateListener((event) => {
  // States: 'authenticated', 'authExpired', 'notAuthenticated',
  //         'identifierUpdated', 'jwtNotPresent', 'undefined'
  console.log('User state:', event.state);
});

// Refresh or update the user with a new JWT (also updates user/ticket properties from payload)
await FreshdeskSDK.authenticateAndUpdate('new-jwt-token');

Reset user

Call on logout (or before switching accounts) to clear the user's session and data.

const result = await FreshdeskSDK.resetUser();
// { success: boolean; message?: string; error?: string }

Tracking user events

Track events to use as engagement context, triggered messages, or segmentation.

await FreshdeskSDK.trackEvent('add_to_cart', { productId: '12345', quantity: 2 });

Content configuration / localisation

Override static widget text (headers, placeholders, ticket form, privacy policy, response-time copy). Any field you omit keeps the widget default; pass {} to reset to defaults. Changes persist and take effect immediately.

await FreshdeskSDK.setContentConfiguration({
  headers: {
    chat: 'Talk to our team',
    faq: 'Help Centre',
    ticketForm: { title: 'Raise a ticket', submitBtnTitle: 'Submit' },
  },
  placeholders: {
    replyField: 'Type your reply...',
    searchField: 'Search articles...',
  },
  privacyPolicySetting: {
    privacyPolicyMessage: 'We respect your privacy',
    privacyPolicyLinkText: 'Privacy Policy',
    privacyPolicyLink: 'https://example.com/privacy',
  },
});

Custom link handler

Take control of links pressed inside the SDK (e.g. deep links).

import { Linking } from 'react-native';

const sub = FreshdeskSDK.setLinkHandler((event) => {
  if (event.url.startsWith('myapp://')) {
    // handle deep link
    return;
  }
  Linking.openURL(event.url);
});

sub?.remove();

Events and cleanup

import FreshdeskSDK, { FreshdeskEvents } from '@freshworks/react-native-freshdesk-sdk';

FreshdeskSDK.addUnreadCountListener(/* ... */);
FreshdeskSDK.addUserStateListener(/* ... */);
FreshdeskSDK.addUserCreatedListener(/* ... */); // iOS only

// Remove every listener (e.g. on unmount)
FreshdeskSDK.removeAllListeners();

// Event name constants
FreshdeskEvents.UNREAD_COUNT_CHANGED; // 'unreadCountChanged'
FreshdeskEvents.USER_STATE_CHANGED;   // 'userStateChanged'
FreshdeskEvents.USER_CREATED;         // 'userCreated'
FreshdeskEvents.ON_LINK_PRESSED;      // 'onLinkPressed'

Push notifications

Push is handled natively — there is no JavaScript push API. The host app must initialize the SDK natively at startup and forward the device token / incoming messages:

• iOS — APNs .p8 auth key, Push Notifications + Background Modes capabilities, and native init in AppDelegate.
• Android — Firebase (google-services.json), the Google Services plugin, and native init in MainApplication.onCreate() plus a FirebaseMessagingService.

The sample app in the SDK's source repository is the reference wiring (Freshworks GitHub access required: sample_app). Full steps ship with the package — see docs/integration/installation.md#push-notifications, or browse it at unpkg.com/browse/@freshworks/react-native-freshdesk-sdk/docs/integration/installation.md.

SDK information

const version = await FreshdeskSDK.getSDKVersion();

Diagnostics

Verify or debug your integration:

await FreshdeskSDK.enableDebugLogs(true);
const report = await FreshdeskSDK.runDiagnostics();
console.log(report.prettyPrinted);

On iOS this runs native structured diagnostics (FreshdeskSDK 1.3+). On Android the wrapper returns integration checks until native diagnostics parity lands — use debugMode: true and Logcat for deeper signal.

AI Integration Kit

The npm package ships an AI Integration Kit that teaches coding agents (Cursor, Claude, Copilot, Codex, Kiro) how to integrate and debug the SDK in your React Native app.

After install:

cp -R node_modules/@freshworks/react-native-freshdesk-sdk/ai-integration-kit/. /path/to/your-app/

Then ask your AI tool: "Use the freshdesk-react-native-integration skill and wire up Freshdesk support."

Canonical skill (for SDK maintainers): ai-integration-kit/ai/skills/freshdesk-react-native-integration/SKILL.md. Regenerate tool copies with npm run sync:ai-kit.

The full tool mapping and usage guide ships with the package — see ai-integration-kit/README.md (i.e. node_modules/@freshworks/react-native-freshdesk-sdk/ai-integration-kit/README.md once installed), or browse it without installing at unpkg.com/browse/@freshworks/react-native-freshdesk-sdk/ai-integration-kit/README.md.

Error handling

All methods return promises. Common error codes:

| Code | Meaning | |------|---------| | FRESHDESK_INVALID_CONFIG | Missing token / host / sdkId | | FRESHDESK_NOT_INITIALIZED | A method was called before initialize() | | FRESHDESK_INIT_ERROR | Initialization failed (credentials/network) | | FRESHDESK_NO_ACTIVITY / FRESHDESK_NO_VIEW_CONTROLLER | App not foregrounded | | FRESHDESK_AUTH_ERROR | JWT authentication failed |

Full documentation

These guides ship with the package under docs/integration/ (i.e. node_modules/@freshworks/react-native-freshdesk-sdk/docs/integration/ once installed). You can also browse them without installing, via unpkg:

• Installation
• Initialization
• API Reference
• Troubleshooting

License

MIT

Support

• Email: [email protected]
• Support Portal
• Report an issue (Freshworks GitHub access required; use the Support Portal above otherwise)