Core Classes

• ICMessaging
• ICMessagingReceiver
• ICNotificationFactory
• ICMessageData
• ICMessage
• ICThread
• ICTopic

ICMessaging

This singleton is the main interface to the IMIconnect messaging system, it provides methods that facilitate incoming and outgoing messages, thread and topic management, message status and connection control.

allowJavascriptInWebviews

Sets whether JavaScript execution is allowed within WebView instances that are created by the SDK. The default value is false.

  Syntax: void allowJavascriptInWebviews(boolean flag)

  Parameters:

closeThread

Closes a conversation thread.

  Syntax: void closeThread(final ICThread thread, final ICUpdateThreadCallback callback)

  Parameters:

connect

Once the RT feature is enabled in the app asset created on IMIconnect and user registration is done, the App Developer can establish a connection between the app and IMIconnect platform by calling the connect method appropriately. This enables the messages sent from IMIconnect to be received on the app. When the application is running in the background, SDK is disconnected from IMIconnect. While in the disconnected state, incoming In-App messages are not received, however when the application comes to foreground again, SDK will establish a connection with IMIconnect platform and allow messages to be received.

connect is used to establish a connection to receive In-App Messages from the IMIconnect platform.
Connection status events are notified through ICMessagingReceiver.onConnectionStatusChanged and ICMessagingListener.onConnectionStatusChanged.

📘

Throws an ICException if a user is not registered with IMIconnect or if In App Messaging is not enabled.

  Syntax: void connect() throws ICException

  Example:

ICMessaging messaging = ICMessaging.getInstance();

try
{
  messaging.connect();
} 
catch (ICException e) 
{
  Log.e("Connect", e.toString());
}

createThread

ICMessaging.getInstance().createThread(streamName, threadTitle, new ICCreateThreadCallback()
{
  @Override
  public void onCreateThreadComplete(final ICThread thread, final ICException exception)
  {
    if (exception != null)
    {
      Log.e("CreateThread", "createdThread failed! Reason:" + exception.toString());
    }
    else
    {
      Log.d("CreateThread ", "createdThread succeeded!");
    }
  }
});

createThread

