< Back to Package Overview
Working with Instant Messaging
The messaging service API provides instant messaging functionality to the client application. Further, it takes care of retrieving data from the server, managing and performing business logic on this data and finally presenting it to the UI layer. It provides core instant messaging functions for clients served by AMM server:
- Network connectivity (through network provider)
- Query messaging capabilities (from AMM server)
- Query/start conversations
- Send messages (with attachments)
- Mark messages as read
- Query/invite conversation participants
- Leave conversations
Most of the API calls allow a listener to passed in to handle success/fail.
Initializing and Configuring the MessagingService
The CSMessagingService object is obtained from the Client SDK's CSUser object. Start by obtaining any existing service configuration, enable the service and configure the AMM parameters supplied by your administrator. Refer to Configuring the SDK for more information.
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;
To successfully register to the AMM server a password corresponding to the username will be required. Passwords are requested by and communicated to the Client SDK using the <CSCredentialProvider> interface.
After you instantiate and set up any required configuration objects, you are now ready to create the CSUser and then call the start method of your CSUser to start all services. Then you can get the CSMessagingService for its further usage.
CSMessagingService *messagingService = user.messagingService;
Creating a conversation
First, create new CSMessagingConversation and then call the start method of your CSMessagingConversation object. Then you can add a participant to the 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 conversation successfully");
}
} else {
// Feature request has been successfully completed.
// Add code to update the UI.
}
}
[conversation startWithCompletionHandler:completionHandler];
Creating a message
Once a CSMessagingConversation has been created successfully, a new CSMessage can be created and sent in the scope of the 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 a new CSMessage has been received in the scope of the existing CSMessagingConversation your application will be notified via didAddMessages. The content of the received message should be added to active conversation.
- (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]);
}
}
Creating a message with an Attachment
CSMessage is a crucial part of the CSMessagingConversation. An important part of the CSMessage is also attachments. You can attach Audio (".m4a"), Video (".mp4") and Pictures (".jpg") to your CSMessage.
In order to create a new CSMessagingAttachment in a CSMessage object, use the createAttachment method and then set the desired values (location, name, MIME types, etc.) for this CSMessagingAttachment object.
To remove an CSMessagingAttachment from the CSMessage use removeAttachment method. Operation success or failure is reported through the completion handler. You can also download the CSMessagingAttachment from the CSMessage by specifying the path to write file. To start the download of the CSMessagingAttachment asynchronously you can use the download() method. To cancel the download, use the cancel() method.
Note: More information on messages with attachments can be found in the article Adding Support for Multimedia Messages.
