Getting Started

Prerequisites

SDK Requirements

1. Login to your account as Account Owner/Admin.
2. Go to Admin > Mobile SDK. You can see your app id, app key, and domain here.

Platform Requirements

  • Freshchat Android SDK clients require devices running Android 4.1(API level 16) or higher
  • Freshchat Android SDK supports apps running Android version 7.0 with appcompat-v7 r24.2 or later

Proguard Configuration

Freshchat Android SDK is configured to support proguard. If Proguard is enabled on your app, no manual configuration is required as it automatically picks up the configuration required for the SDK.

Permissions

Freshchat Android SDK is built with support for the Run Time/Dynamic Permissions Model introduced in Marshmallow as long as the app is built with targetSdk as Marshmallow or later.

Add SDK

Add Freshdesk Messaging Android SDK to your project.

1. Add the maven URL to the root build.gradle (project/build.gradle). Ensure that you open the build.gradle file for the app module.

project/build.gradle
Copied Copy
1
2
3
4
5
allprojects { repositories { maven { url "https://jitpack.io" } } }
EXPAND ↓

2. Add the following dependency to your app module's build.gradle file (project/app/build.gradle):

project/app/build.gradle
Copied Copy
1
2
3
4
5
6
7
8
apply plugin: 'com.android.application' android { // ... } dependencies { // ... implementation 'com.github.freshworks:freshchat-android:{{latest-version}}' }
EXPAND ↓

Replace {{latest-version}} with the latest version of the SDK from here.

Example: implementation 'com.github.freshworks:freshchat-android:4.2.0

3. If the app targets Android 7.0+ and Image attachment is enabled, configure the FileProvider by adding it to AndroidManifest.xml.

AndroidManifest.xml
Copied Copy
1
2
3
4
5
6
7
8
9
<provider android:name="androidx.core.content.FileProvider" android:authorities="com.example.demoapp.provider" android:exported="false" android:grantUriPermissions="true"> <meta-data android:name="android.support.FILE_PROVIDER_PATHS" android:resource="@xml/freshchat_file_provider_paths" /> </provider>
EXPAND ↓
Strings.xml
Copied Copy
1
<string name="freshchat_file_provider_authority">com.example.demoapp.provider</string>
EXPAND ↓

4. Select File > Sync Project to save the file and integrate the SDK in the project.

Initialize SDK

Invoke Freshchat.init() with your app id, app key, and domain before invoking any other features of Freshdesk Messaging SDK. We recommend you to invoke init() from your app's launcher/support activity's onCreate() function. Freshdesk Messaging SDK checks for the presence of its components during init() and warns about missing components.

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

FreshchatConfig config = new FreshchatConfig("YOUR-APP-ID","YOUR-APP-KEY");
freshchatConfig.setDomain("YOUR-DOMAIN");
Freshchat.getInstance(getApplicationContext()).init(config);

Note: In shared preferences (Android)/keychains in iOS), account-sensitive information is stored. Any changes or deletions you make in the folder may cause the SDK to malfunction. For example, channels and FAQs will not load and instead, a continuous loading indicator will display.

Configuring the SDK

Enable or disable features like camera capture before initialization.

Copied Copy
1
2
3
4
5
6
7
8
FreshchatConfig config = new FreshchatConfig("YOUR-APP-ID","YOUR-APP-KEY"); config.setDomain("YOUR-DOMAIN"); config.setCameraCaptureEnabled(true); config.setGallerySelectionEnabled(true); config.setResponseExpectationEnabled(true); config.setTeamMemberInfoVisible(true); config.setUserEventsTrackingEnabled(true); Freshchat.getInstance(getApplicationContext()).init(config);
EXPAND ↓

Note: In shared preferences (Android)/keychains in iOS), account-sensitive information is stored. Any changes or deletions you make in the folder may cause the SDK to malfunction. For example, channels and FAQs will not and instead, a continuous loading indicator will display.

Manage User Information

Managing user information with JWT authentication

Freshdesk Messaging uses JSON Web Token (JWT) to allow only authenticated users to initiate a conversation through the Freshdesk Messaging messenger. It sends a callback (along with the user’s authentication status) to let you know about any event with respect to the messenger and user’s authentication status. Once the user is authenticated on your system and tries to initiate a conversation, your system communicates the encrypted key to Freshdesk Messaging to allow or restore conversations. This way, the authenticated user can engage in a secure conversation until the end of a session. This also prevents any third party from impersonating your users.

You can manage both logged-in and anonymous users. The following table provides the Freshdesk Messaging specific properties in JWT token.

Attribute Description
freshchat_uuid

Freshchat UUID is the UUID provided by Freshdesk Messaging SDK.

This value can be obtained using the below API every time before generating a JWT Token.

Android:

Freshchat.getInstance(getContext()).getFreshchatUserId();

iOS:

[[Freshchat sharedInstance] getFreshchatUserId];

reference_id

Reference Id is the uniquely identifiable information of the user in your system. Eg. userId, email, etc

With reference_id, you can restore the user's conversation history across multiple sessions and platforms.

Managing a restorable JWT user

You can restore user conversations for logged-in users, every time they initiate a conversation from a different browser or device. Restorable user JWT Token should contain reference_id and freshchat_uuid.

