In app chat

To continue using Infobip's Mobile Messaging solutions with the newest features and bug fixes, you can check out our other SDKs:

• Android SDK
• Huawei SDK
• iOS SDK
• Flutter plugin
• React Native plugin

Find more info about Live chat product on Infobip docs.

---

• Intro
• Display In-app chat screen
• Customize In-app chat
• Handle notification taps
• Sending attachments
• Attachments preview
• Supported attachment types
• Unread chat push messages counter
• Changing localization
• Sending Contextual Data
• Authenticated chat
• Handle chat errors

Intro

To setup In-app chat for Mobile Messaging plugin, put inAppChatEnabled: true in configuration:

MobileMessaging.init({
        ...
        inAppChatEnabled: true,
        ...
});

Display In-app chat screen

Call showChat method. By default in-app chat screen will be displayed with toolbar and back button at the left corner for closing the screen.

MobileMessaging.showChat(null)

Examples of android and iOS in-app-chat

You can configure presenting options for iOS, so that in-app chat screen will be displayed with toolbar and x button for iOS.

MobileMessaging.showChat({
    ios: {
         shouldBePresentedModally: true
    }
});

Customize In-app chat

You can define your own custom appearance for chat view by passing json containing predefined fields to MobileMessaging.setChatCustomization();. Call this method before loading the chat, once our SDK has been initialised, for the changes to be applied. We offer an example on chat customization in the example application.

Json object fields

• Status bar
  • chatStatusBarBackgroundColor (String) -- in hex format, color of the status bar
  • chatStatusBarIconsColorMode (String) -- text one of ['dark','light'] indicating light/dark mode of status bar's icons
• Toolbar
  • chatToolbar (Object) -- a Toolbar Json fields, used in chat screen
  • attachmentPreviewToolbar (Object) -- a Toolbar Json fields, used in attachment preview screen
  • attachmentPreviewToolbarSaveMenuItemIcon (String) -- save icon resource (path to file) in attachment preview screen
  • attachmentPreviewToolbarMenuItemsIconTint (String) -- in hex format, icons tint in attachment preview screen
• Network error
  • networkErrorText (String) -- text of network error alert
  • networkErrorTextColor (String) -- in hex format, text color of network error alert
  • networkErrorTextAppearance (String) -- text appearance of network error alert
  • networkErrorLabelBackgroundColor (String) -- in hex format, background of text in network error alert
• Chat
  • chatBackgroundColor (String) -- in hex format, chat background color
  • chatProgressBarColor (String) -- in hex format, chat's loading progress bar's color
• Input
  • chatInputTextAppearance (String) -- text appearance in input
  • chatInputTextColor (String) -- in hex format, color text in input
  • chatInputBackgroundColor (String) -- in hex format, input's background color
  • chatInputHintText (String) -- input's hint text (placeholder)
  • chatInputHintTextColor (String) -- in hex format, input hint's color
  • chatInputAttachmentIcon (String) -- attachment's icon resource (path to file) in input
  • chatInputAttachmentIconTint (String) -- in hex format, input attachment's icon color
  • chatInputAttachmentBackgroundDrawable (String) -- resource (path to file), icon which is used as background for attachment button in chat input
  • chatInputAttachmentBackgroundColor (String) -- in hex format, background color of the attachment icon in the input view
  • chatInputSendIcon (String) -- resource (path to file), icon which represent send button in chat input
  • chatInputSendIconTint (String) -- in hex format, tint color of chat input send button
  • chatInputSendBackgroundDrawable (String) -- resource (path to file), icon which is used as background for send button in chat input
  • chatInputSendBackgroundColor (String) -- resource (path to file), icon which is used as background for send button in chat input
  • chatInputSeparatorLineColor (String) -- in hex format, color of a separator between the chat and the chat input
  • chatInputSeparatorLineVisible (Boolean) -- indicating if separator line is visible
  • chatInputCursorColor (String) -- in hex format, color of chat input cursor

Toolbar Json fields

• backgroundColor (String) -- in hex format, background of toolbar
• navigationIcon (String) -- back icon resource (path to file)
• navigationIconTint (String) -- tint of back icon
• titleTextAppearance (String) -- text appearance of toolbar title
• titleTextColor (String) -- in hex format, color of toolbar title
• titleText (String) -- toolbar title text
• titleCentered (Boolean) -- indicating if toolbar text is centered
• subtitleTextAppearance (String) -- text appearance of toolbar subtitle, android only
• subtitleTextColor (String) -- in hex format, color of subtitle, android only
• subtitleText (String) -- subtitle text, android only
• subtitleCentered (Boolean) -- indicating if subtitle text is centered, android only

Note: Same style can be achieved in a xml format of android styles. Define your own theme.

Livechat widget theme

