Pre Requisites 

RN v0.60 and above will be supported from Freshchat SDK v2.0.0.


Get your APP ID and APP Key

Your Freshchat account is associated with a unique APP ID and APP key which is used to integrate your mobile SDK with Freshchat.


Login to your Freshchat account as Account Owner/Admin. 

Go to Settings > Mobile SDK. You can find your APP ID and APP Key here. 



1. Add Freshchat SDK to your project

  1. Freshchat node package name is ‘react-native-freshchat-sdk’.

  2. In your react native project’s Package.json file, under dependencies add ”react-native-freshchat-sdk”: “{{latest-version}}”


For latest SDK version please refer the following link: https://www.npmjs.com/package/react-native-freshchat-sdk


1.1. iOS Setup

RN Version
Freshchat Version

Steps

0.60+

2.0.0+

Run below command to autolink the SDK 

cd ios 

pod install


< 0.60

2.0.0+

1. Make sure Podfile exists inside your ios project directory. If not, initialise pod inside your ios project directory and add the React dependency in your podfile. React dependencies are available below this table.

2. Then link the React native Freshchat SDK using the following command,

react-native link react-native-freshchat-sdk

< 0.60

< 2.0.0

1. Link the React native Freshchat SDK using the following command,

react-native link react-native-freshchat-sdk


2. Go to ios folder of your react native project.

3. Add an entry for FreshchatSDK as shown below in Podfile,

target 'ProjectName' do

pod 'FreshchatSDK', :path=> '../node_modules/react-native-freshchat-sdk/ios/FreshchatSDK.podspec'

end


4. Run pod install from iOS directory

0.60+

< 2.0.0

Only Freshchat SDK 2.0.0+ will be compatible with RN v0.60+.


React dependencies when RN < 0.60 & Freshchat SDK 2.0.0+

# React Native requirements
pod 'React', :path => '../node_modules/react-native', :subspecs => [
'Core',
'CxxBridge', # Include this for RN >= 0.47
'DevSupport', # Include this to enable In-App Devmenu if RN >= 0.43
'RCTText',
'RCTNetwork',
'RCTWebSocket', # Needed for debugging
'RCTAnimation', # Needed for FlatList and animations running on native UI thread
# Add any other subspecs you want to use in your project
]
# Explicitly include Yoga if you are using RN >= 0.42.0
pod 'yoga', :path => '../node_modules/react-native/ReactCommon/yoga'
pod 'DoubleConversion', :podspec => '../node_modules/react-native/third-party-podspecs/DoubleConversion.podspec'
pod 'glog', :podspec => '../node_modules/react-native/third-party-podspecs/glog.podspec'
pod 'Folly', :podspec => '../node_modules/react-native/third-party-podspecs/Folly.podspec'

Migrating an existing freshchat integration to Freshchat SDK 2.0.0+


Unlink React native Freshchat SDK from your react project using the following command. 

react-native unlink react-native-freshchat-sdk

Remove the following line from Podfile inside your iOS project. pod 'FreshchatSDK', :path=> '../node_modules/react-native-freshchat-sdk/ios/FreshchatSDK.podspec'

Refer above tabular column and choose steps as per your requirement.


1.2. Android Setup

Add maven { url "https://jitpack.io" } to your project level build.gradle file.

allprojects {
    repositories {
        .....
        maven { url "https://jitpack.io" }
    }
}

If you are using RN version < 0.60, please run below command. 

react-native link react-native-freshchat-sdk

2. Initialization of SDK

Invoke Freshchat.init() with your app id and app key before invoking/ attempting to use any other features of Freshchat SDK.  


We highly recommend invoking init() from your app's launcher / support screen launch. Freshchat SDK checks for presence of its components during init() and will warn about missing components when it detects the components are missing or their manifest entries are missing. 


Replace the YOUR-APP-ID and YOUR-APP-KEY in the following code snippet with the actual app ID and app key.

import { Freshchat, FreshchatConfig } from 'react-native-freshchat-sdk';
var freshchatConfig = new FreshchatConfig(APP_ID, APP_KEY);
Freshchat.init(freshchatConfig);


2.1 Initialization Config Options

Enable or disable features like camera capture by specifying it in the config before initialization.  

