Note: We have changed our package name from @sprinklr/chat-native-client to @sprinklrjs/chat-native-client

1) Install Sprinklr messenger**

Install Sprinklr messenger in your project using package manager (yarn/npm) as mentioned below:

yarn:

npm:

**Note: Sprinklr Messenger is restricted package so you need to configure the following registry in .npmrc for Sprinklr scoped packages:

Replace <SPR_REGISTRY_AUTH_TOKEN> with registry token provided by Sprinklr.

Note: Please raise a support ticket to tickets@sprinklr.com

2) Install Sprinklr Messenger Peer Dependencies*

Additionally install the following peer dependencies in your project as part of Sprinklr Messenger Installation:

• react-native-vector-icons

• react-native-blob-util

• react-native-image-picker

• react-native-video

• react-native-netinfo

• react-native-webview

• react-native-async-storage​

• react-native-clipboard 

• react-native-camera-roll

• react-native-permissions

• react-native-svg​

​

yarn:

npm:

* Please note that listed dependencies also need to be linked natively so it is recommended to follow their documentation for the installation.

And make sure you have the necessary dependencies, and the version should surpass the specified threshold 

• "redux": ">=4.0.0" 

• "react-native": ">=0.70.0" 

• "react-redux": ">=8.0.0" 

• "react": ">=18.2.0" 

• "redux-saga": ">=1.0.1"

• “react-native-permissions" : “>=3.6.0” 

​

In case you have the requirement to use the alternative to a specific dependency or you want to provide custom implementation of your own then refer to this section ​

3) Setup for Android

You can skip this step if your app does not support Android.

1. Link Sprinklr Messenger in your project: 

Open android/settings.gradle, and add following lines which will add Sprinklr Messenger and related dependencies to your app.

Open android/app/build.gradle, add this line

Add these lines to MainApplication.java, so that Sprinklr Messenger related packages becomes part of React Native package:

2. Add Permissions in your project: 

Include the following permissions in AndroidManifest.xml if you are supporting upload and download media functionality in messenger:

<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.DOWNLOAD_WITHOUT_NOTIFICATION" />
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />

<uses-permission android:name="android.permission.READ_MEDIA_IMAGES" /> 
<uses-permission android:name="android.permission.READ_MEDIA_VIDEO" /> 
<uses-permission android:name="android.permission.POST_NOTIFICATIONS"/> 

4) Setup for iOS

You can skip this step if your app does not support iOS.

1. Link Sprinklr Messenger in your project: 

Open Podfile, and add following lines which will add Sprinklr Messenger and related dependencies to your app:

2. Add Permissions in your project: 

Include the following permissions in info plist file if you are supporting upload and download media functionality in messenger:

Above permissions are required by Apple for all apps that access the photo library or use the camera/microphone.

​

​

5) Initialize Messenger

Sprinklr Messenger can be initialized for both unauthenticated and authenticated users:

• For Anonymous Users:

For anonymous chats you can initialize the messenger using the takeOff method. Behind the scenes we will automatically create the anonymous user for the messenger and initialize the flow for the same. Please note that the takeOff method should be called once in the application lifecycle. You can use separate methods for updating the user or various information in the messenger which are explained in other sections. For the best performance takeOff should be called at the root of the application or as early as possible in your application flow.

Note: appId, environment and locale are mandatory parameters

• For Authenticated Users: 

For authenticated chats you can initialize the messenger using takeOff method by providing user details. In this flow we will consider provided user’s information for the messenger and initialize the flow for the same. Please note that the takeOff method should be called once in the application lifecycle. You can use separate methods for updating the user or other information or may be for cleanup the messenger which are explained in other section. For the best performance takeOff should be called at the root of the application with user details or as early as possible in your application flow.

Note:

• appId, environment and locale are mandatory parameters but user object should also be passed in takeOff for authenticated chats.

• Also note that the UserID and Hash are mandatory parameters and hash should be generated for every change in user object. To know the procedure to generate hash please refer below “How to generate userHash?” 

• User details are supposed to be concatenated to form a string, separated by underscore as shown below:

•  If you don’t have a few values, you need not send anything but keep the underscores as is. For example, let’s say you don’t have profileimageUrl, there will be 2 underscores after lastName. The string will be as shown below: 

To know the procedure of how to generate Hash, please refer below.

​

• For Authenticated Custom Users: 

This step is done to create a custom user using any custom or specific attributes. In other words, it involves creating user accounts with personalized details or characteristics 
Below is the example to initiate the process with custom attributes and Hash, where you can  pass the attributes values: 

• Custom Attribute 1 

• Custom Attribute 2 

• Hash 

 Note: If you wish to implement a Custom User Authentication Flow, kindly get in touch with the Sprinklr Team to initiate discussions about the implementation process. 

​

How to generate userHash?

The userHash is a generated HMAC or Hash-based Message Authentication Code. For HMAC, Sprinklr uses the sha256 hash function. You need to generate HMAC for the following "string" of user details. User details are concatenated to form a string, separated by underscore as shown below -

