< Back to Package Overview

Adding support for multimedia messages

The messaging service API provides instant messaging functionality to the client application. It deals with retrieving data from the server, managing and performing business logic on this data and finally, presenting it to the UI layer. This API attempts to use closures where possible.

• Network connectivity
• Query messaging capabilities (from the AMM server)
• Query/start conversations
• Send messages (with attachments)
• Mark messages as read
• Query/invite conversation participants
• Leave conversations
• IM address validation

Most of the API calls allow a listener to pass in to handle success or fail.

MessagingService Capabilities

CSMessagingService supports different features based on its type. To recognize whether the feature is available or not, you need to check the appropriate capability. UI elements should be enabled, disabled or hidden depending on these capabilities. Such capabilities exist at the CSMessagingService level:

Initializing and Configuring the MessagingService

The CSMessagingService object is obtained from the Client SDK CSUser object.

Note: More information on service configuration can be found in the article Configuring the SDK.

Enable the service and configure the AMM parameters supplied by your administrator:

userConfig.AMMConfiguration.enabled = YES;

userConfig.AMMConfiguration.server =
[CSServerInfo serverWithHostName: ""
        port:"" secure:TLS];

//the poll refresh interval in minutes
userConfig.AMMConfiguration.pollingIntervalInMinutes = 0;
userConfig.AMMConfiguration.credentialProvider = messagingCredentialProvider;

Valid username and password are required to successfully register to the AMM server. The password required for the AMM service is not defined as a part of the service configuration. Passwords are requested by and communicated to the Client SDK using the <CSCredentialProvider> protocol.

Note: More information on how to manage passwords using <CSCredentialProvider> can be found in the article Working with Credentials.

After you instantiate and set up required configuration objects, now you are ready to create CSUser and then call the start method of your CSUser to start all services. Then you can get CSMessagingService for its further usage.

CSMessagingService *messagingService = user.messagingService;

Conversation Capabilities

These capabilities exist on the Client SDK CSMessagingConversation object:

Retrieval of active conversations

The retrieveActiveConversationsWithWatcher method retrieves the dynamically updated collection of conversations that are associated with the currently logged in user. Normally, the client application will only need to call this method once to install a watcher object to monitor the initial download of conversations and then continue to watch for updates to the collection.

if (self.conversationsWatcher == nil) {
    self.conversationsWatcher = [[CSDataRetrievalWatcher alloc] init];
    [self.conversationsWatcher addDelegate:self];
    [messagingService retrieveActiveConversationsWithWatcher:
        self.conversationsWatcher];
}

Creating a conversation

First, create new CSMessagingConversation and then call the start method of your CSMessagingConversation object. Then you can add a participant to CSMessagingConversation by specifying a valid extension and domain.

CSMessagingConversation *newConversation = 
    [messagingService createConversation];