var freshchatConfig = new FreshchatConfig(APP_ID, APP_KEY);
freshchatConfig.teamMemberInfoVisible = true;
freshchatConfig.cameraCaptureEnabled = true;
freshchatConfig.gallerySelectionEnabled = true;
freshchatConfig.responseExpectationEnabled = true;
freshchatConfig.showNotificationBanner = true; //iOS only
freshchatConfig.notificationSoundEnabled = true; //iOS only
freshchatConfig.themeName = "CustomTheme.plist"; //iOS only
freshchatConfig.stringsBundle = "FCCustomLocalizable"; //iOS only
Freshchat.init(freshchatConfig);

3. User Information


3.1 Updating User Information

You can send basic user information at any point to give you more context on the user when your support agents are messaging back and forth with them. 

import { FreshchatUser } from 'react-native-freshchat-sdk';
var freshchatUser = new FreshchatUser();
freshchatUser.firstName = "John";
freshchatUser.lastName = "Doe";
freshchatUser.email = "johndoe@dead.man";
freshchatUser.phoneCountryCode = "+91";
freshchatUser.phone = "1234234123";
Freshchat.setUser(freshchatUser, (error) => {
    console.log(error);
});

3.2 Updating User Properties (Meta Data)

You can capture and send additional metadata about the user and the events in the app, all of which also becomes a way to segment your users to later push messages to them. 

/var userPropertiesJson = {
    "user_type": "Paid",
    "plan": "Gold"
}
Freshchat.setUserProperties(userPropertiesJson, (error) => {
    console.log(error);
});

3.3 Reset User Data

Reset user data at logout or when deemed appropriate based on user action in the app by invoking the resetUser API. 

Freshchat.resetUser();

3.4 Restore user

For retaining the chat messages across devices/sessions/platforms, the mobile app needs to pass the same external id and restore id combination for the user. This will allow users to seamlessly pick up the conversation from any of the supported platforms - Android, iOS and Web.


  • External Id - This should (ideally) be a unique identifier for the user from your system like a user id or email id etc and is set using the Freshchat.identifyUser() API. This cannot be changed once set for the user
  • Restore Id - This is generated by Freshchat for the current user, given an external id was set and can be retrieved anytime using the Freshchat.getUser().getRestoreId() API. The app is responsible for storing and later present the combination of external id and restore id to the Freshchat SDK to continue the chat conversations across sessions on same device or across devices and platforms.


Note
  • Restore Id for a user is typically generated only when user has sent a message.
  • Notifications are supported in only one mobile device at any point in time and is currently the last restored device or device with last updated push token


To set external id 

Freshchat.identifyUser("EXTERNAL_ID", null, (error) => {
    console.log(error);
});

To retrieve the restore id

Freshchat.getUser((user) => {
            var restoreId = user.restoreId;
            console.log("restoreId: " + restoreId);
        })

To lookup and restore user by external id and restore id

Freshchat.identifyUser("EXTERNAL_ID", "RESTORE_ID", (error) => {
    console.log(error);
});


To listen to restore id generated event

Restore Id generation is an asynchronous process. You need to listen to this event throughout your application lifecycle. Usually generation happens after user initiates a conversation.


Register for restore id generated event

Freshchat.addEventListener(
    Freshchat.EVENT_USER_RESTORE_ID_GENERATED,
    () => {
        console.log("onRestoreIdUpdated triggered");
        Freshchat.getUser((user) => {
            var restoreId = user.restoreId;
            var externalId = user.externalId;
 console.log("externalId: " + externalId);
            console.log("restoreId: " + restoreId);
        })
    }
);


3.5 Get Freshchat User ID

You can get your user's unique identifier using getFreshchatUserId() API.


Freshchat.getFreshchatUserId((data) => {
        console.log(data);
        });


4. Launching the Support Solution

Use the snippets below to launch into the FAQ or Conversation based support experience from a call to action in your app. Your call to action or entry point could be an on-screen button or a menu item.


4.1 Conversations

In response to a specific UI events like a menu selection or button on click event, invoke the showConversations() API to launch the Conversation Flow. If the app has multiple channels configured, the user will see the channel list. Channel list is ordered as specified in the Dashboard (link to channel list in dashboard) when there are no messages. When messages are present, the order is based on most recently used first 


Note

Only Message Channels with visibility set to "Visible to all users" will be displayed when using showConversations() API

 

Launching Conversation List from click of a button in your app's screen

Freshchat.showConversations();


4.1.1 Filtering Conversation Channels

To filter and display only Message Channels tagged with a specific term, use the filterByTags API in ConversationOptions instance passed to showConversations() API as below.


Eg: To link and display only specific Message Channels from say orders page in your app, those specific Message Channels can be tagged with the term "order_queries".

