Conversations

The Webex Connect UI SDK for iOS builds on the message transport capabilities exposed within the Core SDK through a collection of customisable user interface components. These components may be used to easily integrate a fully-featured rich messaging capability within a host application.

ICConversationsViewController

Displays a list of conversations for the current user and a floating action button for creating a new conversation, use this view controller when you wish to integrate a conversation list within your own layouts.

The view controller does not open or create new conversations directly, instead, events are raised through the ICConversationsViewControllerDelegate and it is your responsibility to write the code in response to those events if you are not using ICConversationSplitViewController.

Message data is lazily loaded from a local ICMessageStore and remotely from the Webex Connect backend services. To achieve the best possible user experience it is recommended that you configure an appropriate message synchronization policy within the Core SDK in order to pre-fetch data.

Prerequisites

This component loads data from ICMessageStore and therefore requires that a valid instance is set within the Core SDK, please refer to ICMessaging messageStore.

If you are not using ICConversationSplitViewController, you must implement the ICConversationsViewControllerDelegate.

Properties

delegate

ICConversationsViewControllerDelegate

The delegate of the ICConversationsViewController

avatar

UIImage

The avatar that will be displayed next to each conversation

Methods

Syntax

Description

(void) reload

Reloads the whole conversation list

Responding to events

Whenever a user selects a conversation or taps the create conversation button, the appropriate event will be raised through the ICConversationsViewControllerDelegate interface.

ICConversationsViewControllerDelegate

Methods:

Syntax

Description

  • (void)conversationsViewController: (ICConversationsViewController)conversationsViewController didSelectThread:(ICThread )thread

Invoked when a user selects a conversation within the view controller. Conversations are represented by an ICThread object, please refer to the Core SDK documentation for details. Typically, you will use the id within ICThread to open the conversation.

  • (void)conversationsViewControllerDidSelectCreateThread: (ICConversationsViewController *)conversationsViewController

Invoked when a user taps the conversations view create button.

  • (void)conversationsViewControllerDidTapOnBackButton:(ICConversationsViewController *)conversationsViewController;

Invoked when a user taps the conversations view back button.

ICInboxTableView

This component displays a list of conversations that are provided via the dataSource.

Styling:
This class allows you to customise the conversations table view.

Properties:

inboxDataSource

id

See ICInboxTableViewDataSource description

inboxDelegate

id

See ICInboxTableViewDelegate

cellFactory

ICMessageTableViewCellFactory

See ICMessageTableViewCellFactory description

selectedIndexes

NSMutableArray

The selected indexes

backgroundColor

UIColor

The table view background color

Sample Code

[[ICInboxTableView appearance] setBackgroundColor:[UIColor lightGrayColor]];

Methods:

Syntax

Description

  • (void) reloadMessages

Reloads the inbox display.

  • (void)addMessagePartViewFactory:(id)messagePartViewFactory forContentType:(NSString *)contentType

Adds a messagePartViewFactory instance in the list of all messagePartViewFactories

  • to create the MessagePartView
  • The content type is used to retrieve the good factory
  • based on the content type of the encountered message part.
  • (void)enableMultipleSelection:(BOOL)isEnabled

Enables the multiple row selection

  • (void)scrollToMessage:(id)messageData animated:(BOOL)animated

Scrolls to a message in the inbox

ICInboxTableViewDataSource

Contains the methods needed to populate the ICInboxTableView with some data

Methods:

Syntax

Description

  • (NSInteger)numberOfMessagesInInboxTableView:(ICInboxTableView *)inboxTableView

Tells the data source to return the number of messages that will be displayed in the inbox table view

  • (id)inboxTableView:(ICInboxTableView )inboxTableView messageDataForRowAtIndexPath:(NSIndexPath )indexPath

Asks the data source the message data that will be represented by the cell

  • (NSArray )inboxTableView:(ICInboxTableView )inboxTableView messagePartsFromMessageData:(id)messageData

Asks the data source the message part that will be displayed for a message data

  • (NSInteger)inboxTableView:(ICInboxTableView )inboxTableView numberOfUnreadMessagesAtIndexPath:(NSIndexPath )indexPath