void (^messagingCompletionHandler)(NSError* error) = 
    ^(NSError* error) {
        if (error) {
            [conversation addParticipantAddresses:participants 
            completionHandler:^(NSArray *participants, NSError *error) {
            if (error) {
                LOG_ERROR(@"Cannot add participant to conversation: %@", error);
            }
            else {
                LOG_MESSAGE(@"Participant was added to convers. successfully");
            }
        } else {
            // Feature request has been successfully completed.
            // Add code to update the UI.
        }
    }

[conversation startWithCompletionHandler:completionHandler];

Message Capabilities

These capabilities exist on the Client SDK CSMessage object:

Creating a message

Once CSMessagingConversation has been created successfully, new CSMessage can be created and sent in the scope of CSMessagingConversation.

CSMessage *newMessage = [conversation createMessage];
[newMessage setBodyAndReportTyping:arguments[@"body"] 
    completionHandler:^(NSError *error) {
        if (error) {
            LOG_ERROR(@"Cannot set message body: %@", error);
        }
        else {
            LOG_MESSAGE(@"Message body changed");
        }
    }];

Receive messages

If new CSMessage has been received in the scope of existing CSMessagingConversation your application will be notified via didAddMessages. The content of received message should be added to active CSMessagingConversation.

- (void)messagingConversation:(CSMessagingConversation *)messagingConversation 
    didAddMessages:(NSArray *)messages {
        for (CSMessage *message in messages) {
            [self addMessageObject:message];
            LOG_MESSAGE(@"Conversation ID %@ added message with ID: %@",
                [messagingConversation conversationId], [message  messageId]);
        }
    }

Marking as read

To mark selected CSMessage as read use the markAsRead method of the CSMessage object.

if (message.markAsReadCapability.allowed) {

    [message markAsRead];
}

You can also mark all content in CSMessagingConversation as read using the markAllContentAsReadWithCompletionHandler method.

if (message.markAllContentAsReadCapability.allowed) {
    [conversation markAllContentAsReadWithCompletionHandler:^(NSError *error) {
        if (error) {
            LOG_ERROR(@"Cannot mark conversation content as read: %@", error);
        }
    }];
}

Attachment Capabilities

These capabilities exist on the Client SDK CSMessagingAttachment object:

Creating a message with an attachment

CSMessage is a crucial part of CSMessagingConversation. An important part of CSMessage is also represented as attachments. In order to create new CSMessagingAttachment in the CSMessage object, use the createAttachment method. You can attach Audio (".m4a"), Video (".mp4") and Pictures (".jpg") to your CSMessage. First, create new CSMessagingAttachment in the CSMessage object via the createAttachment method and then set desired values (location, name, MIME types, etc.) for this attachment object.

CSMessagingAttachment *attachment = [draftMessage createAttachment];

[attachment setName:[self.fileToBeAttached lastPathComponent] 
    completionHandler:^(NSError *error) {
        if (error) {
            LOG_ERROR(@"Error while setting name of attachment: %@", error);
        } 
        else {
            LOG_MESSAGE(@"Successfully set name of attachment");
        }
}];

[attachment setIsThumbnail:NO completionHandler:^(NSError *error) {
    if (error) {
        LOG_ERROR(@"Error while setting 'IsThumbnail' attribute: %@", error);
    } 
    else {
        LOG_MESSAGE(@"Successfully set 'IsThumbnail' attribute of attachment");
    }
}];

[attachment setIsGeneratedContent:NO completionHandler:^(NSError *error) {
    if (error) {
        LOG_ERROR(@"Error while setting 'IsGeneratedContent' attribute 
            of attachment: %@", error);
    } 
    else {
        LOG_MESSAGE(@"Successfully set 'IsGeneratedContent' attribute");
    }
}];

[attachment setLocation: [NSString stringWithFormat:@"%@", 
    self.fileToBeAttached.path] completionHandler:^(NSError *error) {
        if (error) {
            LOG_ERROR(@"Error while setting location of attachment: %@", error);
        } 
        else {
            LOG_MESSAGE(@"Successfully set location of attachment");
        }
    }];

[attachment setMimeType:@"*/*" completionHandler:^(NSError *error) {
        if (error) {
            LOG_ERROR(@"Error while setting MimeType of attachment: %@", error);
        } 
        else {
            LOG_MESSAGE(@"Successfully set mime type of attachment");
        }
}];

To remove CSMessagingAttachment from CSMessage, use the removeAttachment method. Operation success or failure is reported through the completion handler.

[message removeAttachment:attachment completionHandler:^(NSError *error) {
    if (error) {
        LOG_ERROR(@"Cannot remove attachment: %@", error);
    } 
    else {
        [messagingHandler removeAttachmentObject:attachment];
        LOG_MESSAGE(@"Attachment removed");
    }
}];

Now you are ready to send your draft CSMessage using the methods described above in the article.

Downloading an attachment

You can download CSMessagingAttachment from CSMessage by specifying the path to write the file to. To start downloading CSMessagingAttachment asynchronously you can use the download method.

[messagingHandler addMessagingAsynchDataRetrievalObject:attachment 
    retrieval:[attachment download:path completionHandler:^(NSError *error) {
        [messagingHandler removeMessagingAsynchDataRetrievalObject:attachment];

        if(error) {
            LOG_ERROR(@"Error while downloading attachment: %@", error);
        } 
        else {
            if(!attachment.consume) {
                LOG_ERROR(@"Cannot get location for consumption");
            }
            else {
                LOG_MESSAGE(@"Attachment was saved to: %@", attachment.consume);
            }
        }
    }]];

Once the file is downloaded in Documents directory of Application, developer can move the file as per requirement (e.g. move images and videos to Photo Library).

You can cancel downloading CSMessagingAttachment as follows:

CSMessagingAsynchDataRetrieval *retrieval = 
    [messagingHandler asynchDataRetrievalForAttachment:attachment];

LOG_MESSAGE(@"Canceling attachment download...");
if (retrieval) {
    [retrieval cancel];
    [messagingHandler removeMessagingAsynchDataRetrievalObject:attachment];
    LOG_MESSAGE(@"Attachment download canceled");
}
else {
    LOG_ERROR(@"Cannot find retrieval object");
}

Please note that the location of attachments is not stored across user session. Therefore, after logout/login there are no local storage paths and the client needs to download attachments again.