Example
Copied Copy
1
2
3
4
{ "freshchat_uuid": "6bc903d6-12ba-11eb-adc1-0242ac120002", "reference_id": "sample_user" }
EXPAND ↓

Restoring a restorable User

To create or restore a restorable user, restore the user API.

Copied Copy
1
Freshchat.getInstance(getContext()).restoreUser("JWT_TOKEN");
EXPAND ↓

Updating user properties of a restorable user

To update user properties of a restorable user, use setUser API:

Sample JWT payload:
Copied Copy
1
2
3
4
5
6
7
8
9
{ "first_name": "Duraivel", "last_name" : "P", "custom_prop1": "value1", "freshchat_uuid": "6bc903d6-12ba-11eb-adc1-0242ac120002", "reference_id": "refId123456" } Freshchat.getInstance(getContext()).setUser("JWT_TOKEN");
EXPAND ↓

Managing an anonymous JWT user

Anonymous users are temporary users. They are mostly created to have chat sessions before login. Note that the conversations of anonymous users cannot be restored. Also, Anonymous user JWT Token should contain freshchat_uuid.

Example:
Copied Copy
1
2
3
{ "freshchat_uuid": "6bc903d6-12ba-11eb-adc1-0242ac120002" }
EXPAND ↓

Creating an anonymous User

To create an anonymous user, use setUser API.

Copied Copy
1
Freshchat.getInstance(getContext()).setUser("JWT_TOKEN");
EXPAND ↓

Updating user properties of an anonymous user

To update the user properties of an anonymous user, use setUser API.

Sample JWT payload:
Copied Copy
1
2
3
4
5
6
7
8
{ "first_name": "Duraivel", "last_name" : "P", "custom_prop1": "value1", "freshchat_uuid": "6bc903d6-12ba-11eb-adc1-0242ac120002" } Freshchat.getInstance(getContext()).setUser("JWT_TOKEN");
EXPAND ↓

Managing JWT users with expiry

JWT token has an unlimited lifetime by default. If you want to add expiry to JWT token, add exp property to your JWT token. Note that exp value should be in seconds.
Sample exp key & value
"exp" : 1603191000

JWT Token Statuses and their SDK behavior

JWT Token status helps you identify the current status of the token provided to SDK. It can be one of the following:

Status Description SDK Behaviour
TOKEN_NOT_SET This will be the initial status of the token before any token is set. The sser will not see chat/FAQ content. SDK will wait for 30 seconds for the app to provide a valid token.
If not provided, the user will be pushed out of the SDK screen.
TOKEN_NOT_PROCESSED This will be the status when the token is provided to SDK and SDK is processing it. The users will not be shown chat / FAQ content. SDK waist for 30 seconds for token to be valid.
If not, the user will be pushed out of SDK screen.
TOKEN_VALID When provided token is valid. The user will be able to use SDK.
TOKEN_INVALID When token is invalid. The user will not be able to open SDK screens. If the user is accessing an SDK screen, they will be pushed out.
TOKEN_EXPIRED When token has expired.

The user will not see chat / FAQ content. SDK will wait for 30 seconds for the app to provide valid token.
If not provided, user will be pushed out of SDK screen.

If user is in the middle of a valid session, chat / FAQ content will be shown. SDK will wait for 30 seconds for the app to provide new valid token. If not provided, user will be pushed out of SDK screen

Use the following code to get current JWT token status:

Android
Copied Copy
1
Freshchat.getInstance(getContext()).getUserIdTokenStatus();
EXPAND ↓

Listening to JWT Token status changes

Android

You can listen to token status changes by listening to Freshchat.FRESHCHAT_EVENTS broadcast event. We recommend you to register in onCreate and unregister in onTerminate of your application class.

Registering receiver
Copied Copy
1
2
IntentFilter freshchatEventsIntentFilter = new IntentFilter(Freshchat.FRESHCHAT_EVENTS); LocalBroadcastManager.getInstance(getApplicationContext()).registerReceiver(freshchatEventsReceiver, freshchatEventsIntentFilter);
EXPAND ↓
Getting token status when event is triggered
Copied Copy
1
2
3
4
5
6
7
8
9
10
BroadcastReceiver freshchatEventsReceiver = new BroadcastReceiver() { @Override public void onReceive(Context context, Intent intent) { Event event = Freshchat.getEventFromBundle(intent.getExtras()); if (event.getEventName() == Event.EventName.FCEventIdTokenStatusChange) { Log.e("FreshchatTest", "Token status - " + Freshchat.getInstance(getApplicationContext()).getUserIdTokenStatus()); } } };
EXPAND ↓
Unregister receiver
Copied Copy
1
LocalBroadcastManager.getInstance(getApplicationContext()).unregisterReceiver(freshchatEventsReceiver);
EXPAND ↓
iOS

You can listen to token status changes by listening to FRESHCHAT_EVENTS in notification center. We recommend you to add observer in viewWillAppear and remove observer in viewWillDisappear of your UIViewController.