import { ConversationOptions } from 'react-native-freshchat-sdk';
var conversationOptions = new ConversationOptions();
conversationOptions.tags = ["premium"];
conversationOptions.filteredViewTitle = "Premium Support"; 
Freshchat.showConversations(conversationOptions);
Note
  • If no matching channel is found, the user will be redirected to default channel. 
  • Message Channels which are normally not visible when using showConversations() API, will also be displayed when tagged and the specific tag is passed to filterByTags API of ConversationOptions instance passed to showConversations() API.


4.1.2 Unread Count

If you would like to obtain the number of unread messages for the user at app launch or any other specific event, use the getUnreadCountAsync API and display the count.

Freshchat.getUnreadCountAsync((data) => {
    console.log(data);
});

The app can also choose to listen to changes to unread count when the app is open. 


Listen for unread message count event


Freshchat.addEventListener(
Freshchat.EVENT_UNREAD_MESSAGE_COUNT_CHANGED,
    () => {
        console.log("onUnreadMessageCountChanged triggered");
        Freshchat.getUnreadCountAsync((data) => {
            var count = data.count;
            var status = data.status;
if (status) {
                console.log("Message count: " + count);
            } else {
                console.log("getUnreadCountAsync unsuccessful");
            }
        });
    }
);


4.2. FAQ

In response to specific UI events like a menu selection or button on click event, invoke the showFAQs() API to launch the FAQ screen.By default the FAQ Categories is displayed as a grid with a “Contact Us” button at the bottom. For customising this, check the FAQ Options.

Freshchat.showFAQs();

4.2.1 FAQs Options

Customizations to the FAQ Flow can be achieved by specifying the relevant options in the FaqOptions instance passed to the showFAQs() API.

import { FaqOptions } from 'react-native-freshchat-sdk';
var faqOptions = new FaqOptions();
faqOptions.tags = ["premium"];
faqOptions.filteredViewTitle = "Tags";
faqOptions.filterType = FaqOptions.FilterType.ARTICLE;
Freshchat.showFAQs(faqOptions);

filteredViewTitle - title given to the result list page of the filter applied. 

tags - name of the tags based on which filter gets applied. 

filterType - Category/Article. Category - combination of articles and sub categories. Article - contains only articles.


Note

When there is no match on the filter applied, it will display all the FAQ categories by default.


4.2.2 Filtering FAQ categories by tags

To filter and display only FAQ Categories tagged with a specific term, use the filterByTags API with Filter Type as Category in FAQOptions instance passed to showFAQs() API as below.


Eg: To display FAQ Categories related to specific user type, those specific FAQ Categories can be tagged with the term "premium".

import { FaqOptions } from 'react-native-freshchat-sdk';
var faqOptions = new FaqOptions();
faqOptions.tags = ["premium"];
faqOptions.filteredViewTitle = "Tags";
faqOptions.filterType = FaqOptions.FilterType.CATEGORY;
Freshchat.showFAQs(faqOptions);


4.2.3 Filtering FAQ articles by tags

To filter and display only FAQs tagged with a specific term, use the filterByTags API with Filter Type as Article in FAQOptions instance passed to showFAQs() API as below. 


Note

FAQs also inherit the tags from the parent FAQ Category.


Eg: To link to FAQs related to payment failure, those specific FAQs can be tagged with the term "payment_failure" and can be linked to from Payments page in the app.

import { FaqOptions } from 'react-native-freshchat-sdk';
var faqOptions = new FaqOptions();
faqOptions.tags = ["premium"];
faqOptions.filteredViewTitle = "Tags";
faqOptions.filterType = FaqOptions.FilterType.ARTICLE;
Freshchat.showFAQs(faqOptions);

4.2.4 Filter Message Channels displayed on clicking "Contact Us" in FAQs by tags

To filter and display only Message Channels tagged with a specific term when user clicks "Contact Us"in FAQ screens, use the filterContactUsByTags API in FAQOptions instance passed to showFAQs() API as below.


Note

The default behaviour for "Contact Us" from within FAQ flow is same as invoking showConversations() i.e it will display all channels that are marked "Visible to all users", except when filtering of channels is enabled by passing tags to filterContactUsByTags API.


Eg: To display Message Channels related to specific section of FAQ show, those specific Message Channels can be tagged with the term "payment_failure".

