In-App Messaging Guide

This guide will show you how to integrate the Webex Connect In-App Messaging capability into your Android application.

Please ensure you have integrated the In-App Messaging Module by following the Quick Start Guide.

Overview of In-App Messaging

In-App Messaging allows bi-directional communication between the Webex Connect platform and your mobile application. Messaging is thread-based, meaning all messages are associated with a specific thread. A thread can be viewed as a chronological sequence of messages presented as a conversation. An end user can participate in one or more threads.

Types of Threads

Webex Connect supports two types of threads:
Conversation Threads: These threads are used for bi-directional communication, making them well-suited for chat experiences.
Announcement Threads: These threads are uni-directional, from the platform to the mobile app, and are ideal for service messages, alerts, and offers.

Messages are delivered via real time connection between the SDK and the Webex Connect message broker. Messages that are published when the real time connection is not active, will be held at the broker for a maximum of 24 hours, and will be delivered once a connection has been established. Messages that are not delivered within the 24 hour period will be removed from the broker and will not be delivered via the real time connection, although can still be retrieved from the Server-Side Inbox (see below).

Our Server-Side Inbox feature persists threads and messages within the Webex Connect platform for later retrieval via API. Data is persisted for a period of 30 days, although this can be adjusted upon request via your account manager. The maximum data retention period is 1 year.

📘

Note

The Server Side Inbox feature must be enabled within your app asset configuration. If the feature is not enabled, any messages that are not delivered via real-time connection within 24 hours of publication, will be lost.

Below are the steps, you need to complete to enable In-App Messaging in your app.

a. Establishing a connection
b. Listening for connection status events
c. Receiving messages
d. Creating threads
e. Publishing messages
f. Closing the connection

a. Establishing a connection

In App Messaging uses its own dedicated connection, therefore you must establish the connection with the Webex Connect platform before messages can be received. Connection is established by invoking the connect method as shown below.

try {
    InAppMessaging.instance.connect()
}catch (e: Exception) {
    //Handle exception
}

try {
    InAppMessaging.getInstance().connect();
} catch (WebexConnectException e) {
    //Handle exception
}

📘

Note

You only need to call the connect method once, after which the SDK will manage the connection for you, even between app restarts. The SDK will stop managing the connection if the disconnect method is called.

b. Listening for connection status events

The SDK exposes the current status of the messaging connection via the connectionStatus enumeration.
As connection status changes the SDK raises events to notify the change to your application code. To receive these events in your application, implement and register a ConnectionStatusListener.

InAppMessaging.instance.registerConnectionStatusListener { connectionStatus ->
    //Handle the connection status change
}

InAppMessaging.getInstance().registerConnectionStatusListener(connectionStatus ->
{
    //Handle the connection status change
    return Unit.INSTANCE;
});

📘

Note

Mobile data connections can be unreliable, therefore it is normal for disconnects to occur. In case of a disconnection the SDK will automatically re-establish the connection for you.

c. Receiving messages

As messages are received by the SDK they are emitted via listeners. Register a listener by calling the registerMessageListner method.

InAppMessaging.instance.registerMessagingListener { inAppMessage ->
    	// Handle the message
	}

InAppMessaging.getInstance().registerMessagingListener(inAppMessage -> {
  	// Handle the message
    return Unit.INSTANCE;
});

d. Creating threads

To create a new thread, instantiate an InAppThread object, set the required data fields, and invoke the createThread method.

val thread = InAppThread()

thread.title = "title"
thread.category = "category"

InAppMessaging.instance.createThread(thread) { inAppThread: InAppThread?, exception: WebexConnectException? -> 
  if (exception == null) {
		//Handle success
  } else {
    //Handle exception
  }
}

InAppThread thread = new InAppThread();

thread.setTitle("title");
thread.setCategory("category");

InAppMessaging.getInstance().createThread(thread, (inAppThread, exception) - > {
    if (exception == null) {
			//Handle success
    } else {
       //Handle exception
    }
    return Unit.INSTANCE;
});

e. Publishing messages

To publish a message, create an instance of InAppMessage, set the required data fields, and call the publishMessage method. Messages must be assigned a valid InAppThread instance, which is obtainable by creating a new thread, fetching existing threads, or from an existing InAppMessage.

val message = InAppMessage()

message.message = "Test message"
message.thread = yourThreadObj

InAppMessaging.instance.publishMessage(message) { publishedMessage: InAppMessage?, exception: WebexConnectException? ->
    if (exception != null) {
        //Handle exception
    } else {
        //Handle success
    }
}

InAppMessage message = new InAppMessage();

message.setMessage("Test message");
message.setThread(yourThreadObj);

InAppMessaging.getInstance().publishMessage(message, (publishedMessage, exception) - > {
    if (exception != null) {
        //Handle exception
    } else {
        //Handle success
    }
    return Unit.INSTANCE;
});

f. Closing the connection

The In-App Messaging module will normally manage the messaging connection for you, automatically connecting and disconnecting as your app transitions between background and foreground states. However, if you wish to disconnect and prevent the In-App Messaging module from re-establishing the connection, you may call the disconnect method.

try {
    InAppMessaging.instance.disconnect()
} catch (e: Exception) {
    // Handle exception
}

try {
  InAppMessaging.getInstance().disconnect();
} catch (WebexConnectException e) {
	// Handle exception
}

With this you have successfully integrated the In-App Messaging module within your app.