Tells the data source to return the number of unread messages for the cell

  • (BOOL)inboxTableView:(ICInboxTableView )inboxTableView shouldDisplayUnreadIndicatorAtIndexPath:(NSIndexPath )indexPath

Tells the data source to display the unread indicator

  • (UIImage )inboxTableView:(ICInboxTableView )inboxTableView avatarForMessageData:(id)messageData

Asks the data source to provide the avatar for a specified message

ICInboxTableViewDelegate

Contains the methods needed to handle an event on the ICInboxTableView.

Methods:

Syntax

Description

  • (CGFloat)inboxTableView:(ICInboxTableView )inboxTableView heightForMessageCellAtIndexPath:(NSIndexPath )indexPath

Asks the data source for the height to use for a message cell in a specified location.

  • (void)inboxTableView:(ICInboxTableView )inboxTableView didSelectMessageDataAtIndexPath:(NSIndexPath )indexPath

Tells the delegate that a message has been selected

  • (void)inboxTableView:(ICInboxTableView )inboxTableView didDeleteMessageDataAtIndexPath:(NSIndexPath )indexPath

Tells the delegate that a message has been deleted

ICInboxMessageTableViewCell

This component is a concrete implementation of the ICMessageTableViewCell.

Styling:

This class allows you to customise the conversations list.

Properties:

dateFont

UIFont

The font of the date label

dateTextColor

UIColor

The text color of the date label

badgeFont

UIFont

The font of the badge label

badgeTextColor

UIColor

The text color of the badge

badgeBackgroundColor

UIColor

The background color of the badge

badgeCornerRadius

CGFloat

The corner radius of the badge

unreadMessageFont

UIFont

The unread message font

unreadMessageTextColor

UIColor

The unread message text color

unreadDateFont

UIFont

The unread date font

unreadDateTextColor

UIColor

The unread date text color

readMessageFont

UIFont

The read message font

readMessageTextColor

UIColor

The read message text color

titleFont

UIFont

The font of the title label

titleTextColor

UIColor

The text color of the title label

containerTextColor

UIColor

The container text color

Sample Code

[[ICInboxMessageTableViewCell appearance] setTitleTextColor:[UIColor blueColor]];
[[ICInboxMessageTableViewCell appearance] setDateTextColor:[UIColor redColor]];
[[ICInboxMessageTableViewCell appearance] setReadMessageTextColor:[UIColor redColor]];

ICMessageTableViewCellFactory

This factory has the responsibility to create all the table view cells that will be displayed in the inbox.

Syntax

Description

(NSString )reuseIdentifierForMessageData:(id) messageData from MessageParts:(NSArray ) messageParts :(NSDictionary *) messagePartViewFactories

Retrieves an identifier used to reuse an existing cell

(ICMessageTableViewCell )cellForIdentifier:(NSString )identifier fromMessageParts:(NSArray ) messageParts with MessagePartViewFactories:(NSDictionary ) messagePartViewFactories

Creates a cell that will represent the message parts passed in parameter

ICConversationViewController

Displays messages within a conversation and provides a message composer.

Messages are displayed to the user in chronological order and new messages can be composed and published directly from the view controller. Supports typing indicators, delivery and read receipts, message attachments, and connection indicator.

Message data is lazily loaded from a local ICMessageStore and remotely from the Webex Connect backend services. To achieve the best possible user experience, it is recommended that you configure an appropriate message synchronization policy within the Core SDK in order to pre-fetch data.

Prerequisites

This component loads data from ICMessageStore and therefore requires that a valid instance is set within the Core SDK, please refer to ICMessaging messageStore.

Properties:

thread

ICThread

See the ICThread description.

flavor

ICMessageComposerFlavor

See the ICMessageComposerFlavor description.

delegate

id

See the ICConversationViewControllerDelegate description

Methods:

Syntax

Description

(void) reloadMessages

Reload all the messages of the current conversation

Styling

ICMessageComposerFlavor

This class allows you to customize the composer. You can select the plugins that will be displayed in the composer and the composer style.

Properties:

plugins

NSArray

An array of plugins that will be displayed in the composer.

style