Creates a thread within the IMIconnect platform from the provided [ICThread](#section-icthread) object.

  Syntax: void createThread(final ICThread thread, final ICCreateThreadCallback callback)

  Parameters:

🚧

Always check that the createThread method is successful before using the thread instance further. On successful completion the thread will be populated with a valid identifier.

  Example:

ICThread thread = new ICThread();

thread.setTitle("MyTitle");
thread.setCategory("MyCategory");

ICMessaging.getInstance().createThread(thread, new ICCreateThreadCallback()
{
  @Override
  public void onCreateThreadComplete(final ICThread thread, final ICException exception)
  {
    if (exception != null)
    {
      Log.e("CreateThread", "createdThread failed! Reason:" + exception.toString());
    }
    else
    {
      Log.d("CreateThread ", " createdThread succeeded!");
    }
  }
});

disconnect

Disconnects the In App Messaging connection between the app and IMIconnect platform. If there is no active connection, then this method fails silently.

When the disconnection completes, the event is notified through [ICMessagingReceiver.onConnectionStatusChanged](#section-onconnectionstatuschanged) and [ICMessagingListener.onConnectionStatusChanged](doc:callbacks#section-onconnectionstatuschanged).

📘

Throws an ICException if the device is not registered with IMIconnect or if the In App Messaging feature is not enabled.

  Syntax: void disconnect() throws ICException

  Example:

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

fetchMessages

Deprecated, use [fetchMessages(String threadId, Date beforeDate, int limit, ICFetchMessagesCallback callback)](#section-fetchmessages-a-limit-)

Fetches a list of messages that matches the specified criteria. The results are notified through the ICFetchMessagesCallback callback.

  Syntax: fetchMessages(String threadId, Date beforeDate, ICFetchMessagesCallback callback)

fetchMessages

ICMessaging.getInstance().fetchMessages(threadId, beforeDate, limit, new ICFetchMessagesCallback()
{
  @Override
  public void onFetchMessagesComplete(final ICMessage[] messages, final boolean hasMoreData, final ICException exception)
  {
    if (exception != null)
    {
      Log.e("fetchMessages", "fetchMessages failed! Reason:" + exception.toString());
      return;
    }
    
    Log.e("fetchMessages", "fetchMessages success:");
  }
});

fetchStreams

Removed in v2.7.0. - Streams are no longer used by the IMIconnect platform, messages are now routed to services based on app associations.

Fetches the list of streams that are associated to the IMIconnect application.

  Syntax: fetchStreams(final ICFetchStreamsCallback callback)

  Parameters:

ICMessaging.getInstance().fetchStreams(new ICFetchStreamsCallback()
{
  @Override
  public void onFetchStreamsComplete(final ICStream[] streams, final ICException exception)
  {
    if (exception != null)
    {
      Log.e("fetchStreams", "fetchStreams failed! Reason:" + exception.toString());
      return;
    }

    Log.e("fetchStreams", "fetchStreams success:");
  }
});

fetchThreads

Deprecated - Use [fetchThreads(Date, int, ICFetchThreadsCallback)](#section-fetchthreads-a-limit-) instead.

Fetches a list of threads that matches the specified criteria.

Results are reported through the ICFetchThreadsCallback callback and are ordered newest to oldest.

  Syntax: fetchThreads (int limit, ICFetchThreadsCallback callback)

fetchThreads

ICMessaging.getInstance().fetchThreads(beforeDate,10, new ICFetchThreadsCallback()
{
  @Override
  public void onFetchThreadsComplete(final ICThread[] threads, final boolean hasMoreData, final ICException exception)
  {
    if (exception != null)
    {
      Log.e("fetchThreads", "fetchThreads failed! Reason:" + exception.toString());
      return;
    }
    
    Log.e("fetchThreads", "fetchThreads success:");
  }
});

fetchTopics

Fetches the list of topics that are configured for the IMIconnect application.

  Syntax: fetchTopics(int offset, final ICFetchTopicsCallback callback)

  Parameters:

📘

When the topic list is large, IMIconnect will return a subset of the results. Use the offset parameter to fetch subsequent results.

Hint: Use the 'hasMoreData' parameter of the ICFetchTopicsCallback.onFetchTopicsComplete method to determine when there is additional data to fetch. Keep a track of your fetched record count to use as the offset to the next call.

  Example:

ICMessaging.getInstance().fetchTopics(0, new ICFetchTopicsCallback()
{
  @Override
  public void onFetchTopicsComplete(final ICTopic[] topics, final boolean hasMoreData, final ICException exception)
  {
    if (exception != null)
    {
      Log.e("fetchTopics", "fetchTopics failed! Reason:" + exception.toString());
      return;
    }
     
    Log.e("fetchTopics", "fetchTopics success:");
     
  	if (hasMoreData)   
    {
     	//Fetch more, use accumulation of topics.length for offset
      //i.e. offset += topics.length;
    }
   }
});

getConnectionStatus

Returns the current connection status between the SDK and IMIconnect platform.

  Syntax: [ICConnectionStatus](doc:enumerations#section-icconnectionstatus) getConnectionStatus()

  Return Value:
 Returns the current connection status between the SDK and the IMIconnect platform.

getInstance

Returns the ICMessaging singleton instance, creating it if necessary.

  Syntax: ICMessaging getInstance()

  Return Value:
 Returns the ICMessaging singleton instance.

getMessageStore

Obtains the current message store instance, if set previously via a call to [setMessageStore(ICMessageStore)](#section-setmessagestore).

  Syntax: [ICMessageStore](doc:storage-synchronization#section-icmessagestore) getMessageStore()

  Return Value:
 The ICMessageStore instance, if set, otherwise null.

isConnected

This method is used to verify whether the In App Messaging connection is currently connected to IMIconnect. This is a convenience method for getConnectionStatus() == ICConnectionStatus.Connected.

  Syntax: boolean isConnected()

  Return Value:
 Returns true if the RTM connection is currently connected.

isStarted

Used to determine whether ICMessaging has been started.

  Syntax: static boolean isStarted()

  Return Value: Returns true if ICMessaging has been started, otherwise false.

📘

The ICMessaging instance is started automatically when the getInstance method is called.

publishMessage

Publishes a message to the IMIconnect platform.

The [ICMessage ](#section-icmessage) passed to this method must contain a valid ICThread instance.

Results of the operation are reported through [ICPublishMessageCallback](doc:callbacks#section-icpublishmessagecallback).

  Syntax: void publishMessage(ICMessage message, ICPublishMessageCallback callback)

  Parameters:

  Example:

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");
    }
  }
});

registerListener

Registers an [ICMessagingListener](doc:callbacks#section-icmessaginglistener) to listen for incoming messages and connection status updates.

Syntax: void registerListener(ICMessagingListener listener)

setMessageAsRead

Updates the status of a message to Read.

The result of the operation is reported through [ICSetMessageStatusCallback](doc:callbacks#section-icsetmessagestatuscallback).

  Syntax: void setMessageAsRead(String transactionId, ICSetMessageStatusCallback callback)

  Parameters:

  Example:

String messageTransactionId = message.getTransactionId();

ICMessaging.getInstance().setMessageAsRead(messageTransactionId, new ICSetMessageStatusCallback() 
{
  @Override
  public void onSetMessageStatusComplete(final String[] messageTransactionIds, final ICException exception) 
  {
    if (exception != null) 
    {
      Log.e("MessageAsRead", exception.toString());
    } 
    else 
    {
      Log.d("MessageAsRead", "Updated Successfully");
    }
  }
});

setMessagesAsRead

Sets the status for multiple messages to Read.

The result of the operation is reported through [ICSetMessageStatusCallback](doc:callbacks#section-icsetmessagestatuscallback).

  Syntax: void setMessagesAsRead(String[] transactionIds, ICSetMessageStatusCallback callback)

  Parameters:

  Example:

String[] messageTransactionIds = new String[] { "id1", "id2" };

ICMessaging.getInstance().setMessagesAsRead(messageTransactionIds, new ICSetMessageStatusCallback() 
{
  @Override
  public void onSetMessageStatusComplete(final String[] messageTransactionIds, final ICException exception) 
  {
    if (exception != null) 
    {
      Log.e("MessagesAsRead", exception.toString());
    } 
    else 
    {
      Log.d("MessagesAsRead", "Updated Sucessfully");
    }
  }
});

setMessageStore

Sets the [ICMessageStore](doc:storage-synchronization#section-icmessagestore) implementation that the SDK will use to persist In App Message data. Passing a null value will remove any previously set store and disable message persistence.

Syntax: void setMessageStore(ICMessageStore messageStore)

  Parameters:

shutdown

Deprecated - Use [shutdown(ICShutdownCallback)](#section-shutdown-a-callback-) instead.

Provides a means to shutdown the messaging module and perform cleanup. There is normally no need to call this method.

Syntax: void shutdown()

shutdown

ICMessaging.shutdown(new ICShutdownCallback()
{
  @Override
  public void onShutdownComplete()
  {
    Log.d("ICMessaging", "Shutdown Completed");
  }
});

subscribeTopic

Subscribes the current user to a topic. After successful completion, the SDK will receive any future messages that are published to the topic.

The result of the operation is reported through [ICSubscribeTopicCallback](doc:callbacks#section-icsubscribetopiccallback).

  Syntax: void subscribeTopic(String topicId, ICSubscribeTopicCallback callback)

  Parameters:

  Example:

String topic = "<your topicId>";

ICMessaging.getInstance().subscribeTopic(topicId, new ICSubscribeTopicCallback()
{
  @Override
  public void onSubscribeTopicComplete(final String topicId, final ICException exception) 
  {
    if (exception != null) 
    {
      Log.e("SubscribeTopic", exception.toString());
    } 
    else 
    {
      Log.d("SubscribeTopic", "Subscribed Successfully");
    }
  }
});

unregisterListener

Unregisters a previously registered [ICMessagingListener](doc:callbacks#section-icmessaginglistener), in order to stop listening for incoming messages and connection status updates.

Syntax: void unregisterListener(ICMessagingListener listener)

unsubscribeTopic

Unsubscribes the current user from a topic. After successful completion the user will no longer receive future messages sent to the topic.

The result of the operation are reported through [ICUnsubscribeTopicCallback](doc:callbacks#section-icunsubscribetopiccallback).

  Syntax: void unsubscribeTopic(String topicId, ICUnsubscribeTopicCallback callback)

  Parameters:

  Example:

String topicId = "<your topicId>";

ICMessaging.getInstance().unsubscribeTopic(topicId, new ICUnsubscribeTopicCallback() 
{
  @Override
  public void onUnsubscribeTopicComplete(final String topicId, final ICException exception) 
  {
    if (exception != null) 
    {
      Log.e("UnsubscribeTopic", exception.toString());
    } 
    else 
    {
      Log.d("UnsubscribeTopic", "Unsubscribed Successfully");
    }
  }
});

updateThread

Updates a thread within the remote IMIconnect platform.

  Syntax: void updateThread(ICThread thread, final ICUpdateThreadCallback callback)

  Parameters:

ICMessagingReceiver

This class allows the interception of incoming messages and connection status changes, and provides a hook into the push notification generation process. Inherit from this class to substitute or supplement the default functionality. The receiver, or subclass thereof, must be declared within the Android manifest.

//A sample app manifest entry. If you inherit a class from ICMessagingReceiver, replace the name with your class name.

  <receiver
      android:name="YOUR_MESSAGE_RECEIVER_NAME"
      android:enabled="true"
      android:exported="false">
      <intent-filter>
          <action android:name="com.imimobile.connect.core.rtmevent"/>
          <action android:name="com.imimobile.connect.core.notification.click"/>
          <action android:name="com.imimobile.connect.core.intent.notification.RECEIVE"/>
      </intent-filter>
  </receiver>

getNotificationFactory

Override this method to provide a custom ICNotificationFactory implementation in order to customise notifications. It is recommended that you do not return a new instance every time this method is invoked, instead cache your custom instance and return that.

  Syntax: [ICNotificationFactory](#section-icnotificationfactory) getNotificationFactory()

  Return Value:
 The default implementation returns the standard [ICNotificationFactory](#section-icnotificationfactory) instance.

onConnectionStatusChanged

Invoked whenever there is a change to the In App Messaging connection status. The exception parameter will be populated with error information when status == ICConnectionStatus.Error.

  Syntax: void onConnectionStatusChanged(Context context, ICConnectionStatus status, ICException exception)

  Parameters:

onMessageReceived

Invoked whenever a new Push or In App Message is received.

  Syntax: void onMessageReceived(Context context, ICMessage message)

  Parameters:

ICNotificationFactory

This class is responsible for creating local notifications for display on the device. By default, the SDK will only produce notifications for Push messages.

Customisations may be introduced by inheriting from this class and overriding onBuildNotification and getActionIconId.

📘

It is possible to completely replace the default notification generation by overriding createNotification instead of onBuildNotification. In this instance you are responsible for building the complete notification and will not get any of the pre-built interactive message functionality.

createNotification

This method is invoked whenever the SDK needs to generate a notification for an incoming message. Override this method to completely replace the notification generation process. To stop notifications from being displayed it is valid to return null from this method.

  Syntax: Notification createNotification(Context context, ICMessage message, int notificationId, Bitmap bigPicture)

  Parameters:

  Return Value:
 Returns an Android notification.

createNotification

getActionIconId

Override this method to return a drawable resource id to be used for an interactive message action.

  Syntax: int getActionIconId(String action, String identifier, ICMessage message)

  Parameters:

  Return Value:
 The resource id for the icon.

onBuildNotification

This method is invoked at the end of the SDK notification build process and may be used to customise the standard notifications.

  Syntax: void onBuildNotification(Context context, NotificationCompat.Builder builder, ICMessage message, int notificationId)

  Parameters:

ICMessageData

An interface for interacting with message data.

getAttachments

Returns the attachments that are attached to the message.

  Syntax: [ICAttachment](doc:attachments-and-media#section-icattachment)[] getAttachments()

  Return Value: Array of message attachments.

getCategory

Returns the category of the message.

  Syntax: String getCategory()

  Return Value: Returns the category of the message.

getChannel

Returns the channel on which the message was received.

  Syntax: [ICMessageChannel](doc:enumerations#section-icmessagechannel)getChannel()

  Return Value: Returns the message channel.

getCreatedAt

Returns the date on which the message was created.

  Syntax: Date getCreatedAt()

  Return Value: Returns the date on which the message was created.

getCustomTags

Returns any custom tag data that was sent as part of the message.

  Syntax: Bundle getCustomTags()

  Return Value: Returns the data that was sent as part of the message payload.

getDeliveredAt

Returns the date on which the message was delivered to the device.

  Syntax: Date getDeliveredAt()

  Return Value: The message delivery date.

getExtras

Used to get supplementary data that was sent as part of the message payload. The format of this data is controlled by the IMIconnect platform and enables certain standard features such as interactive messages.

  Syntax: Bundle getExtras()

  Return Value: Returns the supplementary data that was sent along with the message payload.

getMessage

Used to get the textual content of the message that is intended for display to the user.

  Syntax: String getMessage()

  Return Value: Returns the textual message that is intended for display to the user.

getPriority

Used to get the priority of the message.

  Syntax: int getPriority()

  Return Value: Returns the priority of the message.

getReadAt

Used to get the date the message was considered as 'read' by the user.

  Syntax: Date getReadAt()

  Return Value: The date the message was read.

getReference

Used to get the message reference (trigger rule) set within IMIconnect.

  Syntax: String getReference()

  Return Value: Returns the reference (trigger rule) of the message.

getStatus

Returns the current status of the message (None/Sent/NotSent/Delivered/Read)

  Syntax: [ICMessageStatus](doc:enumerations#section-icmessagestatus)getStatus()

  Return Value: Returns the current status of the message.

getSubmittedAt

Returns the date on which the message was submitted to the IMIconnect platform.

  Syntax: Date getSubmittedAt()

  Return Value: Message submission date.

getThread

Returns an ICThread instance representing the thread to which the message belongs.

  Syntax: [ICThread](#section-icthread) getThread()

  Return Value: The [ICThread](#section-icthread) to which the message belongs.

getTransactionId

Gets the transaction id that uniquely identifies the message within the IMIconnect platform.

  Syntax: String getTransactionId()

  Return Value: Returns the transaction id that identifies the message.

getType

Returns the type of the message.

  Syntax: [ICMessageType](doc:enumerations#section-icmessagetype) getType()

  Return Value: Returns the message type. See [ICMessageType](doc:enumerations#section-icmessagetype) enumeration for details of the possible options.

getUserId

Returns the user id to which the message belongs. This should always be equivalent to the currently registered user.

  Syntax: String getUserId()

  Return Value: Returns the user id to which the message belongs.

isOutgoing

Used to determine whether a message is outgoing (sent by the user) or incoming (sent to the user).

  Syntax: boolean isOutgoing()

  Return Value: Returns 'true' if message is outgoing

ICMessage

This class provides a concrete implementation of the [ICMessageData](#section-icmessagedata) interface to express In App and Push channels in a generalised form and is used when receiving messages to or sending messages from the SDK. In addition to the class specific methods listed below, reference the [ICMessageData](#section-icmessagedata) class for interface method details.

fromJSON

Returns an ICMessage instance from a JSONObject. The JSONObject must contain valid ICMessage data.

  Syntax: static ICMessage fromJSON(JSONObject jsonObj)

  Return Value: An ICMessage instance or null if the jsonObj parameter was null.

getMedia

Deprecated - Use [getAttachments](#section-getattachments) instead.

Returns any media files that are attached to the message.

  Syntax: [ICMediaFile](doc:attachments-and-media#section-icmediafile)[] getMedia()

  Return Value:
 Returns the media files that were attached to the message or null if no media file attachments exist.

getTitle

Gets the message title, if present.

  Syntax: String getTitle()

  Return Value: Returns message title if present.

setAttachments

Used to set the attachments which will be sent with an outgoing message.

  Syntax: setAttachments(final ICAttachment[] attachments)

  Parameters:

setCustomTags

This method is used to set the custom tags bundle to be sent with an outgoing RTM. This method is not applicable to Push messaging.

  Syntax: void setCustomTags(Bundle tags)

  Parameters:

getCustomTags

This method is used to return any custom tag data that was sent as part of the message.

  Syntax: Bundle getCustomTags()

  Returns: Returns the data that was sent as part of the message payload.

setDeliveredAt

Sets the date on which the message is considered delivered to the device.

The SDK sets the delivered status automatically when a message is received, there should be no need to call this method manually.

  Syntax: void setDeliveredAt(Date date)

  Parameters:

setMedia

Deprecated - Use [setAttachments](#section-setattachments) instead.

Attaches the specified media files to the message.

  Syntax: void setMedia(ICMediaFile[] files)

  Parameters:

setMessage

Used to set the textual part of the message.

  Syntax: void setMessage(String message)

  Parameters:

setReadAt

Sets the date on which the message was considered as Read.

  Syntax: void setReadAt(Date date)

  Parameters:

setStatus

Sets the status of the message.

This method has limited use as message status is generally inferred based on delivered and read at dates. i.e. a message with a read at date is considered to be in the Read status.

  Syntax: void setStatus(ICMessageStatus status)

  Parameters:

setThread

Sets the thread instance to which the message belongs.

A valid thread instance must be assigned to a message before it can be published.

When replying to an existing thread, obtain the thread instance from an existing incoming message or from [fetchMessages](#section-fetchmessages).

When publishing to a new thread, instantiate a new ICThread instance and use [createThread](#section-createthread) to provision the thread within the IMIconnect platform before attempting to publish.

  Syntax: void setThread(ICThread thread)

  Parameters:

toJSON

Returns a JSON representation of the message.

  Syntax: JSONObject toJSON()

  Return Value: Message data as a JSONObject

ICThread

Within IMIconnect all In App messages are compartmentalised into logical threads of conversation. The ICThread class is the local representation of thread data within the IMIconnect SDK.

Threads can be managed via the SDK using the methods exposed by the [ICMessaging](#section-icmessaging) class and support data attributes such as title, category, status and extras.

Before messages can be published from the SDK a thread must be provisioned within the IMIconnect platform via [ICMessaging.createThread](#section-createthread) or via the [web APIs](doc:api-reference#create-thread-1).

When replying to an existing thread, obtain a ICThread instance from an incoming [ICMessage](#section-icmessage) or from the [ICMessaging.fetchThreads](#section-fetchthreads) method.

fromJSON

getCategory

getCreatedAt

getExternalId

Gets the external id associated to the thread. An external id is a value that may be used to associate the thread with an entity in an external system.

  Syntax: String getExternalId()

  Return Value: The external id, if present, otherwise null.

getExtras

getId

Gets the unique identifier of the thread. This value is generated by the IMIconnect platform when the thread is provisioned.

  Syntax: String getId()

  Return Value: The thread id.

getStatus

getTitle

getType

getUpdatedAt

Returns the date on which the thread was last updated. Changes to thread data, or publication of messages on the thread, will affect this date.

  Syntax: Date getUpdatedAt()

  Return Value: The date the thread was last updated.

setCategory

setExternalId

Sets the external id value. External ids can be used to associate a thread with an entity in an external system.

  Syntax: void setExternalId(String externalId)

  Parameters:

setExtras

Sets extra data to be associated with the thread.

  Syntax: void setExtras(Bundle extras)

  *Parameters:

setTitle

Sets the thread title.

  Syntax: void setTitle(String title)

  Parameters:

toJSON

ICTopic

This class represents a topic within the IMIconnect platform.

IMIconnect supports topic based messaging, where users may subscribe to, and receive messages on, specific topics of interest.

fromJSON

getCreatedOn

getDescription

This method is used to get topic description.

  Syntax: String getDescription()

  Return Value: Returns description of topic.

getGroup

This method is used to get the topic’s group.

  Syntax: String getGroup()

  Return Value: Returns the topic's group.

getId

getName

Returns the name of the topic.

The topic name is the textual identifier used to reference the topic within IMIconnect.

  Syntax: String getName()

  Return Value: Returns the name of the topic.

getTitle

isSubscribed

Returns whether the current user is subscribed to the topic.

  Syntax: boolean isSubscribed()

  Return Value: Returns true if the current user is subscribed to the topic.

toJSON