< 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.

• 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 return promise, that can handle success or fail.

MessagingService Capabilities

Messaging 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 Messaging level:

Initializing and Configuring the MessagingService

The Messaging object is obtained from the Client SDK User object. The UserConfiguration object is used to define the services that are available to the end users of your application. Each service is configured individually. Its configuration is stored in a dedicated object referenced from the UserConfiguration object.

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

Start by obtaining any existing service configuration:

var userConfiguration = new AvayaClientServices.Config.UserConfiguration();

var ammConfiguration = userConfiguration.ammConfiguration;

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

ammConfiguration.enabled = true;

var serverInfo = new AvayaClientServices.Config.ServerInfo("",
    "",
    TLS);   // True if connection to the server is required to be secure;

ammConfiguration.networkProviderConfiguration = new AvayaClientServices.Config.NetworkProviderConfiguration(serverInfo);

//the poll refresh interval in minutes
ammConfiguration.pollingIntervalInMinutes = 0;

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 CredentialProvider interface:

var messagingCredentialProvider = new AvayaClientServices.Config.CredentialProvider("", "");

ammConfiguration.credentialProvider = messagingCredentialProvider;

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

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

var messagingService = user.getMessaging();

Conversation Capabilities

These capabilities exist on the Client SDK Conversation object:

Retrieval of active conversations

The getActiveConversations() 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.

var conversationsRetrieval = messagingService.getActiveConversations();
var conversationsSet = conversationsRetrieval.getDataSet();

conversationsSet.addOnDataSetChangedCallback(function (conversations, type) {
    if (type === AvayaClientServices.Base.DataSetChangeTypes.ADDED) {
            // Conversations added;
    } else if (type === AvayaClientServices.Base.DataSetChangeTypes.UPDATED) {
            // Conversations update;
    } else if (type === AvayaClientServices.Base.DataSetChangeTypes.REMOVED) {
            // Conversations removed;
    }
});

Creating a conversation

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

var newConversation = messagingService.createConversation();
newConversation.start().then(function () {
        newConversation.addParticipantAddresses(addresses).then(function ([]) {
            // Participants added successfully;
        }, function (error) {
            // Participants does not added successfully;
        })
    }, function (error) {
        // Update UI elements that new conversation was not started
    });

Message Capabilities

These capabilities exist on the Client SDK Message object:

Creating a message

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

var message = newConversation.createMessage();

message.setBodyAndReportTyping("");

message.send().then(function () {
        // Message sent successfully;
    }, function (error) {
        // Message does not sent successfully;
    });

Receive messages

If new Message has been received in the scope of existing Conversation your application will be notified via messages.addOnDataSetChangedCallback(). The content of received Message should be added to active Conversation.

var messages = newConversation.getMessages();
messages.addOnDataSetChangedCallback(function ([]) {
    // Display received messages on UI
});

When your application receives the onNumberOfConversationsWithUnreadContentSinceLastAccessChanged() callback, you need to retrieve all active conversations via the getActiveConversations() method to update the list of current conversations. This callback is called to report that the number of conversations with unread content has changed since the last accessed time. Only new content since the last time when Conversation was accessed, will be flagged.

messagingService.addOnNumberOfConversationsWithUnreadContentSinceLastAccessChanged(function ({}, ) {
    messagingService.getActiveConversations();
});

Marking as read

To mark selected Message as read use the markAsRead() method of the Message object.

if (message.getMarkAsReadCapability().isAllowed) {
    message.markAsRead();
}

You can also mark all content in Conversation as read using the markAllContentAsRead() method.

if (conversation.getMarkAllContentAsReadCapability().isAllowed) {
    conversation.markAllContentAsRead(function ({}) {
        //Successfully marked all content as read;
    }, function (error) {
        //Failure marking all content as read;
    });
}   

Attachment Capabilities

These capabilities exist on the Client SDK Attachment object:

Creating a message with an attachment

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

var attachment = message.createAttachment();

attachment.setName("");

To remove Attachment from Message, use the removeDraftAttachment() method.

var attachments = message.getAttachments();
if (attachments[0]) {
    message.removeDraftAttachment(attachments[0]);
}

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

Downloading an attachment

You can download Attachment from Message by getting the URL to file. To get Attachment downloading URL you can use the getDownloadURL() method.

if (message.hasAttachment()) {
    var attachments = message.getAttachments();
    if (attachments[0]) {
        attachments[0].getDownloadURL();
    }
}