Registering receiver
Copied Copy
1
2
3
4
5
[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(userActionEvent:) name:FRESHCHAT_EVENTS object:nil];
EXPAND ↓
Getting token status when event is triggered
Copied Copy
1
2
3
4
5
6
(void) userActionEvent:(NSNotification *)notif { FreshchatEvent *fcEvent = notif.userInfo[@"event"]; if(fcEvent.name == FCEventIdTokenStatusChange){ NSString *tokenStatus = [[Freshchat sharedInstance] getUserIdTokenStatus]; } }
EXPAND ↓
Unregister receiver
Copied Copy
1
2
3
4
[[NSNotificationCenter defaultCenter] removeObserver:self name:FRESHCHAT_EVENTS object:nil];
EXPAND ↓

Managing user information without JWT authentication

Pass user information

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

Copied Copy
1
2
3
4
5
6
7
8
9
// Get the user object for the current installation FreshchatUser freshchatUser = Freshchat.getInstance(getApplicationContext()).getUser(); freshchatUser.setFirstName("John"); freshchatUser.setLastName("Doe"); freshchatUser.setEmail("john.doe.1982@mail.com"); freshchatUser.setPhone("+91", "9790987495"); // Call setUser so that the user information is synced with Freshchat's servers Freshchat.getInstance(getApplicationContext()).setUser(freshchatUser);
EXPAND ↓

Update user properties

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

Copied Copy
1
2
3
4
5
6
7
8
9
10
11
/* Set any custom metadata to give agents more context, and for segmentation for marketing or pro-active messaging */ Map<String, String> userMeta = new HashMap<String, String>(); userMeta.put("userLoginType", "Facebook"); userMeta.put("city", "SpringField"); userMeta.put("age", "22"); userMeta.put("userType", "premium"); userMeta.put("numTransactions", "5"); userMeta.put("usedWishlistFeature", "yes"); //Call setUserProperties to sync the user properties with Freshchat's servers Freshchat.getInstance(getApplicationContext()).setUser(userMeta);
EXPAND ↓

Sync user information across devices

For retaining the chat messages across devices/sessions/platforms, the mobile app needs to pass the same unique identifiers for the users. This allows users to seamlessly pick up the conversation from any supported platforms - Android, iOS, and Web.

To sync user information, you need the following parameters/attributes.

Parameter Description
externalId

A unique identifier for the user from your system like a user id or email id.

Note: Once set, you cannot change this.

restoreId

This is generated by Freshdesk Messaging for the current user.

The app stores and presents the combination of external id and restore id to the Freshdesk Messaging SDK to continue the conversations across sessions on the same device or across devices and platforms.

Saving the conversations

1.To set the external id (if not set already):
Copied Copy
1
Freshchat.getInstance(getApplicationContext()).identifyUser(externalId, null);
EXPAND ↓
2.To listen to restore id generated event:

Restore Id generation is an asynchronous process. So, you need to register a broadcast receiver to get notifications when it is generated. You can register at onCreate and unregistered at onTerminate of your application class.

Note: Restore ID will be generated only after the user starts a conversation. So, make sure this is not invoked on the app before any user reaches for help.

a. Register for broadcast receiver
Copied Copy
1
2
IntentFilter intentFilter = new IntentFilter(Freshchat.FRESHCHAT_USER_RESTORE_ID_GENERATED); LocalBroadcastManager.getInstance(getApplicationContext()).registerReceiver(broadcastReceiver, intentFilter);
EXPAND ↓
b. Listen to broadcast receiver
Copied Copy
1
2
3
4
5
6
BroadcastReceiver broadcastReceiver = new BroadcastReceiver() { @Override public void onReceive(Context context, Intent intent) { String restoreId = Freshchat.getInstance(getApplicationContext()).getUser().getRestoreId(); } };
EXPAND ↓
c. Unregister broadcast receiver
Copied Copy
1
LocalBroadcastManager.getInstance(getApplicationContext()).unregisterReceiver(broadcastReceiver);
EXPAND ↓
3. To save restore id
Copied Copy
1
saveRestoreIdForUser(restoreId);
EXPAND ↓

Note:Make sure to save the restoreID on your server to retrieve conversations later.

Now all the conversations are mapped to the exteralid and restoreid.

Retrieving conversations

You can use the app to retrieve saved conversations in the following scenarios:

  • When the user uninstalls/reinstalls the app
  • When the user logs out and logs into the same app
  • When the user switches across devices, OS, or, platforms

To lookup and restore user by external id and restore id:
Copied Copy
1
Freshchat.getInstance(getApplicationContext()).identifyUser(externalId, restoreId);
EXPAND ↓

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

Reset user data

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

Note: Ensure that you call this function whenever your users log out. Otherwise, conversations will be visible to the newly logged-in user too.
Copied Copy
1
Freshchat.resetUser(getApplicationContext());
EXPAND ↓

Log user events in timeline

Tracking user events provides more insight and context about the user(s) in your application. Events like user actions, failure/error cases can be tracked using this API. Tracked events are listed under Events Timeline on the agent side. (Available from version 3.1.0)

Copied Copy
1
2
3
4
5
6
7
8
9
10
String eventName = "Visited Order Details page"; // Create a map and set required properties like below HashMap<String, Object> properties = new HashMap<>(); properties.put("Order Id", 3223232332); properties.put("Order Date", "24 Jan 2020"); properties.put("Order Status ", "In-Transit"); // Call trackEvent by passing eventName and a map of properties Freshchat.trackEvent(getContext(), eventName, properties);
EXPAND ↓

