In-App Messaging Guide

This short guide will show you how to wire up an Android application to use the Webex Connect In-App Messaging capability.

In App Messaging allows bi-directional communication between the Webex Connect platform and your mobile application. Messaging is thread based, which means all messages are associated with a thread, an end user may participate in one or many threads.

Webex Connect supports two types of threads, Conversation and Announcement. Conversation threads are used for bi-directional communication so are well suited to chat experiences. Announcement threads are uni directional, from platform to mobile app, and are ideal for items such as service messages, alerts and offers.

📘

Note

The Core SDK is only concerned with message transport and not message display.

Establishing a connection
Listening for connection status events
Receiving messages
Creating threads
Publishing messages
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 ICMessaging.connect method.

ICMessaging messaging = ICMessaging.getInstance();

try
{
  messaging.connect();
}
catch (ICException e)
{
  //An exception can occur if In App Messaging is not enabled for your app asset or if the device is not registered with the SDK.
  Log.e("Connect", e.toString());
}

📘

Note

You only need to call the connect method once, after which the SDK will manage the connection for you.

📘

Note

The Time-to-Live (TTL) limit is of 24 hours for In-App and Live Chat messages. Messages undelivered within this period will expire and will not be sent via MQTT or Web Sockets. To avoid loss of undelivered messages, app developers are recommended to implement 'fetch threads' and 'fetch messages' functionality to download these messages from the Server-Side Inbox.

Note that, if Server-Side Inbox is disabled for your app asset, then these messages will be lost if they are not delivered to the customers device within 24 hours.

b. Listening for connection status events

The SDK exposes the current status of the messaging connection via the ICConnectionStatus enumeration.
As connection status changes the SDK raises events to notify the change to your application code, to receive these events in your application either:

1. Create a receiver class extending ICMessagingReceiver and override the onConnectionStatusChanged method. -- OR --
2. Implement and register an ICMessagingListener

public class MyReceiver extends ICMessagingReceiver 
{  
  ...
    
  @Override
  protected void onConnectionStatusChanged(final Context context, final ICConnectionStatus status, final ICException e) 
  {
    Log.d("ConnectionStatusChanged", "Status : " + status.toString());
  
    if (e != null) 
    {
      Log.e("ConnectionStatusChanged", "Exception : " + e.toString());
    }
  }
}


ICMessaging.getInstance().registerListener(new ICMessagingListener()
	{
		...

		@Override
		public void onConnectionStatusChanged(final ICConnectionStatus icConnectionStatus, final ICException e)
		{
      Log.d("ConnectionStatusChanged", "Status : " + status.toString());
  
      if (e != null) 
      {
        Log.e("ConnectionStatusChanged", "Exception : " + e.toString());
      }
		}
	});

📘

Note

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

c. Receiving messages

In-App messages are received via the onMessageReceived method of a custom ICMessagingReceiver subclass or ICMessagingListener implementation, just like connection status events.

Implement your custom receiver or listener as follows:

public class MyReceiver extends ICMessagingReceiver 
{
	@Override
	protected void onMessageReceived(final Context context, final ICMessage message) 
	{
		Log.d("MessageReceived", message.getMessage());
	}
}

ICMessaging.getInstance().registerListener(new ICMessagingListener()
{
	@Override
	public void onMessageReceived(final ICMessage icMessage)
	{
		Log.d("MessageReceived", message.getMessage());
	}

	@Override
	public void onConnectionStatusChanged(final ICConnectionStatus icConnectionStatus, final ICException e)
	{
		//For InApp Messaging connection events
	}
});

d. Creating threads

In-App Messaging within Webex Connect is thread based, this means that all messages are associated with a particular thread. The SDK exposes thread data via the ICThread class. To create a new thread within the Webex Connect platform instantiate a ICThread object, set the required data fields and invoke the createThread method.

ICThread thread = new ICThread();
				
thread.setTitle("title");
thread.setCategory("category");
				
ICMessaging.getInstance().createThread(thread, new ICCreateThreadCallback()
{
  @Override
	public void onCreateThreadComplete(final ICThread icThread, final ICException e)
	{
	  if (e == null)
		{
		  //Success
		}
		else
		{
		  //Failure
			e.printStackTrace();
		}
	}
});

e. Publishing messages

The SDK represents message data with the ICMessage class, new messages can be published easily by instantiating a ICMessage and invoking the publishMessage method. As mentioned in Creating threads, messaging in Webex Connect is thread based so a message must be associated with an ICThread object. Obtain a ICThread object by calling the createThread method or, when replying to existing conversations, from an existing ICMessage instance.

ICMessage message = new ICMessage();

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

ICMessaging.getInstance().publishMessage(message, new ICPublishMessageCallback()
{
	@Override
    public void onPublishMessageComplete(final ICMessage message, final ICException exception)
    {
		if (exception != null)
		{
			Log.e("PublishMessage", exception.toString());
		}
		else
		{
			Log.d("PublishMessage", "Published Successfully");
		}
    }
});

f. Closing the connection

The SDK 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 SDK from re-establishing the connection, you may call the disconnect method.

ICMessaging messaging = ICMessaging.getInstance();
 
try 
{  
	messaging.disconnect();
} 
catch (ICException e) 
{
	Log.e("Disconnect", e.toString());
}