ICMessageComposerStyle

See ICMessageComposerStyle description

Methods:

Syntax

Description

  • (instancetype)flavorWithStyle:(ICMessageComposerStyle ) style plugins:(NSArray )plugins;

Instantiates an ICMessageComposerFlavor with a style and some plugins

ICMessageComposerStyle

Determines the style (color and appearances) of the message composer.

Properties:

composerBackgroundColor

UIColor

The composer background color

borderWidth

CGFloat

The border width

borderColor

UIColor

The border color

cornerRadius

CGFloat

The corner radius

backgroundColor

UIColor

The background color

messageTextColor

UIColor

The message text color

messageFont

UIFont

The message font

ICConversationCollectionView

This component will display the incoming and outgoing messages in some bubbles.

Properties:

conversationDataSource

id

See ICConversationCollectionViewDataSource description

conversationDelegate

id

See ICConversationCollectionViewDelegate description

cellFactory

ICMessageCollectionViewCellFactory

See ICMessageCollectionViewCellFactory description

isScrollingTop

BOOL

Informs if the user is currently scrolling to top

backgroundColor

UIColor

The background color of the conversation collection view

Methods:

Syntax

Description

(void) reloadMessages

Reloads the conversation display.

(void) addMessagePartViewFactory:(id)messagePartViewFactory forContentType:(NSString )contentType

Adds a messagePartViewFactory instance in the list of all messagePartViewFactories to create the MessagePartView.
The content type is used to retrieve the good factory based on the content type of the encountered message part.

(void) scrollToBottomAnimated:(BOOL)animated

Scrolls the conversation collection view to the bottom

(void) scrollToMessage:(id)messageData animated:(BOOL)animated

Scrolls to a message in the conversation

ICConversationCollectionViewDataSource

Contains the methods needed to populate the ICConversationCollectionView with some data

Methods:

Syntax

Description

(NSInteger) conversationCollectionView:(ICConversationCollectionView) conversationCollectionView numberOfMessagesForMessageGroup:(NSString *) messageGroup

Tells the data source to return the number of messages that will be displayed in the conversation collection view

(id)conversationCollectionView:(ICConversationCollectionView) conversationCollectionView messageDataForItemAtIndex:(NSInteger)index forMessageGroup:(NSString )messageGroup

Asks the data source the message data that will be represented by the cell

(NSArray )conversationCollectionView:(ICConversationCollectionView) conversationCollectionView messagePartsFromMessageData:(id)messageData

Asks the data source the message part that will be displayed for a message data

(NSInteger)numberOfMessageGroupsInConversationCollectionView:(ICConversationCollectionView) conversationCollectionView

Tells the data source to return the number of groups that will be displayed in the conversation collection view

(NSString)conversationCollectionView:(ICConversationCollectionView) conversationCollectionView messageGroupAtIndex:(NSInteger) index

Asks the data source the message group that will be displayed at an index

(BOOL)conversationCollectionView:(ICConversationCollectionView)conversationCollectionView shouldDisplayStatusForMessageData:(id) messageData

Asks the data source to return the bool value of messages that will be displayed in the conversation collection view

ICConversationCollectionViewDelegate

It contains the methods needed to handle an event on the ICConversationCollectionView.

Methods:

Syntax

Description

  • (CGFloat)conversationCollectionView:(ICConversationCollectionView) conversationCollectionView heightForMessageCellAtIndexPath:(NSIndexPath *) indexPath

Asks the delegate for the height to use for a message cell in a specified location.

  • (CGFloat)conversationCollectionView:(ICConversationCollectionView) conversationCollectionView heightForMessageGroupAtIndex:(NSInteger)index

Asks the delegate for the height to use for a message group in a specified location.

  • (void)conversationCollectionView:(ICConversationCollectionView) conversationCollectionView didSelectAttachmentMessagePart:(ICMediaMessagePart *) mediaMessagePart

Tells the delegate that an attachment has been selected

  • (void)conversationCollectionView:(ICConversationCollectionView) conversationCollectionView didRemoveMessagePart:(id) messagePart