Notes:
1. Freshdesk Messaging allows only 121 unique events per account.
2. Event name accepts string value (max 32 chars).
3. Property key name should be of string type (max 32 chars).
4. Property value can be of any primitive object type (max 256 chars).
5. Freshdesk Messaging allows you to send a maximum of 20 properties per event.


Handle push notifications

Integrating Freshdesk Messaging push notification in your application helps users receive your support messages quicker.

Connecting Freshdesk Messaging with Firebase Cloud Messaging (FCM)

Prerequisites

Before you proceed, make sure that you do the following:

  • Implement FCM in your app
  • Device runs Play Services
  • Save FCM Server Key in Freshdesk Messaging web portal

Saving FCM server key in Freshdesk Messaging web portal

Get your Application's Firebase FCM server key and save it in the Freshdesk Messaging web app under Admin > Mobile SDK > FCM Server key.

Sending the device registration token to Freshdesk Messaging

Note: Before proceeding, ensure to push registration token to Freshdesk Messaging SDK

Copied Copy
1
2
String token = FirebaseInstanceId.getInstance().getToken(); Freshchat.getInstance(this).setPushRegistrationToken(token);
EXPAND ↓

Handling messages

When you implement FirebaseMessagingService, pass the RemoteMessage object to Freshdesk Messaging if it is a Freshdesk Messaging notification.