import { FaqOptions } from 'react-native-freshchat-sdk';
var faqOptions = new FaqOptions();
faqOptions.tags = ["payment_failure"];
faqOptions.filteredViewTitle = "Payments";
faqOptions.filterType = FaqOptions.FilterType.ARTICLE;
faqOptions.showFaqCategoriesAsGrid = true;
faqOptions.showContactUsOnFaqScreens = true;
faqOptions.showContactUsOnFaqNotHelpful = true;
faqOptions.contactusFilterTags = ["payments"];
Freshchat.showFAQs(faqOptions);

5. Send message API

The app can send a message on behalf of the user using the sendMessage() API. 


Note

This API would silently send a message and not launch the Freshchat SDK UI


Eg: To send a message on a channel tagged "premium", the API can be invoked as below.

import { FreshchatMessage } from 'react-native-freshchat-sdk';
var freshchatMessage = new FreshchatMessage();
freshchatMessage.tag = "premium";
freshchatMessage.message = "text message";
Freshchat.sendMessage(freshchatMessage);


6. Push Notifications

Integrating Freshchat push notification in your application will help users receive your support messages quicker.


6.1.1 Server side integration


Android

In Firebase Console Under your project go to cloud messaging tab and you will see your Server Key, copy that. If you do not have a Firebase account for your application. Refer https://firebase.google.com/docs/android/setup

Save this FCM server key in Freshchat web portal under Settings -> Mobile SDK


iOS

Refer here for generating .p12 file and uploading it to Freshchat.


6.1.2 Client side integration

Please follow the below steps to integration push notifications in you mobile app. Below steps are under the assumption that your app is handing other push notifications.


Steps


1. Saving push token: Each application will have a push token. Freshchat needs this token to send push notification to user. You can use below snippet to send token to Freshchat SDK. 

Freshchat.setPushRegistrationToken(token);

2. Passing received push notification payload to Freshchat SDK.

Freshchat.isFreshchatNotification(notification, (freshchatNotification) => {
    if (freshchatNotification) {
        Freshchat.handlePushNotification(notification);
    } else {
        // handle your app notification
    }
})

6.2 Customising Notifications (Android only)

Add the below code in index.js

var freshchatNotificationConfig = new FreshchatNotificationConfig();
freshchatNotificationConfig.priority = FreshchatNotificationConfig.NotificationPriority.PRIORITY_HIGH;
freshchatNotificationConfig.notificationSoundEnabled = true;
freshchatNotificationConfig.largeIcon = "notif"; // Drawable name
freshchatNotificationConfig.smallIcon = "notif"; // Drawable name
Freshchat.setNotificationConfig(freshchatNotificationConfig);

6.3 Push Notification Checklist

We have identified some potential areas where problem happens. So we consolidated those into checklists, check if you have done everything.


iOS

1. Make sure you have uploaded correct push certificate in Freschat portal.


2. Make sure that you are checking in development or production environment and upload the respective certificate in Freschat portal.


3.Don’t check in iOS simulator, since it did not have push notification capability. Check in real device.


4.Push notification capability should be enabled in your Xcode project.


5.Make sure you gave permission to push notification for your application. If not go to settings -> under your application, enable push notification.


6.Confirm you are passing on device token to the Freshchat using the following method,

Freshchat.setPushRegistrationToken(device.pushToken);


7. Under Appdelegate class make sure you have either UNUserNotificationCenter delegate methods or [UIApplicationDelegate application:didReceiveRemoteNotification:fetchCompletionHandler:] is implemented. And if UNUserNotificationCenter framework is being used, make sure delegate has been set for that.


8. Add respective react bridging codes on the push notification delegate methods.


9. Refer the codes here for plugin implementation, confirm you have implemented all the recommendations.


10. If you have Notification extension in your app, make sure its not blocking the notification.


Android

1. Make sure you have added correct FCM key of your application in Freshchat portal


2. Don’t check in emulator, which don’t have google play service enabled. Check in real device.


3. Confirm you are passing on device token to the Freshchat using the following method,

Freshchat.setPushRegistrationToken(device.pushToken);

4. Make sure you are receiving notification from FCM.


5. Refer the codes here for plugin implementation, confirm you have implemented all the recommendations


If the problem persists, try the following URL,

https://web.freshchat.com/app/api/notif_debug?convId=CONV_ID where,

CONV_ID is the conversation id of the conversation for which you did not receive notification. CONV_ID is the last numeric part of the url when you open the conversation in the browser. 

Ensure that you are logged in as Admin while opening this url. It will give you the reason behind the push notification failure.


7. Other Notes

For Localisation, UI customisation, RTL support and more refer our platform specific documentation for Android and iOS.