So for the above example, the string for which you need to generate the hash would be

Sample code to generate HMAC is mentioned here 

​

Sample Code Generation for Javascript 

​

Note: Make sure you have the necessary dependency, and the version should be within the specified threshold 

• “crypto-js”: "<= 3.3.0”
  Refer here - crypto-js​

6) Present Messenger View

Messenger view can be presented by any of your UI controls (like FAB, Messenger Icon, Tab bar Icon etc) as per your application requirement. For presenting the messenger view create a full page messenger view like below which you can define as a scene in your navigator and present as per your use case: 

LaunchOptions should be provided when messenger need to be opened as a result of notifications etc. Payload structure will be:

7) Present InAppNotificationBanner

To display the messenger notifications to the user when user receive message/reply from support agent and app is in foreground mode then you can show the in-app notification banners at the top inside your app. 

To show in-app banner for messenger related notifications you can either use Sprinklr provided messenger notification banner or you can customize the view as per your requirement.

To use Sprinklr provided in app banner, add MessengerNotificationBanner parallel to root view of the application: 

​

To use your customized banner instead of Sprinklr provided banner you have to follow some additional steps apart from adding your banner at the top:

Register your notification handler to the messenger client so that we provide you the control of received notifications which you can use to display received message information in your custom banner:

Notification object structure will be as follows:

Step 2 - Configurations

1) Update user

User attributes can be updated by calling:

Note: UserID and Hash are mandatory parameters and hash should be generated for every change in user object. To know the procedure to generate Hash, please refer above “How to generate userHash?”  

2) Update Custom User 

Custom User attributes can be updated by calling: 

​

3) Update language

To update the user language use below function:

Sprinklr live chat supports the following languages: Arabic, Bokmal, Chinese, English, Thai, Turkish, Vietnamese, Portuguese, Spanish, Indonesian, Japanese, Korean, French. 

Few languages with limited availability are Albanian, Norwegian, Bosnian, Chinese (traditional), Chinese (honk-kong), Croatian, Czech, Danish, Dutch, Estonian, Finnish, German, Hebrew, Hungarian, Italian, Latvian, Lithuanian, Macedonian, Malayalam, Polish, Romanian, Serbian, Slovak, Slovanian, Swedish.

4) Cleanup

You can logout the user and cleanup the associated data from the application by calling cleanup

5) Customize Messenger landing screen

By default messenger view is opened with messenger home page showing all conversations but you can customize the default behaviour and can launch MessengerView with single conversation view as well. Single conversation view behavior can also be customized as explained below:

• Open single conversation view with new conversation

For your use case if you want to skip the previous conversation history and directly want to open the single conversation view with new conversation then you can open MessengerView as shown below:

• Open single conversation view with previous conversation history

If you directly want to open single conversation view with previous conversation history then you can open MessengerView as shown below:

​

​

6) Capture customer context when starting a new conversation from custom view

When chat is being opened from a custom view, sometimes you might want to capture additional context on the conversation/case. 

Example - A button called “Know More about this laptop”  near a laptop product which opens a chat with a predefined contextual welcome message - “Hi there! It looks like you are interested in buying a laptop”. At the same time, you might want to set the case custom fields indicating the “product category: laptop”, “case type: inquiry”.

To do this, 

1. Create the case custom fields and note down their field name

2. Pass conversationContext to chatInitialisationContext* when opening new conversation directly (5ea7fa9e87651f356209878f and 5eb7fa9e87651f356219348e are the two custom field names)

* Note: chatInitialisationContext is explained in previous section

​

7) Capture customer context from the application on all cases of the user

Sometimes you might want to pass some contextual information in case custom fields for new conversations started by the user. 

To do this,

1. Create the case custom fields and note down their field name. Field Name can be copied from the Sprinklr UI by navigating to Custom Fields -> Click on 3 dots -> Copy Field Name. 

2. You can pass these values in clientContext in the takeOff method called in step 5.  (5e281d040844e435b is the custom field name)

You can also update the client context on run time by calling the following method:

8) Update Conversation Context (Case Custom Field) on Demand 

At times you might want to update the value of conversation context/case custom field during or after a conversation.  

Example: After a purchase is made on the website you might want to set the transaction amount or id on the case for reporting. After doing this, you can attribute sales to each conversation/case.  

To do this,  

1. Create the case custom fields and note down their field name1.  

2. Whenever you want to update the case custom field, call the following JavaScript function (5e291d040844e435b is the custom field name). 

   import MessengerClient from '@sprinklrjs/chat-native-client'    MessengerClient.updateConversationContext({"context": {"5e291d040844e435b": ["Custom Field Value"]}})

   ​

9) Update the profile context within Profile Custom Fields

When chat is being opened from a custom button or hyperlink, sometimes you might want to capture some context on the profile/user during the conversation or after the conversation. To do this, 

1. Create the profile custom fields and note down their field name 