Copied Copy
1
2
3
4
5
6
7
8
public void onMessageReceived(RemoteMessage remoteMessage) { if (Freshchat.isFreshchatNotification(remoteMessage)) { Freshchat.handleFcmMessage(context, remoteMessage); } else { // Handle notifications with data payload for your app } }
EXPAND ↓

To troubleshoot any issues with push notifications, check Fixing broken Android push notifications.

Customizing Notifications

You can customize the notifications that the app can receive for agent replies to chat. These notifications contain details like icons, agent messages, app names, etc. Freshdesk Messaging SDK supports customizing the following for notifications.

1. Notification Icon (Small Icon and Large Icon): App icon is used as the default for the small icon if not set explicitly.
2. Notification Sound: Enable or disable notification tone. By default it is disabled.
3. Notification Priority: Priority for notifications in below Android 8.0 devices. Default is NotificationCompat.PRIORITY_DEFAULT.
4. Notification Importance: Importance for notifications in Android 8.0+ devices. Default is NotificationManagerCompat.IMPORTANCE_DEFAULT. This can be modified to show Heads up Notifications.
5. Activity to launch on up navigation from the messages screen launched from notification. The messages screen will have no activity to navigate to the backstack when it is launched from notification. Specify the activity class name to be launched.
6. For specifying the accent color of the circle behind the small icon in a notification.

Copied Copy
1
<color name="freshchat_notification_accent_color">@color/red</color>
EXPAND ↓

7. On Oreo and later versions of Android, you can customize the notification channel name used to deliver notifications by overriding the string as below.

Copied Copy
1
<string name="freshchat_campaign_notification_channel_name">Campaign messages</string>
EXPAND ↓
Example:
Copied Copy
1
2
3
4
5
6
7
FreshchatNotificationConfig notificationConfig = new FreshchatNotificationConfig() .setNotificationSoundEnabled(true) .setSmallIcon(R.drawable.ic_notif_small_icon) .setLargeIcon(R.drawable.ic_notif_large_icon) .launchActivityOnFinish(MainActivity.class.getName()) .setPriority(NotificationCompat.PRIORITY_HIGH); Freshchat.getInstance(getApplicationContext()).setNotificationConfig(notificationConfig);
EXPAND ↓

Android Oreo Support

Freshdesk Messaging supports Notification channels out of the box in Oreo or later. It automatically creates a notification channel for conversation messages.

Note: If you haven't integrated FCM, follow the instructions here and continue from 3.

Display FAQs

Invoking FAQs

In response to specific UI events like a menu selection or button click event, you can invoke the showFAQs() API to launch the FAQ screen. By default, the FAQ categories are displayed as a grid with a “Contact Us” button at the bottom. You can use the available FAQ options to customize how it looks.

Copied Copy
1
2
3
4
5
6
myFAQButton.setOnClickListener(new OnClickListener() { @Override public void onClick(View view) { Freshchat.showFAQs(getApplicationContext()); } });
EXPAND ↓

Customizing FAQ Flow

You can customize the FAQ flow using the FaqOptions instance in showFAQs() API. The FAQs are typically the solution articles categories you build in the Knowledge Base.

Example: To launch the FAQ from the click of a button in your app screen, use the following:
Copied Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
myFAQButton.setOnClickListener(new OnClickListener() { @Override public void onClick(View view) { FaqOptions faqOptions = new FaqOptions() .showFaqCategoriesAsGrid(true) //To display the FAQ categories as list, set the value as false. .showContactUsOnAppBar(true) // To hide Contact us from the app bar, set the value as true. .showContactUsOnFaqScreens(false) //To show Contact us on FAQ screen, set the value as true. .showContactUsOnFaqNotHelpful(false); //To show Contact us on FAQ feedback, set the value as true Freshchat.showFAQs(MainActivity.this, faqOptions); } });
EXPAND ↓

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 a category in the FAQ Options instance in showFAQs() API.

Example: To display FAQ Categories related to specific user type, tag the categories with the term "premium".
Copied Copy
1
2
3
4
5
6
7
List<String> tags = new ArrayList<>(); tags.add("premium"); FaqOptions faqOptions = new FaqOptions() .filterByTags(tags, "FAQs", FaqOptions.FilterType.CATEGORY);//tags, filtered screen title, type Freshchat.showFAQs(MainActivity.this, faqOptions);
EXPAND ↓

Filtering FAQ articles by tags

To filter and display FAQ articles tagged with a specific term, use the filterByTags API with Filter Type as Article in FAQOptions instance in showFAQs() API.
Note: FAQs also inherit the tags from the parent FAQ Category.

Example: To link FAQs related to payment failure, tag the specific FAQs with the term "payment_failure" and link it to the Payments page in the app.
Copied Copy
1
2
3
4
5
6
7
List<String> tags = new ArrayList<>(); tags.add("payment_failure"); FaqOptions faqOptions = new FaqOptions() .filterByTags(tags, "payment_failure", FaqOptions.FilterType.ARTICLE);//tags, filtered screen title, type Freshchat.showFAQs(MainActivity.this, faqOptions);
EXPAND ↓

Filter topics in FAQs by tags

You can make specific topics appear for customers when they click on Contact Us option from the FAQ screen. For this, use the filterContactUsByTags API in FAQOptions instance in showFAQs() API.

Example: To display all topics related to payment failure, tag the topics with the the term "payment_failure".
Copied Copy
1
2
3
4
5
6
7
8
List<String> tags = new ArrayList<>(); tags.add("payment_failure"); FaqOptions faqOptions = new FaqOptions() .filterContactUsByTags(tags, "Payments"); //tags, filtered screen title Freshchat.showFAQs(MainActivity.this, faqOptions);
EXPAND ↓

Note: The default behavior for "Contact Us" from within FAQ flow is the 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.

Manage user conversations

Introduction

In response to 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 topic list. The topic list is ordered as specified in the Dashboard (link to the Topics list in the dashboard) if there are no messages. If messages exist, the order is based on the most recently interacted topics.

Note: Only Topics with visibility set to "Visible to all users" will be displayed when using showConversations() API

Launching conversation list

Copied Copy
1
2
3
4
5
6
myConversationsButton.setOnClickListener(new OnClickListener() { @Override public void onClick(View view) { Freshchat.showConversations(getApplicationContext()); } });
EXPAND ↓

Filtering Conversation Topics

To filter and display only topics tagged with a specific term, use the filterByTags API in ConversationOptions instance in showConversations() API.

Example: To link and display specific Topics from the orders page in your app, tag the Topics the term "order_queries".
Copied Copy
1
2
3
4
5
List<String> tags = new ArrayList<>(); tags.add("order_queries"); ConversationOptions options = new ConversationOptions() .filterByTags(tags, "Order Queries"); Freshchat.showConversations(MainActivity.this, options);
EXPAND ↓

Notes:

  • If no matching Topics are found, the user will be redirected to the default Topic.
  • Topics that are 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.

Displaying Unread Messages Count

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.

Note: Before using this function, ensure to set up the push notifications.

Copied Copy
1
2
3
4
5
6
7
Freshchat.getInstance(getApplicationContext()).getUnreadCountAsync(new UnreadCountCallback() { @Override public void onResult(FreshchatCallbackStatus freshchatCallbackStatus, int unreadCount) { //Assuming "badgeTextView" is a text view to show the count on badgeTextView.setText(Integer.toString(unreadCount)); } });
EXPAND ↓

Updating unread messages count

The app can also choose to listen to changes to unread count when the app is open. The way to listen to the broadcast is described below.

Registering the broadcast receiver
Copied Copy
1
2
IntentFilter intentFilter = new IntentFilter(Freshchat.FRESHCHAT_UNREAD_MESSAGE_COUNT_CHANGED); getLocalBroadcastManager(getApplicationContext()).registerReceiver(unreadCountChangeReceiver, intentFilter);
EXPAND ↓
Listening to unread count changes
Copied Copy
1
2
3
4
5
6
7
8
9
10
11
12
BroadcastReceiver unreadCountChangeReceiver = new BroadcastReceiver() { @Override public void onReceive(Context context, Intent intent) { Freshchat.getInstance(getApplicationContext()).getUnreadCountAsync(new UnreadCountCallback() { @Override public void onResult(FreshchatCallbackStatus freshchatCallbackStatus, int unreadCount) { //Assuming "badgeTextView" is a text view to show the count on badgeTextView.setText(Integer.toString(unreadCount)); } }); } }
EXPAND ↓
Unregistering the broadcast receiver
Copied Copy
1
getLocalBroadcastManager(getApplicationContext()).unregisterReceiver(unreadCountChangeReceiver);
EXPAND ↓

Displaying unread message count across conversations

To obtain the number of unread messages for the user across specific conversations filtered by tags, use the getUnreadCountAsync API.

Copied Copy
1
2
3
4
5
6
7
8
List<String> tags = new ArrayList<>(); tags.add("premium"); // Tags to filter conversations by Freshchat.getInstance(getApplicationContext()).getUnreadCountAsync(new UnreadCountCallback() { @Override public void onResult(FreshchatCallbackStatus FreshchatCallbackStatus, int unreadCount) { badgeTextView.setText(Integer.toString(unreadCount)); } }, tags);
EXPAND ↓

Note: To display unread message count, make sure that push notifications are already set up.

Localization

Language Localization

Localizing default SDK texts

All strings in SDK can be modified by overriding them in the respective locale strings.xml file. All Freshdesk Messaging texts can be found here.

For example, to change the title for the message Topics list page, include the following string in strings.xml:
Copied Copy
1
<string name="freshchat_activity_title_channel_list">Conversations</string>
EXPAND ↓

Localizing FAQs and Topics

Once FAQs and Topics are localized in the Freshdesk Messaging web app, SDK automatically updates content based on the user's app/device locale.

Right-to-Left Language Support

Freshdesk Messaging SDK supports RTL languages.

Runtime app locale change

If your app can support different locales (languages) apart from the default locale of the device, follow the steps below to update the locale in your Freshdesk Messaging SDK.

1. Once the app changes locale, notify the SDK about the app locale change.

Copied Copy
1
Freshchat.notifyAppLocaleChange(activityContext);
EXPAND ↓

2. Freshdesk Messaging internally uses webview as part of SDK. From Android OS version 7.0, webview changes locale during the webview load. To fix this, we have provided a callback method onLocaleChangedByWebView(), where you need to reset the locale again inside this function.

To implement FreshchatWebViewListener

Copied Copy
1
2
3
4
5
6
7
8
9
10
11
12
private FreshchatWebViewListener webviewListener = new FreshchatWebViewListener() { @Override public void onLocaleChangedByWebView(@NonNull WeakReference<Context> activityContext) { if (activityContext.get() == null) { return; } // Reset the run time locale here changeLocale(activityContext, appLocale); } };
EXPAND ↓

Set webview listener to Freshdesk Messaging Instance. We recommend you to do this in onCreate() of Application class.

Copied Copy
1
Freshchat.getInstance(this).setWebviewListener(webviewListener);
EXPAND ↓

UI Customization

Themes Customizations

Selecting an existing theme

Freshdesk Messaging SDK depends on appcompat-v7 for providing backward compatibility, hence all the Freshdesk Messaging themes are from Theme.AppCompat.*. To switch the theme applied to Freshdesk Messaging SDK components, change the parent of Theme.Freshchat.SelectedTheme to one of the variants of Theme.Freshchat.* in your app's styles.xml.

Example:
Copied Copy
1
<style name="Theme.Freshchat.SelectedTheme" parent="@style/Theme.Freshchat.Light.DarkActionBar" />
EXPAND ↓

Freshdesk Messaging SDK ships with Theme.Freshchat.Light and Theme.Freshchat.Light.DarkActionBar.

Create and apply a custom theme

Freshdesk Messaging SDK's theme is built on top of the Android system and supports the standard android theme attributes for items like ActionBar background color, ActionBar text color, status bar color, etc. Refer to Android Material Theme Attributes for more details.

For example, to customize colorPrimary, include the following.

Copied Copy
1
<item name="colorPrimary">@color/my_awesome_color</item>
EXPAND ↓

Customizing Text Appearance

Freshdesk Messaging SDK supports changing text appearance for several elements in the SDK. You can refer to the default styles of text appearance implementation here.

Note: TextStyles listed are standard android view styles, typically for text views, and hence textAppearance can include any customizations like textColor, textSize, etc.

Steps to customize the text appearance

1. Define custom Text Appearance as a style.

For example, MyCustomTextAppearance style is defined as:
Copied Copy
1
2
3
4
5
6
7
8
<style name="MyCustomTextAppearance" parent="TextAppearance.AppCompat.Medium"> <item name="android:textColor">@color/textColorPrimary</item> <item name="android:textColorHighlight">@color/textColorHighlight</item> <item name="android:textColorHint">@color/textColorHint</item> <item name="android:textColorLink">@color/textColorLink</item> <item name="android:textSize">16sp</item> <item name="android:textStyle">bold</item> </style>
EXPAND ↓

2. Map the Text Appearance style to a predefined Freshdesk Messaging textAppearance custom attribute.

For example, MyCustomTextAppearance style defined above is text appearance of the style freshchatChannelNameTextStyle.
Copied Copy
1
2
3
4
5
6
<style name="MyCustomTheme" parent="Theme.Freshchat.Light.DarkActionBar"> <item name="freshchatChannelNameTextStyle">@style/CustomChannelNameTextStyle</item> </style> <style name="CustomChannelNameTextStyle" parent="Widget.Freshchat.ChannelName"> <item name="android:textAppearance">@style/MyCustomTextAppearance</item> </style>
EXPAND ↓

3. Set the custom theme for all the Freshdesk Messaging SDK Activities. The simplest way to do it is to override and set the parent of Theme.Freshchat.SelectedTheme in your app's styles.xml / themes.xml.

Copied Copy
1
<style name="Theme.Freshchat.SelectedTheme" parent="MyCustomTheme" />
EXPAND ↓

Alternately if you want to apply different themes for each activity, include the activity entries in your app's AndroidManifest.xml and override the theme from there. For example, include the custom theme as android:theme and tools:replace attribute to replace the theme by manifest merger. For a list of Freshdesk Messaging SDK Activities, refer to Freshdesk Messaging Android SDK Manifest.

Copied Copy
1
2
<activity android:name="com.freshchat.consumer.sdk.activity.ChannelListActivity" android:theme="@style/MyCustomTheme" tools:replace="android:theme" /> <activity android:name="com.freshchat.consumer.sdk.activity.ConversationDetailActivity" android:theme="@style/MyAlternateTheme" tools:replace="android:theme" />
EXPAND ↓

Customizing view appearance

Freshdesk Messaging SDK allows you to customize the appearance of the following views. If the view is a text container view, the text appearance can also be customized as part of the style.

  • freshchatMessageListStyle: Message List View Style
  • freshchatMessageListItemStyle: Style for each item in the message list
  • freshchatConversationBannerMessageStyle: Style for the banner view on top of conversation detail/message list screen
  • freshchatFAQCategoryDescriptionTextStyle: Style for FAQ category description view
  • freshchatFAQListEmptyTextStyle: Style for FAQ list empty view

FAQ Categories Screen

  • freshchatSearchIcon:Style for Freshchat search icon
  • freshchatFAQCategoryListStyle: FAQ Category List View Style
  • freshchatFAQCategoryListItemStyle: Style for each FAQ Category in the list
  • freshchatFAQCategoryNameTextStyle: Style for FAQ category name view
  • freshchatFAQCategoryAltIconStyle: Style for alternate view for category icon when icon is not configured
  • freshchatContactUsTextStyle: Style for Contact US view

FAQs list screen

  • freshchatFAQListItemStyle: Style for each item in the FAQ / Article List
  • freshchatFAQListStyle: FAQ / Article List View Style

FAQ feedback

  • freshchatFAQVotingPromptTextStyle: FAQ Voting Prompt Text style
  • freshchatFAQVotingPromptViewStyle: FAQ Voting Prompt View's style
  • freshchatFAQUpvoteButtonStyle: Style for the upvote button in the voting prompt for FAQ
  • freshchatFAQDownvoteButtonStyle: Style for the downvote button in the voting prompt fo FAQ

List of topics

  • freshchatChannelLastUpdatedAtTextStyle: Style for the Topic last updated at view
  • freshchatChannelUnreadCountTextStyle: Style for the Topic unread count view
  • freshchatChannelNameTextStyle: Style for Topic name view
  • freshchatChannelDescriptionTextStyle: Style for the Topic description view
  • freshchatChannelListItemStyle: Style for each Topic in the list
  • freshchatChannelListStyle: Topics List View Style
  • freshchatChannelAltIconStyle: Style for alternate view for the Topic icon when icon is not present

Conversation/chat screen

  • freshchatTeamMemberNameTextStyle: Style for agent name view
  • freshchatTeamMemberAvatarIcon: Style for agent avatar icon view
  • freshchatTeamMemberMessageTextStyle: Style for agent message view
  • freshchatTeamMemberMessageTimeTextStyle: Style for agent message timeStamp view
  • freshchatUserMessageTextStyle: Style for user message view
  • freshchatUserMessageTimeTextStyle: Style for user message timeStamp view
  • freshchatMessageButtonStyle: Style for the Button in the messages
  • freshchatMessageReplyInputViewStyle: Style for the Message Input Edittext Field for the user
  • freshchatSendIcon: Style for chat send icon button
  • freshchatAttachIcon: Style for freshchat attach icon

User feedback on chat screen

  • freshchatChatResolutionPromptTextStyle: Text style for freshchat resolution prompt
  • freshchatChatResolutionPromptViewStyle: Style for freshchat resolution prompt view
  • freshchatChatResolutionPositiveButtonStyle: Style for freshchat resolution positive button
  • freshchatChatResolutionNegativeButtonStyle: Style for freshchat resolution negative button

CSAT

  • freshchatCustomerSurveyDialog: Style for freshchat customer survey dialog
  • freshchatCustomerSurveyQuestionTextStyle: Style for freshchat customer survey question text
  • freshchatCustomerSurveyRatingBarStyle: Style for freshchat customer survey rating bar
  • freshchatCustomerSurveyCommentsInputViewStyle: Style for customer survey comments input

Carousels on chat screen

  • freshchatCarouselCardTitleTextStyle: Text style for carousel card title
  • freshchatCarouselCardDescTextStyle: Text style for carousel card description
  • freshchatCarouselCardButtonStyle: Style for carousel card button
  • freshchatCarouselCardSelectedTextStyle: Text style for carousel card selected
  • freshchatCarouselCardErrorImage: Style for freshchat carousel card error image
  • freshchatCarouselCardPlaceholderImage: Style for freshchat carousel card placeholder image

Dropdown on chat screen

  • freshchatDropDownHintTextStyle: Text style for freshchat fropdown hint
  • freshchatDropDownIcon: Style for freshchat fropdown icon
  • freshchatDropDownItemTextStyle: Text style for freshchat dropdown item

Calendar scheduling option on chat screen

  • freshchatCalendarFindASlotButtonStyle: Style for freshchat calendar find a slot button
  • freshchatCalendarNotInterestedButtonStyle: Style for freshchat calendar not interested

Calendar scheduling process

  • freshchatCalendarPopupDurationTextStyle: Text style for freshchat calendar popup duration
  • freshchatCalendarDayHeaderTextStyle: Text style for freshchat calendar day header
  • freshchatCalendarTimeSlotItemTextStyle: Text style for freshchat calendar time slot
  • freshchatCalendarPartOfTheDayHeaderTextStyle: Text style for freshchat calendar part of the day header
  • freshchatCalendarTimeSlotsListStyle: Style for freshchat calendar time slots list
  • freshchatCalendarOutlineButtonStyle: Style for freshchat calendar outline button
  • freshchatCalendarConfirmationAgentAvatarStyle: Style for freshchat calendar confimation agent avator
  • freshchatCalendarConfirmationUserAvatarStyle: Style for freshchat calendar confirmation user avatar
  • freshchatCalendarConfirmationMeetingDescTextStyle: Text style for freshchat calendar confirmation meeting description
  • freshchatCalendarConfirmationMeetingTimeSlotTextStyle: Text style for freschat calendar confimation meeting time slot text style
  • freshchatCalendarConfirmationMeetingDateTextStyle: Text style for freschat calendar confirmation meeting date
  • freshchatCalendarTimeSlotConfirmButtonStyle: Style for freshchat calendar time slot confirmation button
  • freshchatCalendarChangeSlotButtonStyle: Style for freshchat calendar change slot button
  • freshchatCalendarIcon: Style for freshchat calendar icon
  • freshchatCalendarCancelIcon: Style for freshchat calendar cancel icon
  • freshchatCalendarPopupTitleTextStyle: Text style for freshchat calnder popup title
  • freshchatCalendarEmailRequestDescTextStyle: Text style for freshchat calender email request description
  • freshchatCalendarEnterEmailEditTextStyle: Text style for freshchat calendar enter email input
  • freshchatCalendarEmailNextButtonStyle: Style for freshchat calendar email next button
  • freshchatCalendarNoTimeSlotsFoundTextStyle: Text style for freshchat calendar no time slots found
  • freshchatCalendarSomethingWentWrongTextStyle: Text style for freshchat calendar something went wrong error

Scheduled calendar slot view on chat screen

Translated chat view

  • freshchatOriginalMessageTitleTextStyle: Style for freshchat original message title
  • freshchatTranslationToggleIconStyle: Style for freshchat translation toggle icon
  • freshchatOriginalMessageBar: Style for freschat original message bar

Customizing Drawable and Icons

You can replace the following icons by overriding the theme attribute and specifying a different drawable for the same in your custom theme.

Copied Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
<!-- Action Icons --> <item name="freshchatSendIcon">@drawable/freshchat_ic_send</item> <item name="freshchatCancelIcon">@drawable/freshchat_ic_cancel</item> <item name="freshchatAttachIcon">@drawable/freshchat_ic_attach</item> <!-- ActionBar Menu Icons--> <item name="freshchatSearchIcon">@drawable/freshchat_ic_action_search_light</item> <!-- Misc Icons--> <item name="freshchatTeamMemberAvatarIcon">@null</item> <item name="freshchatContactUsIcon">@drawable/freshchat_ic_action_contact_us</item> <!-- Chat Bubbles --> <item name="freshchatChatBubbleLeft">@drawable/freshchat_chat_bubble_left</item> <item name="freshchatChatBubbleRight">@drawable/freshchat_chat_bubble_right</item>
EXPAND ↓

Customizing Notification Icons

To change the notification icons, refer to the “Customizing Notifications” section in the Integration Steps document.

Customizing the Topic Name and Welcome Message

Navigate to Admin > Topics to customize the title of the conversation interface and the default message.

Customizing Interactions

Custom Image Loader

By default, Freshdesk Messaging SDK includes Picasso 2.5.2 library to download images. If you want to use any other version of Picasso or any other image download library, you can set your custom image downloader using the etImageLoader() API.

Note: Please ensure not to override the library.

Examples

1. Implement the custom image loader.

Copied Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
public class CustomImageLoader implements FreshchatImageLoader { @Override public void load(@NonNull FreshchatImageLoaderRequest request, @NonNull ImageView imageView) { // your code to download image and set to imageView } @Nullable @Override public Bitmap get(@NonNull FreshchatImageLoaderRequest request) { // code to download and return bitmap image } @Override public void fetch(@NonNull FreshchatImageLoaderRequest request) { // code to download image } }
EXPAND ↓

2. Call Freshchat.setImageLoader() in onCreate() of your Application class.

Copied Copy
1
2
3
4
5
6
7
public class MyApp extends Application { @Override public void onCreate() { super.onCreate(); Freshchat.setImageLoader(new CustomImageLoader()); } }
EXPAND ↓

Intercept and handle non-Freshdesk Messaging links in app

Freshdesk Messaging provides lets you handle all non Freshdesk Messaging hyperlinks clicks by apps. Register a LinkHandler with Freshdesk Messaging that provides a callback when a user clicks a link.

We recommend setting the link handler in the Application class.

Copied Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
private LinkHandler linkHandler = new LinkHandler() { @Override public boolean handleLink(@NonNull String url, @Nullable Bundle bundle) { if (urlHandledByApp) { return true; // true, if handled by app } else { return false; // false, to let Freshchat SDK handle the link } } }; // Set link handler to override links Freshchat.getInstance(context).setCustomLinkHandler(linkHandler);
EXPAND ↓