TABLE OF CONTENTS

• Mobile Chat SDK Widget Overview
• Prerequisites
  • Platform Requirements
  • Web Chat Widget configuration
• Set up the SDK
• User identification & authentication
• Deploy the SDK
  • Initializing the SDK
  • Setting user properties
  • Setting ticket properties
• Handle Push Notifications
• URL Handling on SDK
• Fetch unread count
• Track user events via SDK
  
  

Mobile Chat SDK Widget Overview

The Freshdesk Mobile Chat SDK allows you to engage with users directly within your mobile app and manage their queries in real time. The SDK supports both anonymous and authenticated users and renders as an integrated, in-app chat interface that blends seamlessly with your app’s UI. Each new chat initiated through the SDK is automatically created as a separate ticket in your Freshdesk inbox, enabling efficient tracking, follow-up, and support.

Prerequisites

Platform Requirements

iOS

Freshdesk iOS SDK is compatible with iOS 17+ devices, and delivers the best experience on iOS 18.5 and newer versions.

Web Chat Widget configuration

The Mobile Chat SDK is fully powered by the Web Chat Widget configuration in terms of both content and appearance. This means that you must first configure a Web Chat Widget with the appropriate content (such as live chat topics, knowledge base categories, and web forms) and appearance settings, including branding, logos, and colors.

All these configurations are automatically inherited by the Mobile Chat SDK and will reflect exactly the same within your mobile app once the SDK is integrated. For more information, see Overview of Web Chat Channel.

Set up the SDK

To enable the Mobile Chat SDK in your mobile app:

1. Log in to your account as an admin.
2. Go to Admin > Channels > Mobile Chat SDK.
3. Click Create new.
4. Select an existing web chat widget or create a new web chat widget, as the Mobile Chat SDK inherits its configuration.
5. In the Mobile SDK config section, obtain the setup instructions and integration keys.
6. Follow the platform-specific integration steps in your mobile app.
7. Once integrated, the chat interface will automatically appear in your app, powered by your Web Chat Widget settings.
   
   

User identification & authentication

Freshdesk supports JSON Web Token (JWT) based authentication to securely identify users interacting with the Mobile Chat SDK. By enabling JWT authentication, you can ensure that only verified users are allowed to initiate conversations through your mobile-integrated chat experience. This helps maintain a secure and personalized support flow inside your app.

User history and conversations will be maintained and restored via this JWT approach. For more details, see Create Widgets.

How JWT Authentication works?

1. Conversation Initiation: A user opens the chat interface within your mobile app through the Mobile Chat SDK.
2. Token Request: The app requests or generates a signed JWT token containing the user’s identity information (such as email or name) from your backend.
3. Chat Initialization: The Mobile Chat SDK initializes the chat session by passing the JWT token to Freshdesk during startup.
4. Token Verification: Freshdesk validates the JWT token, extracts the user details from the payload, and grants access to the authenticated chat session.
   
   

Deploy the SDK

To deploy the SDK:

1. Go to Admin > Mobile Chat SDK > Create SDK.
2. In the SDK configuration, you’ll find the credentials needed to initialise the SDK in your mobile app.
   

Initializing the SDK

In Appdelegate -> didFinishLaunchingWithOptions (Invoke the Freshdesk initialisation)

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { 
    let sdkConfig = FreshdeskSDKConfig(token: <YOUR_TOKEN>,
                                       host: "<YOUR_HOST>",
                                       sdkId: "<YOUR_SDK_ID>",
                                       jwtToken: "<YOUR_JWT>",
                                       locale: "<YOUR_APP_LOCALE>"
    )
    Freshdesk.initialize(with: sdkConfig)
    registerNotifications() // For notification related, check PushNotification section at the last
    return true
}

Setting user properties

To set user properties, use the method below as a reference. 

Note: 

1. Ensure that these properties are whitelisted under the Contact Fields of the SDK-linked widget.
2. For JWT-enforced SDKs, updating user properties is handled via the JWT payload. Please refer to the 'JWT' section below.

let userProperties: [String: Any] = [
                        "name": "Mobile iOS SDK",
                        "address": "Chennai, India",
                        "mobile": "1234567890",
                        "phone": "9876543210",
                        "customnumber": 123 //custom user field
    ]
Freshdesk.setUserDetails(with: userProperties)

Setting ticket properties

To set ticket information, use the method below as a reference. 

Note: Ensure that these properties are whitelisted under the Ticket Fields of the SDK-linked widget.

let ticketProperties: [String: Any] = [
                        "subject": "Product Enquiry",
                        "priority": 3,
                        "cf_custom_ticket_field": "sample value" //custom ticket field  
]
Freshdesk.setTicketProperties(with: ticketProperties)

Handle Push Notifications

To enable real-time push notifications for incoming messages, the required push notification configuration data must be added to the Mobile Chat SDK during initialization. This includes the appropriate platform-specific notification certificates or keys.

