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.
Most of the API calls allow a listener to pass in to handle success or fail.
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:
Capability | Conditions Required | Property to check Capability |
---|---|---|
Create Conversation | The Client is connected to the messaging server. | createConversationCapability |
Remove Conversation | The Conversation is in the draft state. | removeConversationCapability |
Retrieve Conversation | The Client is connected to the messaging server. The messaging server supports Retrieve. | retrieveConversationCapability |
Search Conversation | The Client is connected to the messaging server. The messaging server supports Search. | searchConversationCapability |
Update Refresh Mode | The Client is connected to the messaging server. The messaging server supports changing the refresh mode. | updateRefreshModeCapability |
Validate Participant Addresses | The Client is connected to the messaging server. The messaging server supports validation of participant addresses. | validateParticipantAddressesCapability |
Automatically Update Last Access Time | The Client is connected to the messaging server. The messaging server supports automatic update of conversation last access timestamps. | automaticallyUpdateLastAccessTimeCapability |
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;
These capabilities exist on the Client SDK CSMessagingConversation object:
Capability | Conditions Required | Property to check Capability |
---|---|---|
Create Message | The Client is connected to the messaging server. The Conversation is in the draft state and has been started, or the Conversation is in the published state. | createMessageCapability |
MarkAllContentAsRead | The Client is connected to the messaging server. The messaging server supports marking all content in the conversation as read. The Conversation is published. | markAllContentAsReadCapability |
Update Subject | The Client is connected to the messaging server. The messaging server supports changing the subject of the Conversation. The Conversation is active. The Conversation is either draft or published. | updateSubjectCapability |
Update Last Access Time Capability | The Client is connected to the messaging server. The messaging server supports changing the LastAccessTime of the Conversation. The Conversation is published. | updateLastAccessedTimeCapability |
Leave | The Client is connected to the messaging server. The Conversation is in the published state. | leaveCapability |
Add Participants | The Client is connected to the messaging server. The Conversation is active. The Conversation is either draft or published. | addParticipantsCapability |
Remove Participants | The Conversation is in the draft state. | removeParticipantsCapability |
Update Sensitivity | The Conversation is in the draft state. | updateSensitivityCapability |
Older Content | The Client is connected to the messaging server. The Conversation is published. | olderContentCapability |
Start | The Conversation is in the draft state and has not yet been started. | startCapability |
Remove | The Conversation is in the draft state. | removeCapability |
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];
}
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];
These capabilities exist on the Client SDK CSMessage object:
Capability | Conditions Required | Property to check Capability |
---|---|---|
Update Body | The Message is in the draft or error state. | updateBodyCapability |
Update InReplyTo | The Message is in the draft or error state. | updateInReplyToCapability |
Update DoNotForward | The Message is in the draft or error state. | updateDoNotForwardCapability |
Update Importance | The Message is in the draft or error state. | updateImportanceCapability |
Create Attachment | The Message is in the draft or error state. | createAttachmentCapability |
Send | The Client is connected to the messaging server. The Message is in the draft or error state. | sendCapability |
MarkAsRead | The Client is connected to the messaging server. The messaging server supports marking messages as read. The Message is published. | markAsReadCapability |
Remove | The Message is in the draft or error state. | removeCapability |
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");
}
}];
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]);
}
}
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);
}
}];
}
These capabilities exist on the Client SDK CSMessagingAttachment object:
Capability | Conditions Required | Property to check Capability |
---|---|---|
Update Name | The Attachment is in the draft or error state. | updateNameCapability |
Update IsThumbnail | The Attachment is in the draft or error state. | updateIsThumbnailCapability |
Update IsGeneratedContent | The Attachment is in the draft or error state. | updateIsGeneratedContentCapability |
Update Location | The Attachment is in the draft or error state. | updateLocationCapability |
Update MIME Type | The Attachment is in the draft or error state. | updateMimeTypeCapability |
Download | The Client is connected to the messaging server. The Attachment is in the "ready to download" state. | downloadCapability |
Consume | The Attachment is in the "downloaded" or "consumed" state. | consumeCapability |
Remove | The Attachment is in the draft or error state. | removeCapability |
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.
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);
}
}
}]];
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.