Brand Messenger Android SDK Conversation

Learn how to initiate a chat with an agent in the Brand Messenger Android SDK

Initiate Chat with Agent

For starting the messaging activity, using the following script:

BrandMessengerManager.show(context);
BrandMessengerManager.show(context);

If the environment is also configured with Welcome-Messages, the following can be used instead of show(context). This will also send an API request to give the user a welcome-message.

BrandMessengerManager.showWithWelcome(context);

To just send the welcome-message API request without displaying the conversation screen, use the following

BrandMessengerManager.sendWelcomeMessageRequest(context);

Intercept Message Actions

Message actions from SDK conversation screen, such as user tapping on link-buttons, can be intercepted and handled outside of the SDK via a delegate.

BrandMessengerManager.setMessageActionDelegate(new KBMMessageActionDelegate() {
    @Override
    public boolean onAction(Context context, String action, Message message, Object object, Map<String, Object> replyMetadata) {
        switch (action) {
            // Example action types
            case KBMRichMessage.SUBMIT_BUTTON:
                break;
            case KBMRichMessage.QUICK_REPLY:
                break;
            case KBMRichMessage.TEMPLATE_ID + 9:
                break;
            case KBMRichMessage.WEB_LINK:
                // URL link data is found differently depending on the rich-message model type
                KBMRichMessageModel.KBMAction kbmAction = null;
                if (object instanceof KBMRichMessageModel.KBMButtonModel) {
                    kbmAction = ((KBMRichMessageModel.KBMButtonModel) object).getAction();
                } else if (object instanceof KBMRichMessageModel.KBMElementModel) {
                    kbmAction = ((KBMRichMessageModel.KBMElementModel) object).getAction();
                } else if (object instanceof KBMRichMessageModel.KBMAction) {
                    kbmAction = (KBMRichMessageModel.KBMAction) object;
                } else if (object instanceof KBMRichMessageModel.KBMPayloadModel) {
                    kbmAction = ((KBMRichMessageModel.KBMPayloadModel) object).getAction();
                }
                String url;
                if (kbmAction != null) {
                    if (!TextUtils.isEmpty(kbmAction.getUrl())) {
                        url = kbmAction.getUrl()
                    } else if (kbmAction.getPayload() != null && !TextUtils.isEmpty(kbmAction.getPayload().getUrl())) {
                        url = kbmAction.getPayload().getUrl();
                    }
                }

                if (object instanceof KBMRichMessageModel.KBMPayloadModel) {
                    KBMRichMessageModel.KBMPayloadModel payloadModel = (KBMRichMessageModel.KBMPayloadModel) object;
                    if (!TextUtils.isEmpty(payloadModel.getUrl())) {
                        url = payloadModel.getUrl();
                    }
                }
                openUrl(url);
                return true;
        }
        // Return false to let SDK handle action. True if action is handled here.
        return false;
    }
});
BrandMessengerManager.setMessageActionDelegate( object : KBMMessageActionDelegate {
    override fun onAction(
        context: Context?,
        action: String?,
        message: Message?,
        `object`: Any?,
        replyMetadata: MutableMap<String, Any>?
    ): Boolean {
        when (action) {
            KBMRichMessage.SUBMIT_BUTTON -> return false
            KBMRichMessage.QUICK_REPLY -> return false
            KBMRichMessage.TEMPLATE_ID -> return false
            KBMRichMessage.WEB_LINK -> {
                // handle link.
                var kbmAction: KBMRichMessageModel.KBMAction? = null
                if (kbmObject is KBMRichMessageModel.KBMButtonModel) {
                    kbmAction = kbmObject.action
                } else if (kbmObject is KBMRichMessageModel.KBMElementModel<*>) {
                    kbmAction = kbmObject.action
                } else if (kbmObject is KBMRichMessageModel.KBMAction) {
                    kbmAction = kbmObject
                } else if (kbmObject is KBMRichMessageModel.KBMPayloadModel) {
                    kbmAction = kbmObject.action
                }
                var url: String
                if (kbmAction != null) {
                    if (!TextUtils.isEmpty(kbmAction.url)) {
                        url = kbmAction.url
                    } else if (kbmAction.payload != null && !TextUtils.isEmpty(kbmAction.payload.url)) {
                        url = kbmAction.payload.url
                    }
                }

                if (kbmObject is KBMRichMessageModel.KBMPayloadModel) {
                    if (!TextUtils.isEmpty(kbmObject.url)) {
                        url = kbmObject.url
                    }
                }
                openUrl(url)
                return true
            }
        }
        return false;
    }
})

Monitor Chat Screen Is Alive

The SDK can enable a touch-based "isAlive" broadcast, which will make the it send out a broadcast on any motion gesture like touch, key press, accessibility focus changes or text changes in message input box. An example usage of this is if the consuming app needs to constantly know if the view in foreground is from the SDK.

BrandMessengerManager.enableIsAliveBroadcast(this, true);

//To receive the "isAlive" broadcast on app that is consuming the SDK
registerMyReceiver(this);

public void registerMyReceiver(Context context) {
   IntentFilter filter = new IntentFilter("KBM_NOTIFICATION_KBM_IS_ALIVE");
   MyBroadcastReceiver receiver = new MyBroadcastReceiver();
   if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
       context.registerReceiver(receiver, filter, Context.RECEIVER_EXPORTED);
    } else {
        context.registerReceiver(receiver, filter);
      }
    }

public class MyBroadcastReceiver extends BroadcastReceiver {
    @Override
     public void onReceive(Context context, Intent intent) {
     Log.d("MyBroadcastReceiver", "Broadcast received: " + intent.getAction());
   }
}

Fetch new messages on every chat screen open

The SDK fetches the latest message every time the chat-screen is opened.
This functionality can be enabled/disabled. When disabled, new messages will only be fetches when a push-notification arrives or a mqtt connection message for new message is received.
Default is enabled (true).
BrandMessengerUserPreference.getInstance(this).setFetchNewOnFragmentOpen(false);

Choosing persistent or temporary storage for the conversation

Customers can switch between using a persistent and temporary database for conversation data.
Default is temporary (false).

BrandMessengerUserPreference.getInstance(this).setUsePersistentMessagesStorage(true);

Display Conditions

These are conditions which decide whether "chat" is active for a user or not.
They can be set from the Care Dashboard under admin panel -> modern chat -> select widget. More information about Display Conditions is available there.
Here are some of the SDK methods for checking display conditions:

// Control chat based on display conditions set from the care dashboard.
BrandMessengerManager.isAllDisplayConditionsMet(MainActivity.this, new KBMGenericCallback<Boolean, Exception>() {
                    @Override
                    public void onSuccess(Boolean success) { }

                    @Override
                    public void onFailure(Exception failure) { }
                });
//Control chat based on a random number and it's magnitude relative to a set percentage.
BrandMessengerManager.shouldThrottle(MainActivity.this, new KBMGenericCallback<Boolean, Exception>() {
                    @Override
                    public void onSuccess(Boolean success) { }

                    @Override
                    public void onFailure(Exception failure) { }
                });
// Control chat based on geo-location and client IP address.
BrandMessengerManager.isDeviceGeoIPAllowed(MainActivity.this, new KBMGenericCallback<Boolean, Exception>() {
                    @Override
                    public void onSuccess(Boolean success) { }

                    @Override
                    public void onFailure(Exception failure) { }
                });

Close the Chat Screen

To close the conversation screen call the following method:

BrandMessengerManager.dismiss();