2. Whenever you want to update the profile custom field, call the following JavaScript function and pass the information for profile level custom fields. 
   This can be done via sdk for updating it on-demand 

   import MessengerClient from '@sprinklrjs/chat-native-client'    MessengerClient.updateUserContext({"5e281d040844e435b": ["Custom Field Value"]})

   ​

​

10) Close Messenger

You can close messenger by

​

11) Get number of open conversations

Sometimes you might want to hide the live chat widget based on the number of open conversation. 

To do this,

1. Call the the below function to get the number of open conversations

2. Listent to the output of the above function to get the number of open conversations

​

12) Get Number of Unread Messages

You'll get notified whenever there's a change in the unread message count. It's a convenient way to stay updated on unread message counts in real-time

​

13) Add delegate to listen to external events from messenger

14) Add Messenger Analytics Handler to Listen to tracking events and screen

​

15) Add Messenger Events Listener to SDK events

The following events can be listened:

​

16) Add Events Logger to SDK Events

The provided code snippet establishes a custom logging system which can handle logging events at different levels. This setup enables us to efficiently track and manage various events within the app.

The following log levels are maintained:

​

​17) Update Theme Mode for User on demand

You can update the theme mode on demand:

Note: Upon invoking the updateThemeMode() method, a confirmation alert will prompt the user to reload the app for the changes in theme to take effect. Furthermore, the parent application should send the updated theme within the configuration while chat initialization

​

18) Configure your Status Card

Note: To get this capability enabled, please reach out to our support team at tickets@sprinklr.com, providing the live chat application ID. Status Card can be enabled only if you are using the modern skin version of live chat widget.

​

Using Status Cards, you can update your customers about the health of a key resource. This key resource could be a tool or service that they interact with frequently. By showing the status of this resource directly, customers don’t have to reach to agents repeatedly. Hence, this improves the customer experience while reducing agent workload.

​

Once status card is enabled for your Livechat widget, you can update the status card by using the following:

​

You can use the following placeholders for title and description:

a.     %%[updatedAt] --> Placeholder for formatted time

b.    %%[status] --> Placeholder for Status, mentioned below in the table as SPR_STATUS

​

19) Disable Attachments for Customer

 You can prevent customers from adding attachments in the chat by hiding the attachment icon from the chat widget.

To do this, you can pass disableAttachment:true in the takeOff method

​

20) Integrate Your Brand's Custom Header in Live Chat 

Enhance your live chat experience by incorporating your own custom header. This allows you to replace Live Chat default header with one that aligns with your brand identity, creating a consistent and seamless experience for your users. 

​

21) Implement Back Button Handling to Control Hardware Back Button 

Utilize the below method to handle the back action within your chat application. This function allows users to seamlessly navigate back to the previous screen, enhancing the overall user experience by providing intuitive and efficient navigation 

22) Close Conversation 

Use the method below to close a conversation on live chat. This feature allows brands to efficiently handle conversation endings, providing control over when and how interactions are closed. Apply this method only on the conversation screen when the case is open to ensure a seamless transition for users as conversations end. 

23) Close All Conversations 

Use the method below to close all conversation on live chat. This option is visible to users with open cases, if there are no cases or all existing cases are already closed then user will not be able to see this option.

24) Delete Conversation 

Use this method to delete a conversation in live chat. This feature allows brands to efficiently remove interactions as needed, providing control over conversation deletions.  Apply this method only on the conversation screen to manage deletions effectively. 

​

25) Delete All Conversations 

Use this method to delete all the conversations in live chat. This feature allows brands to efficiently remove interactions as needed, providing control over conversation deletions. Apply this method only on the home screen to manage deletions effectively.

26) Clear User Session

You can now enable users to clear their session details. When a user clears their session, any new conversations will be treated as if they are from a completely new user. This feature is especially useful for users interacting with your brand in public spaces or over a public network.

​

​

Step 3 - Push Notifications

For more details on mobile push notifications, please refer here

Prerequisite

1. Android: Google service.json file

2. iOS: APNS certificate (P12) along with its credentials

Note:

• Google service.json file can be different for staging/prod env

• APNS certificate (P12) and its credentials must be different for staging/prod env

• If you are testing the push notification setup on prod mobile application(iOS), plesae ensure to use test flight build

• If the Google service.json file is different sandbox/prod env and you are testing the push notification setup on prod mobile application(Android), plesae ensure to use test flight build

Configuration

To enable push notifications, please raise a support ticket to tickets@sprinklr.com with the following information:

1. Google service.json file

2. APNS certificate (P12) along with its credentials

3. Live Chat AppID

4. Partner ID

5. Env

1) Register/Unregister for push notifications

You can register the messenger for sending push notifications by providing push token received from apns/fcm as below:

You can unregister for messenger push notifications by sending empty token as below:

​

2) Handle Messenger Push Notifications

Once you have registered for messenger push notifications then you might receive notifications from your platform as well as messenger. To check if notification is messenger notification you can check as below:

Once you have identified if notification is messenger notification you need to follow certain steps to handle messenger notification as mentioned below: