< 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
- 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 passed in to handle success or fail.
Initializing and Configuring the MessagingService
The MessagingService object is obtained from the Client SDK's User 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.
AMMConfiguration ammConfiguration = userConfiguration.AmmConfiguration;
ammConfiguration.Enabled = true;
ammConfiguration.ServerInfo = new ServerInfo("",
"",
TLS); // True if the connection to the server is required to be secure;
//the poll refresh interval in minutes
ammConfiguration.PollIntervalInMinutes = ((uint)(0));
ammConfiguration.CredentialProvider =
new UserNamePasswordCredentialProvider("","","");
The valid username and password are required to successfully register to the AMM server. Passwords are requested by and communicated to the Client SDK using the ICredentialProvider interface. For more information about credentials handling in Client SDK please refer to Working with Credentials.
Finally save your configuration back to your UserConfiguration object.
userConfiguration.AmmConfiguration = ammConfiguration;
After you instantiate and set up any required configuration objects, you are now ready to create the User and then call the start() method of your User to start all services. Then you can get the MessagingService for its further usage.
MessagingService messagingService = mUser.MessagingService;
Creating a conversation
First, create new Conversation and then call the start() method of your Conversation object. Then you can add a participant to the Conversation by specifying a valid extension and domain.
Conversation newConversation = messagingService.CreateConversation();
newConversation.Start((error) =>
{
if (error == null)
{
// Update UI elements: Start conversation succeeded
}
else
{
// Update UI elements: Start conversation failed
}
});
newConversation.AddParticipantAddresses(addresses, (newConversation,
participants, error) =>
{
if (error == null)
{
// Update UI elements: Add participant succeeded
}
else
{
// Update UI elements: Add participant failed
}
});
Creating a message
Once a Conversation has been created successfully, a new Message can be created and sent in the scope of the Conversation.
Message message = newConversation.createMessage();
message.SetBodyAndReportTyping(messageBody, (arg) =>
{
if (arg == null)
{
CreatedMessage.Send((sendArg) =>
{
if (sendArg == null)
{
// Update UI elements: Send message succeeded
}
else
{
// Update UI elements: Send message failed
}
});
}
else
{
// Update UI elements: Failed to set message text
}
});
Receive messages
If a new Message has been received in the scope of the existing Conversation your application will be notified via DataCollectionChangedEventArgs. The content of the received message should be added to active conversation.
private void DataRetrievalCollectionChanged(object sender,
DataCollectionChangedEventArgs e)
{
if (e.ChangeType == DataCollectionChangeType.ItemsAdded)
{
ProcessNewMessages(e.ChangedItems);
}
else if (e.ChangeType == DataCollectionChangeType.ItemsUpdated)
{
ProcessUpdatedMessages(e.ChangedItems);
}
}
Creating a message with an attachment
Message is a crucial part of the Conversation. An important part of the Message is also attachments. You can attach Audio (".m4a"), Video (".mp4") and Pictures (".jpg") to your Message.
In order to create a new Attachment in a Message object, use the CreateAttachment() method and then set the desired values (location, name, MIME types, etc.) for this Attachment object.
To remove an Attachment from the Message use RemoveAttachment() method. Operation success or failure is reported through the completion handler. You can also download the Attachment from the Message by specifying the path to write file. To start the download of the Attachment 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.