Tells the delegate that a message part has been deleted

  • (void)conversationCollectionView:(ICConversationCollectionView) conversationCollectionView didSelectRetryForMessageData:(id) messageData

Tells the delegate that the user is trying to re-send a message

ICAlertMessageCollectionViewCell

Displays an alert event in the ICConversationCollectionView. This alert could be a conversation that is now closed or reopened for example.

Styling:
This class allows you to customise the alert message collection view cell inside a conversation.

Properties:

containerBackgroundColor

UIColor

The container background color.

containerCornerRadius

CGFloat

The corner radius of the bubble.

containerTextColor

UIColor

The text color of the container.

containerFont

UIFont

The font of the container.

Sample Code

[[ICAlertMessageCollectionViewCell appearance] setContainerBackgroundColor:[UIColor blackColor]];
[[ICAlertMessageCollectionViewCell appearance] setContainerCornerRadius:10.0f];    
[[ICAlertMessageCollectionViewCell appearance] setContainerTextColor:[UIColor lightGrayColor]];
[[ICAlertMessageCollectionViewCell appearance] setContainerFont:[UIFont systemFontOfSize:12.0f weight:UIFontWeightRegular]];

ICIncomingMessageCollectionViewCell

Displays the incoming messages in the ICConversationCollectionView. It has the appearance of a bubble.

Styling:

This class allows you to customise the incoming messages inside a conversation.

Properties:

containerBackgroundColor

UIColor

The container background color.

containerCornerRadius

CGFloat

The corner radius of the bubble.

containerTextColor

UIColor

The text color of the container.

containerFont

UIFont

The font of the container.

timeFont

UIFont

The font of time label

Sample Code

[[ICIncomingMessageCollectionViewCell appearance] setContainerBackgroundColor:[UIColor redColor]];
[[ICIncomingMessageCollectionViewCell appearance] setContainerCornerRadius:10.0f];
[[ICIncomingMessageCollectionViewCell appearance] setContainerTextColor:[UIColor redColor]];
[[ICIncomingMessageCollectionViewCell appearance] setContainerFont:[UIFont systemFontOfSize:15.0f weight:bold]];
[[ICIncomingMessageCollectionViewCell appearance] setTimeFont:[UIFont systemFontOfSize:12.0f weight:bold]];

Methods:

Syntax

Description

(void) showFooter

Shows the footer of the cell.

(void) hideFooter

Hides the footer of the cell.

ICOutgoingMessageCollectionViewCell

Displays the outgoing messages in the ICConversationCollectionView. It has the appearance of a bubble.

Styling:

This class allows you to customise the outgoing messages inside a conversation.

Properties:

containerBackgroundColor

UIColor

The container background color.

containerCornerRadius

CGFloat

The corner radius of the bubble.

containerTextColor

UIColor

The text color of the container.

containerFont

UIFont

The font of the container.

messageStateFont

UIFont

The message state font.

timeFont

UIFont

The font of the time.

Sample Code

[[ICOutgoingMessageCollectionViewCell appearance] setContainerBackgroundColor:[UIColor redColor]];
[[ICOutgoingMessageCollectionViewCell appearance] setContainerCornerRadius:10.0f];   
[[ICOutgoingMessageCollectionViewCell appearance] setContainerTextColor:[UIColor redColor]];
[[ICOutgoingMessageCollectionViewCell appearance] setContainerFont:[UIFont systemFontOfSize:15.0f weight:bold]];
[[ICOutgoingMessageCollectionViewCell appearance] setMessageStateFont:[UIFont systemFontOfSize:12.0f weight:bold]];
[[ICOutgoingMessageCollectionViewCell appearance] setTimeFont:[UIFont systemFontOfSize:12.0f weight:bold]];

Methods:

Syntax

Description

(void) showFooter

Shows the footer of the cell.

(void) hideFooter

Hides the footer of the cell.

(void)showStatus:(BOOL)status

Shows the message status label of the cell

ICConversationHeaderCollectionReusableView

Displays the group where the messages belong. Those groups represents by default the day when the messages have been received.

Styling:
This class allows you to customise the header view of the collection view inside a conversation.

Properties:

messageGroupFont

UIFont

The message group font.

messageGroupTextColor