Livechat widget themes are defined on the Live chat widget setup page on Infobip Portal. You can define multiple custom themes and customize various widget attributes, read Livechat documentation to get information about all possible widget customization options.

To set Livechat theme in In-app chat you must:

1. Define the name and values of your theme(s) in a JSON format, under widget section Theme -> Advanced Customization, in Infobip Portal.
2. Once you know the names of your themes, you can use them with MobileMessaging.setWidgetTheme() function.

Handle notification taps

Mobile Messaging Plugin has notificationTapped event, which will be sent when user opens the app by tapping on the notification alert. Note that chat messages may be recognised by chat attribute:

MobileMessaging.register("notificationTapped", function(message) {
  if (message.chat) {
     console.log('Chat message tapped', message);
  }
});

Sending attachments

For sending attachments you will need to add additional permissions

• For iOS iCloud capability will be turned on automatically, but you will still need to add it to the provisioning profile(s) More info about iOS permissions

• For Android add this code in to config.xml More info about Android permissions

    <platform name="android">
        ...
        <config-file target="AndroidManifest.xml" parent="/*" xmlns:android="http://schemas.android.com/apk/res/android">
            <uses-permission android:name="android.permission.CAMERA" />
        </config-file>
    </platform>

Attachments preview

For saving attachments to photo library you will need to add additional permissions

• For iOS more details can be found by the link More info about iOS permissions

• For Android add this code in to config.xml More info about Android permissions

    <platform name="android">
        ...
        <config-file target="AndroidManifest.xml" parent="/*" xmlns:android="http://schemas.android.com/apk/res/android">
            <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
        </config-file>
    </platform>

Supported attachment types

• Supported attachment types for iOS
• Supported attachment types for Android

Unread chat push messages counter

Starting from version 2.3.0, 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:

MobileMessaging.getMessageCounter((result) => {
    console.log('Counter: ' + result);
});

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.resetMessageCounter();

You can register to event inAppChat.unreadMessageCounterUpdated, in order to get updates of the counter in runtime.

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: "es_ES", "es-ES", "es".

MobileMessaging.setLanguage('es', function (error) {
    console.log("Error set language: " + error);
});

Sending Contextual Data

It is possible to send contextual data / metadata to Infobip’s Conversations via mobile messaging SDK's chat. Data can be sent anytime, 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). Sent data will be automatically linked to the conversationId and accountId internally.

There are tree 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, an "all multithread strategy" that can be left empty, and will use false (ACTIVE) as default. Possible values are: metadata sent to "ACTIVE" conversation for the widget (with false), or to "ALL" non closed conversations for the widget (with true).
3. Error callback.

Usage:

MobileMessaging.sendContextualData(
  '{"test_attribute_string":"test_attribute_value"}',
  true,
  function () {}
);

Authenticated chat

It is possible to authenticate a user before accessing the In-app chat, given you have enabled this feature in the LiveChat widget.

The authentication is accomplished by combining the Mobile Messaging SDK personalisation method with a JWT (JSON Web Token). The token needs to be generated by your end. For more details, see instructions).

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 userIdentity you passed in Mobile Messaging SDK personalisation call - there will be an authentication error otherwise.

Note:

We highly recommend to visit JWT payload structure table and follow the description for each field.

Mobile messaging provides setChatJwtProvider() method to give In-app chat the ability to authenticate users. Method's first argument - jwtProvider is a callback function that returns a JSON Web Token (JWT) used for chat authentication. It supports both synchronous and asynchronous approaches:

Synchronous usage:

/*
1 - The customer authenticate in your system, and you recognise his/her unique identifier
2 - You call personalise (MobileMessaging.personalize()) 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.setChatJwtProvider(() => {
  return "your_token"; // Return a valid JWT string directly
});
MobileMessaging.showChat();

Asynchronous usage:

MobileMessaging.setChatJwtProvider(async () => {
  const jwt = await getChatToken(...);
  return jwt; // Return a Promise<string> that resolves to a valid JWT
});
MobileMessaging.showChat();

Note: the jwtProvider callback argument may be invoked multiple times during the widget's lifecycle due to events such as screen orientation changes or network reconnections. It is essential to supply a fresh, new, valid JWT on each invocation.

Handle chat errors

You can handle chat-related errors by setting exception handler before showing the chat screen.

Typical use cases:

• User Notifications: Show friendly error messages if chat fails to load or send.
• Error Logging: Report errors to remote logging services for monitoring.
• Fallback Actions: Redirect users to alternative support channels if chat is unavailable.

MobileMessaging.setChatExceptionHandler(
    function (exception) {
        utils.log('Cordova app: Chat exception received: ' + JSON.stringify(exception));
    },
    function (error) {
        utils.log('Cordova app: Error setting chat exception handler: ' + error);
    }
);
MobileMessaging.showChat();