The steps to obtain these certificates/keys and update the SDK configuration are outlined below.

Step 1: Upload your .p8 push certificate:

Select  Settings > Mobile Chat SDK > Push Notification.

Here’s how you can get your .p8 from Apple:

1. Go to the Apple Developer Account and sign in:
   https://developer.apple.com/account 
2. In the left menu, open Certificates, Identifiers & Profiles → Keys.
3. Click the “+” (Add Key) button.
4. Enter a name for the key and enable “Apple Push Notifications service (APNs)”.
5. Click Continue > Register to confirm.
6. Click Download to save the AuthKey_XXXXXX.p8 file.
   (This is your APNs Auth Key and can only be downloaded once.)
   
   

Step 2: After uploading, add your Authentication KeyId and TeamId in the required fields.

Step 3: Request push notification permission and register with APNs.

func registerNotifications() {
        UNUserNotificationCenter.current().delegate = self
        UNUserNotificationCenter.current().requestAuthorization(options: [.alert, .sound, .badge]) { (granted, error) in
            // Handle authorization status
            if granted {
                DispatchQueue.main.async {
                    UIApplication.shared.registerForRemoteNotifications()
                }
            }
        }
    }

Step 4: Receive APNs device token and register with Freshdesk SDK

func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
        Freshdesk.setPushRegistrationToken(deviceToken)
    }

Step 5: Handle notification when the app is in foreground

func userNotificationCenter(_ center: UNUserNotificationCenter, willPresent notification: UNNotification,
                                withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void) {
        let userInfo = notification.request.content.userInfo
        let appState = UIApplication.shared.applicationState
        
        if Freshdesk.isFreshdeskNotification(userInfo) {
            Freshdesk.handleRemoteNotification(userInfo, appState: appState)
        
        } else {
            // If not Freshdesk notification, show normally
            completionHandler([.banner, .badge, .sound])
        }
    }

Step 6: Handle notification when user taps it (background/terminated)

func userNotificationCenter(_ center: UNUserNotificationCenter, didReceive response: UNNotificationResponse,
                                withCompletionHandler completionHandler: @escaping () -> Void) {
        let userInfo = response.notification.request.content.userInfo
        let appState = UIApplication.shared.applicationState
        
        if Freshdesk.isFreshdeskNotification(userInfo) {
            Freshdesk.handleRemoteNotification(userInfo, appState: appState)
        } else {
            // Not Freshdesk notification
        }
        completionHandler()
    }

URL Handling on SDK

The Freshdesk Mobile Chat SDK provides flexible URL handling so you can control how different types of links behave within your mobile app. Depending on your app’s navigation structure and user experience requirements, you can customize the way the SDK processes various URL types.
The supported URL categories include:

• In-app rich deep links: Routes users to specific screens or features inside your app.
• External URLs: Opens web pages outside the app, typically using the system browser or an in-app web view, based on your custom implementation.
• Solution article URLs: Opens Freshdesk Knowledge Base articles directly within the Mobile Chat SDK’s built-in article viewer for a seamless in-app support experience.

This configuration allows you to maintain consistent navigation behavior and integrate the chat experience smoothly with your existing app flow.

  Freshdesk.setCustomLinkHandler { url in
        print("Link tapped: \(url)")
        // Custom handling logic
        if url.absoluteString.hasPrefix("App-deep-link://") {
            // "Deeplink URL tapped: Perform any action with url.host ?? url.absoluteString
            return
        }
        // Open your custom link in seperate view url.host ?? url.absoluteString
    }

Note: Make sure the application holds a solid reference to the implementation of the FreshDeskSDKLinkHandler (no weak references) or it may be garbage collected.

Fetch unread count

The Freshdesk Mobile Chat SDK allows you to fetch the unread message count for each live chat topic associated with your widget. This enables you to display badges or pills on entry points outside the Mobile Chat SDK, such as your app’s home screen, menu, or support section, indicating that new messages are waiting.

This ensures users are aware of pending conversations even before they open the chat interface.

Use the method below to retrieve the existing unread count.

 Freshdesk.getUnreadCount()

To receive real-time updates of the unread count, add a notification observer as shown below.

NotificationCenter.default.addObserver(self, selector: #selector(self.onUnreadCount(_:)), name: Notification.Name(FDEvents.unreadCount.rawValue), object: nil)
        
    @objc func onUnreadCount(_ notification: NSNotification) {
        if let unreadCount = notification.object as? Int {
            DispatchQueue.main.async {
                //Update realtime count value with unreadCount
            }
        }
    }

Track user events via SDK

Freshdesk lets you track user actions, such as updating a profile picture or adding items to a cart. These events can help you engage users, trigger messages, or segment users for campaigns.

Use the method below as a reference.

Freshdesk.trackUserEvents(name: "eventName", payload: ["eventName":"eventValue"])