TABLE OF CONTENTS

Pre Requisites 

Get your APP ID, APP Key, and Domain

1. Adding the Freshchat SDK to your project

1.1. iOS Setup

1.2. Android Setup

2. Initialization of SDK

2.1 Initialization Config Options

3. User Information

3.1 Updating User Information

3.2 Updating User Properties (Meta Data)

3.3 Reset User Data

3.4 Restore user

3.5 Get Freshchat User ID

4. Launching the Support Solution

4.1 Conversations

4.1.1 Filtering Conversation Topics

4.1.2 Unread Count

4.2. FAQ

4.2.1 FAQs Options

4.2.2 Filtering FAQ categories by tags

4.2.3 Filtering FAQ articles by tags

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

5. Send message API

6. Push Notifications

6.1.1 Server side integration

6.1.2 Client side integration

6.2 Customising Notifications (Android only)

6.3 Push Notification Checklist

7. Other Notes


Pre Requisites 

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


Get your APP ID, APP Key, and Domain

  • Your Freshchat account is associated with a unique APP ID and APP key which you can use to integrate your mobile SDK with Freshchat .
  • Login to your Freshchat account as Account Owner/Admin > navigate to Admin > Mobile SDK. You can find your APP ID, APP Key and Domain here. 




1. Adding the Freshchat SDK to your project

  • The Freshchat node package name is ‘react-native-freshchat-sdk’.
  • In your react native project’s Package.json file, under dependencies add ”react-native-freshchat-sdk”: “{{latest-version}}”
  • For the latest SDK version please refer to 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);
freshchatConfig.domain = "YOUR-DOMAIN";
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.domain = "YOUR-DOMAIN";
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 Topics configured, the user will see the Topics list. The Topics list is ordered as specified in the Dashboard (link to the Topics list in dashboard) when there are no messages. When messages are present, the order is based on most recently used first 



Note: Only Topics 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 Topics

To filter and display only Topics 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 Topics from say orders page in your app, those specific Topics 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 Topic is found, the user will be redirected to the default Topic. 
Topics 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.1.3 Unread message count across conversations filtered by tags


If you would like to obtain the number of unread messages for the user across specific conversations filtered by tags, use the getUnreadCountAsync API.


const getUnreadCountAsyncForTags = () => 
{
    Freshchat.getUnreadCountAsync(
{
            tags: ["new", "test"]
        },
        (data) => 
{
            console.log(data);
        });
};


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 Topics displayed on clicking "Contact Us" in FAQs by tags

To filter and display only Topics 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.


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



Eg: To display Topics related to specific section of FAQ show, those specific Topics 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 Topic 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. You can also refer to the Firebase setup documentation here: https://firebase.google.com/docs/android/setup

  • Save this FCM server key in Freshchat web portal under Admin -> 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


  • 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);


  • 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 Admin -> 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://<<your-freshchat-account-domain-here>>/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.