An example subscription is for the statuses of various users in the Interaction Center system. To create this subscription, the client application must use the PUT /icws/{sessionId}/messaging/subscriptions/status/user-statuses method and provide a list of userIds that the application is interested in receiving status information for. The following shows an example of how a client application might create a user status subscription for two users whose userIds are user1 and user2.

// This example snippet assumes the existence of a helper
// method for sending a request to the active ICWS session.
var sendRequest = function(httpMethod, path, requestPayload, responseCallback) { };

// The type of the message associated with the user-statuses subscription
userStatusMessageType = 'urn:inin.com:status:userStatusMessage'

/**
 * Starts the subscription for users statuses for user1 and user2.
 * @see stopUserStatusSubscription
 */
function startUserStatusSubscription() {
    // The PUT request requires a list of userIds
    payload = { userIds:['user1', 'user2'] };

    session.sendRequest('PUT', '/messaging/subscriptions/status/user-statuses', payload, 
        function(status, jsonResponse) {
            if ((status >= 200) && (status <= 299)) {
                // Subscription was started
            }
            else {
                // There was an error starting the subscription.
                // Details are in the jsonResponse.
                throw new Error(jsonResponse)
            }
        });
}

/**
 * Stops the subscription for users statuses.
 * @see startUserStatusSubscription
 */
function stopUserStatusSubscription() {
    // The DELETE request does not take any payload values.
    payload = {};

    session.sendRequest('DELETE', '/messaging/subscriptions/status/user-statuses', payload, 
        function(status, jsonResponse) {
            if ((status >= 200) && (status <= 299)) {
                // Subscription was stopped
            }
            else {
                // There was an error stopping the subscription.
                // Details are in the jsonResponse.
                throw new Error(jsonResponse)
            }
        });
}

function displayUserStatuses(userStatusMessage) {
    var statusIndex, statusCount, currentStatus;
    
    if (!userStatusMessage.isDelta) {
        // If the message is not a delta, we must clear all previous 
        // information and prepare for refreshed information
        clearStatusDisplay();
    }
    
    // process the userStatusMessage to update the display
    statusCount = userStatusMessage.userStatusList.length;
    for (statusIndex = 0; statusIndex < statusCount; statusIndex++) {
        currentStatus = userStatusMessage.userStatusList[statusIndex];
        
        updateStatusForUser(currentStatus.userId, currentStatus.statusId);
    }
}

// Register a callback with the message channel (see example in the Retrieving Messages section)
// Note: The registration happens before the subscription is started to ensure no messages are missed.
registerMessageCallback(userStatusMessageType, displayUserStatuses);

// Start the subscription
startUserStatusSubscription();

// The subscription can be stopped using the following:
stopUserStatusSubscription();

Back to top

The following provides a simple example of retrieving pending messages from JavaScript.

// This example snippet assumes the existence of a helper
// method for sending a request to the active ICWS session.
var sendRequest = function(httpMethod, path, requestPayload, responseCallback) { };

// This example snippet assumes the existence of a helper function:
// A function determining whether server-sent events messaging is supported by inspecting the messaging feature version (supported in messaging version 2).
var isServerSentEventsSupportedOnServer = function() {};

// Dictionary of ICWS message __type ID to the callback (type: icwsMessageCallback)
// to invoke when that message is received.
var icwsMessageCallbacks = {};
var messageProcessingTimerId;
var eventSourceInstance;

// Polling interval for retrieving ICWS message queue.
var ICWS_MESSAGE_RETRIEVAL_INTERVAL_MS = 1000;

/**
 * Sets the callback for a particular type of ICWS message.
 * @param {String} messageType The ICWS message type. (ex: urn:inin.com:status:userStatusMessage)
 * @param {icwsMessageCallback} messageCallback The callback to invoke with the message details.
 * @throws {Error} The messageCallback was undefined.
 * @throws {Error} A callback is already registered for the specified messageType.
 */
function registerMessageCallback(messageType, messageCallback) {
    if (messageCallback === undefined) {
        throw new Error('Invalid argument "messageCallback".');
    }
    
    if (!icwsMessageCallbacks[messageType]) {
        icwsMessageCallbacks[messageType] = messageCallback;
    } else {
        throw new Error('Message callback already registered for message type: ' + messageType);
    }
};

/**
 * Starts the message processing mechanism, if not already running.
 * @see stopMessageProcessing
 */
function startMessageProcessing() {
    if (isServerSentEventsSupportedOnServer() && typeof EventSource !== 'undefined') {
        if (!eventSourceInstance || eventSourceInstance.readyState === EventSource.CLOSED) {
            var messagingUrl = getSessionUrl('/messaging/messages');
 
            eventSourceInstance = new EventSource(messagingUrl, {
                withCredentials: true // Allows the Cookie HTTP request header to be sent
            });
 
            eventSourceInstance.onmessage = onServerSentEventMessage;
        }
    } else {
        // Only send the next request once the previous result has been received.
        function runTimerInstance() {
            messageProcessingTimerCallback();
            messageProcessingTimerId = setTimeout(runTimerInstance, ICWS_MESSAGE_RETRIEVAL_INTERVAL_MS);
        }
        
        if (!messageProcessingTimerId) {
            runTimerInstance();
        }
    }
}

/**
 * Stops the message processing mechanism, if running.
 * @see startMessageProcessing
 */
function stopMessageProcessing() {
    if (eventSourceInstance) {
        if (eventSourceInstance.readyState !== EventSource.CLOSED) {
            eventSourceInstance.stop();
        }
    } else if (!!messageProcessingTimerId) {
        clearTimeout(messageProcessingTimerId);
        messageProcessingTimerId = null;
    }
}

/**
 * Implements the message processing mechanism timer callback.
 * @see startMessageProcessing
 * @see stopMessageProcessing
 */
function messageProcessingTimerCallback() {
    var payload, messageIndex, messageCount, jsonMessage, messageType, messageCallback;
    
    // The messaging GET request does not take any payload values.
    payload = {};

    sendRequest('GET', '/messaging/messages', payload, function(status, jsonResponse) {
        if ((status >= 200) && (status <= 299)) {
            // Process retrieved messages.
            messageCount = jsonResponse.length;
            for (messageIndex = 0; messageIndex < messageCount; messageIndex++) {
                jsonMessage = jsonResponse[messageIndex];
                messageType = jsonMessage.__type;
                
                // For each message, invoke a registered message callback if there is one.
                messageCallback = icwsMessageCallbacks[messageType];
                if (messageCallback) {
                    messageCallback(jsonMessage);
                } else {
                    // No registered message handler.
                }
            }
        }
    });
    
 /**
 * Handles eventSourceInstance's message event and relays it to the correct callback.
 * @param {Event} event The onmessage event data.
 * @see stopMessageProcessing
 */
function onServerSentEventMessage(event) {
    var message, messageType, messageCallback;
    try {
       // Process the data off of the event. It is a JSON string.
       var message = JSON.parse(event.data);
       messageType = message.__type;
 
       // Invoke a registered message callback if there is one.
       messageCallback = icwsMessageCallbacks[messageType];
       if (messageCallback) {
           messageCallback(jsonMessage);
       } else {
           // No registered message handler.
       }
    }
    catch (error) {
       // Failed to process message.
    }
}
}

Back to top