UIColor

The message group text color.

Sample Code

[[ICConversationHeaderCollectionReusableView appearance] setMessageGroupFont:[UIFont systemFontOfSize:12.0f weight:UIFontWeightRegular]];
[[ICConversationHeaderCollectionReusableView appearance] setMessageGroupTextColor:[UIColor lightGrayColor]];

Methods:

Syntax

Description

(void)setMessageGroup:(NSString *)messageGroup;

Sets the name of the message group.

ICMessageCollectionViewCellFactory

This factory has the responsibility to create all the collection view cells that will be displayed in the conversation.

Methods:

Syntax

Description

(NSString )reuseIdentifierForMessageData:(id) messageDatafromMessageParts:(NSArray)messagePartswithMessagePartViewFactories:(NSDictionary *) messagePartViewFactories

Retrieves an identifier used to reuse an existing cell.

(UINib )nibForIdentifier:(NSString ) identifier
fromMessageParts:(NSArray ) messageParts
withMessagePartViewFactories:(NSDictionary
) messagePartViewFactories

Retrieves the nib associated to the current identifier in order to be registered to be used in the conversation cell.

(Class)classForIdentifier:(NSString )identifier
fromMessageParts:(NSArray
) messageParts
withMessagePartViewFactories:(NSDictionary *) messagePartViewFactories

Retrieves the class associated with the current identifier in order to be registered to be used in the conversation cell.

ICConversationSplitViewController

This view controller leverages the functionality of the lower-level components and provides the necessary wiring to combine them into a fully-featured in-app chat experience with minimal code.

The activity supports the display of the user conversation list and provides a means to open them or create new conversations. Selecting a conversation displays the conversation view and allows users to read, compose and send messages.

Prequisites

This component requires that a valid ICMessageStore instance is set within the Core SDK.

Adaptive Layout

The layout of the view controller adapts to the device display, typically when running on a iPhone the activity will display the conversation list full screen, when a conversation is displayed this replaces the conversation list display. Navigating back from the conversation will cause the conversation list to be re-displayed.

When running on an iPad, the layout is split into two sections. The conversation list is shown on the left and the active conversation is shown on the right.

Properties:

categories

NSMutableArray

The categories that should be displayed to the user when he will create a new conversation

customerDetails

ICCustomerDetails

See ICCustomerDetails

avatar

UIImage

The avatar that will be displayed next to every conversation

hideBackButton

BOOL

Hides back button, if value is true.

conversationViewController

ICConversationViewController

See the ICConversationViewController

conversationsViewController

ICConversationsViewController

See the ICConversationsViewController

ICConversationCategoryViewController

The ICConversationCategoryViewController displays a list of conversation categories.

Categories are represented by ICConversationCategory instances, these instances may be nested to create a hierarchy of categories. The view controller displays one level of categories at a time when the user taps a category the fragment with either:

(a) Where the category has sub-categories, displays the list of sub-categories
(b) Where the category does not have sub-categories, raise an event via the

Properties:

categories

NSMutableArray

The categories that isdisplayed to the user while creating a new conversation

delegate

id

The ICConversationCateogryViewController delegate

Interaction

The view controller displays a single level of categories at a time, if a category is selected which has sub-categories then the sub-category list replaces that which is currently shown. Pressing the back button will navigate up one level in the hierarchy.

When a final selection is made the selection is raised as an event through the ICConversationCategoryViewControllerDelegate. A final selection is determined as a category that has no sub-categories.

ICConversationCategoryViewControllerDelegate

Methods:

Syntax

Description

(void)conversationCategoryViewController:
(ICConversationCategoryViewController )conversationCategoryViewController didSelectConversationCategory:(ICConversationCategory )conversationCategory parentCategory:(ICConversationCategory *)parentCategory

Invoked when a final category selection is made.

ICConversationCategory

Organizations typically have multiple contact points to which a customer may be directed depending on their query. Conversation categories provide the means to drive users to the correct contact point.

The information contained in a ICConversationCategory instance is also used to establish the correct communication stream for a conversation. Within Webex Connect, real-time messages are sent over a stream, the stream is used to direct messages to the correct service to process the message.

