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.gradle1 2 3 4 5 | allprojects { repositories { maven { url "https://jitpack.io" } } } |
2. Add the following dependency to your app module's build.gradle file (project/app/build.gradle):
project/app/build.gradle1 2 3 4 5 6 7 8 | apply plugin: 'com.android.application' android { // ... } dependencies { // ... implementation 'com.github.freshworks:freshchat-android:{{latest-version}}' } |
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.xml1 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> |
1 | <string name="freshchat_file_provider_authority">com.example.demoapp.provider</string> |
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.
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); |
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.
Example1 2 3 4 | { "freshchat_uuid": "6bc903d6-12ba-11eb-adc1-0242ac120002", "reference_id": "sample_user" } |
Restoring a restorable User
To create or restore a restorable user, restore the user API.
1 | Freshchat.getInstance(getContext()).restoreUser("JWT_TOKEN"); |
Updating user properties of a restorable user
To update user properties of a restorable user, use setUser API:
Sample JWT payload: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"); |
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:1 2 3 | { "freshchat_uuid": "6bc903d6-12ba-11eb-adc1-0242ac120002" } |
Creating an anonymous User
To create an anonymous user, use setUser API.
1 | Freshchat.getInstance(getContext()).setUser("JWT_TOKEN"); |
Updating user properties of an anonymous user
To update the user properties of an anonymous user, use setUser API.
Sample JWT payload: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"); |
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 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:
Android1 | Freshchat.getInstance(getContext()).getUserIdTokenStatus(); |
Listening to JWT Token status changes
AndroidYou 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 receiver1 2 | IntentFilter freshchatEventsIntentFilter = new IntentFilter(Freshchat.FRESHCHAT_EVENTS); LocalBroadcastManager.getInstance(getApplicationContext()).registerReceiver(freshchatEventsReceiver, freshchatEventsIntentFilter); |
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()); } } }; |
1 | LocalBroadcastManager.getInstance(getApplicationContext()).unregisterReceiver(freshchatEventsReceiver); |
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 receiver1 2 3 4 5 | [[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(userActionEvent:) name:FRESHCHAT_EVENTS object:nil]; |
1 2 3 4 5 6 | (void) userActionEvent:(NSNotification *)notif { FreshchatEvent *fcEvent = notif.userInfo[@"event"]; if(fcEvent.name == FCEventIdTokenStatusChange){ NSString *tokenStatus = [[Freshchat sharedInstance] getUserIdTokenStatus]; } } |
1 2 3 4 | [[NSNotificationCenter defaultCenter] removeObserver:self name:FRESHCHAT_EVENTS object:nil]; |
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.
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); |
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.
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); |
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):1 | Freshchat.getInstance(getApplicationContext()).identifyUser(externalId, null); |
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 receiver1 2 | IntentFilter intentFilter = new IntentFilter(Freshchat.FRESHCHAT_USER_RESTORE_ID_GENERATED); LocalBroadcastManager.getInstance(getApplicationContext()).registerReceiver(broadcastReceiver, intentFilter); |
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(); } }; |
1 | LocalBroadcastManager.getInstance(getApplicationContext()).unregisterReceiver(broadcastReceiver); |
1 | saveRestoreIdForUser(restoreId); |
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
1 | Freshchat.getInstance(getApplicationContext()).identifyUser(externalId, restoreId); |
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.1 | Freshchat.resetUser(getApplicationContext()); |
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)
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); |
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
1 2 | String token = FirebaseInstanceId.getInstance().getToken(); Freshchat.getInstance(this).setPushRegistrationToken(token); |
Handling messages
When you implement FirebaseMessagingService, pass the RemoteMessage object to Freshdesk Messaging if it is a Freshdesk Messaging notification.
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 } } |
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.
1 | <color name="freshchat_notification_accent_color">@color/red</color> |
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.
1 | <string name="freshchat_campaign_notification_channel_name">Campaign messages</string> |
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); |
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.
1 2 3 4 5 6 | myFAQButton.setOnClickListener(new OnClickListener() { @Override public void onClick(View view) { Freshchat.showFAQs(getApplicationContext()); } }); |
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: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); } }); |
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".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); |
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.
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); |
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".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); |
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
1 2 3 4 5 6 | myConversationsButton.setOnClickListener(new OnClickListener() { @Override public void onClick(View view) { Freshchat.showConversations(getApplicationContext()); } }); |
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".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); |
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.
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)); } }); |
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 receiver1 2 | IntentFilter intentFilter = new IntentFilter(Freshchat.FRESHCHAT_UNREAD_MESSAGE_COUNT_CHANGED); getLocalBroadcastManager(getApplicationContext()).registerReceiver(unreadCountChangeReceiver, intentFilter); |
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)); } }); } } |
1 | getLocalBroadcastManager(getApplicationContext()).unregisterReceiver(unreadCountChangeReceiver); |
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.
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); |
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:1 | <string name="freshchat_activity_title_channel_list">Conversations</string> |
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.
1 | Freshchat.notifyAppLocaleChange(activityContext); |
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
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); } }; |
Set webview listener to Freshdesk Messaging Instance. We recommend you to do this in onCreate() of Application class.
1 | Freshchat.getInstance(this).setWebviewListener(webviewListener); |
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:1 | <style name="Theme.Freshchat.SelectedTheme" parent="@style/Theme.Freshchat.Light.DarkActionBar" /> |
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.
1 | <item name="colorPrimary">@color/my_awesome_color</item> |
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: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> |
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.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> |
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.
1 | <style name="Theme.Freshchat.SelectedTheme" parent="MyCustomTheme" /> |
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.
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" /> |
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.
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> |
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.
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 } } |
2. Call Freshchat.setImageLoader() in onCreate() of your Application class.
1 2 3 4 5 6 7 | public class MyApp extends Application { @Override public void onCreate() { super.onCreate(); Freshchat.setImageLoader(new CustomImageLoader()); } } |
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.
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); |