Skip to content

In‐app chat

Jump to bottom
Olga Koroleva edited this page May 19, 2023 · 29 revisions

Find more info about Live chat product on Infobip docs.

Intro

In-app chat SDK is built on top of Mobile Messaging SDK and that's why Mobile Messaging should be included into your application and properly configured. If you haven't used Mobile Messaging SDK in you application yet, then please follow Quick start guide to enable it.

Then you will need to add In-app chat SDK as a dependency into your iOS app by adding the following line in to your Podfile:

pod 'MobileMessaging/InAppChat'

And start In-app chat component by adding withInAppChat() to the MobileMessaging initialization chain:

MobileMessaging
	.withApplicationCode(<# your application code #>, notificationType: <# your notifications types preferences #>)?
	.withInAppChat() // this line prepares In-app chat service to start
	.start()

Display In-app chat view

Mobile Messaging In-app chat SDK provides a built-in chat view which you can quickly embed into your own application. Key component to use is MMChatViewController. We support two ways of using it:

  • via Interface Builder: set "MMChatViewController" as Custom class name for your view controller object.
  • programmatically: by presenting the appropriate chat view controller instance from an arbitrary parent view controller, for example:

If you want it to be with top bar, it will have dismiss(x) button:

if let rootVC = UIApplication.shared.keyWindow?.rootViewController {
	let chatVC = MMChatViewController.makeRootNavigationViewController()
	rootVC.present(chatVC, animated: true)
}

or, if you have navigation controller, you can push chat view controller to it, navigation bar will have back button.

let vc = MMChatViewController.makeChildNavigationViewController()
navigationController?.pushViewController(vc, animated: true)

or, if you want view controller to be presented modally, it will be without top bar.

if let rootVC = UIApplication.shared.keyWindow?.rootViewController {
	let chatVC = MMChatViewController.makeModalViewController()
	rootVC.present(chatVC, animated: true)
}

Customize In-app chat view

InAppChat offer three levels of customisation, all of them optional, each level allowing more freedom (thus being more complex as result).

The first level is defined as "General Chat Settings", and consist of values that are shared with the chat web widget, but also can be modified in runtime through code. The way to access this general chat settings, and customising the basics of the chat appearance, is through the instance: MMChatSettings.settings, and consists of the following variables:

  • title (String) - title for navigation bar when using NavigationViewController
  • sendButtonTintColor (UIColor) - tint color for Send button
  • navBarItemsTintColor (UIColor) - tint color of navigation bar items when using NavigationViewController
  • navBarColor (UIColor) - color of navigation bar when using NavigationViewController
  • navBarTitleColor (UIColor) - color of title of navigation bar when using NavigationViewController

The second level is defined as "Advanced Chat Settings". It allows you to modify anything from our UI classes, with the implication of extra effort in terms of testing and design in your end. You can access the long list of exposed variables through the instance MMChatSettings.settings.advancedSettings, which includes all fonts, icons, frames and colours our chat compose bar uses. In the ChatExample project, included within the SDK, you can see its capabilities (search for setCustomSettings)

The third level is defined as "Custom Chat Replacement". It allows you to completely exclude the compose bar we offer for interacting with the chat, and use your own input instead. The only requirements are, for your custom input view:

  1. to use our MMChatComposer protocol.
  2. to use the MMComposeBarDelegate methods to interact with the chat.
  3. and to inject your view in our chat view controller before it is loaded (for example, with the provided initialiser MMChatViewController.makeCustomViewController(with: yourCustomInputView)).

In the ChatExample project, included within the SDK, you can see its capabilities (search for showReplacedChatInNavigation)

Dark Mode

In a similar manner as you can customize in-app chat view (see section above), you can define your own settings/branding for dark mode. To achieve it, you must define your colors and other values within MMChatSettings.darkSettings; it uses the same class as the regular settings explained previously.

Then, you can decide a theme, by assigning a value to MMChatSettings.colorTheme, between three available option modes:

  1. light. This will use the values (default or assigned by you) in MMChatSetting.settings. It is the default mode.
  2. dark. This will use the values in MMChatSetting.darkSettings. If darkSettings are undefined, it will use all colours of light mode, but inverted.
  3. auto. This will decide based on the settings of the operating system - meaning, your end-user will decide which mode will be applied and when.

In the ChatExample project, included within the SDK, you can see how different settings are defined, and are dynamically applied, by searching for onChangeColorTheme and darkSettings.

Note: Dark mode feature is currently offered only on mobile.

Handle notification taps

You can retrieve the message details in such special scenario as user tapping on the notification alert/banner:

  1. Implement MMMessageHandlingDelegate protocol and it's method didPerform(action:forMessage:completion:):
class MyMessageHandlingDelegate : MMMessageHandlingDelegate {
    func didPerform(action: MMNotificationAction, forMessage message: MM_MTMessage?, notificationUserInfo: [String: Any]?, completion: @escaping () -> Void) {
    	// this way you may distinguish chat message from regular flow/broadcast push message:
        if message.isChatMessage { 
	    print("Chat message with text: \(message.text) was tapped")
	    <# your custom handling here #>
	}
        // don't forget to call `completion`, it's very important to tell the system that action handling is finished
        completion()
    }
}
  1. Pass the delegate object to MobileMessaging SDK:
MobileMessaging.messageHandlindDelegate = MyMessageHandlingDelegate()

Library events

Mobile Messaging SDK supports MMNotificationInAppChatAvailabilityUpdated event - Library-events, which is posted after the in-app chat availability status received from backend server. The userInfo dictionary contains the following key: MMNotificationKeyInAppChatEnabled - contains boolean value.

Sending attachments

Starting from 8.1.0 SDK version, we added sending attachments feature. In order to be able to choose attachment, you application need to be able to open photo library to choose the file or use camera and microphone to capture photo and video. By the Apple policies you will need to add following keys with text descriptions to your App's Info.plist file:

  • NSPhotoLibraryUsageDescription
  • NSCameraUsageDescription
  • NSMicrophoneUsageDescription

To enable document picker, you will need to turn on the iCloud Documents capabilities in Xcode.

iCloud Capabilities

Attachments preview

Starting from 8.3.0 SDK version, we added attachments preview feature. Supported file types are Images, Videos and PDFs.

In order to be able to save attachment to photo library, by the Apple policies you will need to add following key with text description to your App's Info.plist file:

  • NSPhotoLibraryAddUsageDescription

Supported attachment types

Media type File size File format
image 10MB JPG, JPEG, PNG
audio 10MB M4A
video 10MB MP4
document 10MB PDF

Unread chat push messages counter

Starting from version 9.2, new API is available to get and reset current unread chat push messages counter. The counter increments each time the application receives chat push message (this usually happens when chat screen is inactive or the application is in background/terminated state). In order to get current counter value use following API:

if let count = MobileMessaging.inAppChat?.getMessageCounter {
//use the count the way that suits you
}

MobileMessaging SDK automatically resets the counter to 0 whenever user opens the chat screen. However, use the following API in case you need to manually reset the counter:

MobileMessaging.inAppChat?.resetMessageCounter()

You can setup an MMInAppChatDelegate in order to get updates of the counter in runtime, for example:

import MobileMessaging

class MyViewController: UIViewController, MMInAppChatDelegate {
    override func viewDidLoad() {
        super.viewDidLoad()
        MobileMessaging.inAppChat?.delegate = self
    }
    //...
    func didUpdateUnreadMessagesCounter(_ count: Int) {
        //use the count the way that suits you
    }
}

Changing localization

The predefined messages prompted within the In-app chat (such as status updates, button titles, input field prompt) by default are localized using system locale setting, but can be easily changed providing your locale string with the following formats:

MobileMessaging.inAppChat?.setLanguage("es_ES")
MobileMessaging.inAppChat?.setLanguage("es-ES")
MobileMessaging.inAppChat?.setLanguage("es")

Sending Contextual Data

It is possible to send contextual data / metadata to Infobip’s Conversations via In-App Chat SDK. The data can be send any time, several times, with only one restriction: the chat must be already loaded and presented, and the communication should have started (meaning, there are messages visible and not the initial “Start the chat” button). The data sent will be automatically linked to the conversationId and accountId internally.

There are two parameters:

  1. The mandatory data, sent as string, in the format of Javascript objects and values (for guidance, it must be accepted by JSON.stringify())
  2. And optionally, a multithread strategy that can be left empty, and will use ACTIVE as default. Possible values are: metadata sent to "ACTIVE" conversation for the widget, or "ALL" non closed conversations for the widget.

Usage:

// Having created your MMChatViewController instance
let vc = MMChatViewController(type: .back)
// Present and wait till the chat is loaded and ready, then simply call
vc.sendContextualData("{name: 'Robert'}") { error in ... }

Multiple chat threads

Default LiveChat widget (name of the channel InAppChat uses) works with single chat threads: one customer can only have one single open conversation. But the LiveChat widget could be created, in Customer Portal, with support for multiple chat threads.

beSettingMT

When the setting above is enabled, the InAppChat UI will automatically offer in mobile:

  • A list (initially empty) of all the unsolved conversation threads the user has opened.
  • A button to "Start new chat" thread.
  • The capability to navigate to each specific chat thread upon tapping in them.
beSettingMT

The functionality for multiple chat threads works out of the box: there is no need for extra implementation in the mobile integrator's side. But there is something you may need to consider regarding navigation bar and the back button of the chat view controller:

The MMChatViewController, when multiple threads are in use, needs to take control over the back button to allow a return to the threads list. In other words: the chat view controller will replace the default back button and its logic. For this reason, it is recommended not to use InAppChat's multiple threads feature without a navigation bar (for example, when presented as modal view). Nevertheless, we allow to customise and intercept the actions of this new back button, if you need so, as seen in the code below:

// Optional definition of a custom back button (but we recommend leaving the default one to handle the navigation for you)
let vc = MMChatViewController.makeRootNavigationViewController()
vc.initialLeftNavigationItem = UIBarButtonItem(image:style:target:action)

Authenticated chat

It is possible to authenticate an user before accesing the chat, given you have enabled this feature in the LiveChat widget. The authentication is accomplished by combining the SDK's Personalisation method with a JWT (JSON Web Token); a token that needs to be generated by your end (see instructions here). We recommend, due to the token expiration, that a new token is always generated and injected in the SDK before presenting the chat, each and every time.

The authentication will use a unique identifier for your user, that can be an email address, a phone number, or an external identifier. It is crucial for this identifier to be valid, and to match the identity defined in the Personalisation - there will be an authentication error otherwise.

The ChatExample provided within the Mobile Messaging SDK offers a functional interface for testing the authentication use case (you just need to set your own Ids, keys and secret keys for it to work). A simplified use would be as follows:

/*
1 - The customer authenticate in your system, and you recognise his/her unique identifier
2 - You call Personalise with this unique identifier (and optionally, with other attributes such as first name, second name, etc)
3 - Now you can display the chat as an authenticated user by doing the following:
*/
MobileMessaging.inAppChat?.jwt = jwt // freshly new generated token. See documentation linked above and/or ChatExample demo for more details
let vc = MMChatViewController.makeModalViewController() // Or your preferred presentation method/style. The chat will read the JWT automatically.
self.navigationController?.present(vc, animated: true, completion: nil)

If you have any questions or suggestions, feel free to send an email to support@infobip.com or create an issue.

Features and APIs

Getting started guides

FAQ

Clone this wiki locally