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.0+ (iOS native SDK is consumed via Swift Package Manager)
• iOS 17.0+
• Android API 26+ (minSdkVersion 26, compileSdkVersion 35, Android Gradle Plugin 8.6+)
• CocoaPods 1.12+ (iOS)

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

The native Freshdesk iOS SDK is consumed as a Swift Package via the podspec's spm_dependency helper (React Native 0.75+). Enable dynamic frameworks and set the deployment target in your Podfile, then install:

platform :ios, '17.0'
use_frameworks! :linkage => :dynamic

cd ios && pod install

CocoaPods resolves and links the FreshdeskSDK Swift Package automatically. On React Native < 0.75 the podspec falls back to a vendored xcframework, so older apps keep working without changes.

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 is the reference wiring. Full steps: Installation → Push Notifications.

SDK information

const version = await FreshdeskSDK.getSDKVersion();

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

• Installation
• Initialization
• API Reference
• Troubleshooting

License

MIT

Support

• Email: [email protected]
• Support Portal
• Report an issue