Properties:

title

NSString

The title of the category.

streamName

NSString

The stream name of the category.

image

UIImage

The image of the category.

subCategories

NSMutableArray

the sub categories.

Methods:

Syntax

Description

(instancetype)initWithTitle:(NSString )title streamName:(NSString )streamName

Instantiates an ICConversationCategory instance with a title and a streamName

(instancetype)initWithTitle:(NSString )title streamName:(NSString )streamName image:(UIImage *)image

Instantiates an ICConversationCategory instance with a title, a streamName and an image

(instancetype)initWithTitle:(NSString )title streamName:(NSString )streamName image:(UIImage )image subCategories:(NSMutableArray )subCategories

Instantiates an ICConversationCategory instance with a title, a streamName, an image and subcategories

ICCustomerDetails

Certain integrations, such as IMIchat, allow customer details to be sent to the agent serving customer requests. This class encapsulates that information.

Properties:

firstName

NSString

The customer's first name

lastName

NSString

The customer's last name

email

NSString

The customer's email

phoneNumber

NSString

The customer's phone number

Methods:

Syntax

Description

(instancetype)initWithDictionary:(NSDictionary *)dictionary

Instantiates an ICCustomerDetails with a dictionary

(NSDictionary *)dictionary

Retrieves a dictionary from the customer details object

ICConnectionStatusView

The view is displayed to show the current connection status with the message broker.
3 statuses can be displayed: “Connected.”, “Connecting…” and “Disconnected.”

Styling:
This class allows you to customise the connection status view in conversations screen.

Properties:

disconnectedBackgroundColor

UIColor

The disconnected background color

disconnectedTextColor

UIColor

The disconnected text color

connectingBackgroundColor

UIColor

The connecting background color

connectingTextColor

UIColor

The connecting text color

connectedBackgroundColor

UIColor

The connected background color

connectedTextColor

UIColor

The connected text color

connectionStatus

ICConnectionStatus

The current connection status

Sample Code

[[ICConnectionStatusView appearance] setDisconnectedBackgroundColor:[UIColor redColor]];
[[ICConnectionStatusView appearance] setDisconnectedTextColor:[UIColor blackColor]];    
[[ICConnectionStatusView appearance] setConnectingBackgroundColor:[UIColor orangeColor]];
[[ICConnectionStatusView appearance] setConnectingTextColor:[UIColor blackColor]];    
[[ICConnectionStatusView appearance] setConnectedBackgroundColor:[UIColor greenColor]];
[[ICConnectionStatusView appearance] setConnectedTextColor:[UIColor whiteColor]];

ICConversationButton

This button allows the user to open a new conversation screen. Some features will be added to that component in the future.

Styling:

This class allows you to customise the conversation button.

Properties:

buttonBackgroundColor

UIColor

The conversation’s button background color

buttonTintColor

UIColor

The conversation’s tint background color

buttonTextColor

UIColor

The conversation’s text background color

buttonCornerRadius

CGFloat

The conversation’s corner radius

shouldShowBadge

BOOL

Determines if the badge should be shown

badgeTextColor

UIColor

The conversation badge's text color

badgeBackgroundColor

UIColor

The conversation badge's background color

badgeCornerRadius

CGFloat

The conversation badge's corner radius

delegate

id

See ICConversationButtonDelegate Description

Sample Code

[[ICConversationButton appearance] setButtonBackgroundColor:[UIColor redColor]];
[[ICConversationButton appearance] setButtonTintColor:[UIColor blueColor]];    
[[ICConversationButton appearance] setButtonTextColor:[UIColor blueColor]];    
[[ICConversationButton appearance] setButtonCornerRadius:10.0f];

ICConversationButtonDelegate

Methods:

(void)conversationButtonShouldStartConversation:(ICConversationButton *)conversationButton

Informs that a new conversation should be started

(void)conversationButton:(ICConversationButton ) conversationButton shouldOpenConversationWithThread:(ICThread ) thread

Informs that a conversation should be opened with a thread

(void)conversationButtonShouldOpenConversations:(ICConversationButton *)conversationButton

Informs that the conversation list should be opened