Handling IMatch WebServices™ Messages

IMatch WebServices™ Messages

This document how IMatch WebServices™ send messages via the web socket.

The IMatch engine works behind both IMatch and IMWS. It generates messages to inform interested receivers about events like file updated or category changed.

Depending on the operations performed by the user, IMWS may send a few messages per minute, or several hundred messages per second! For example, if a user changes the rating of 100 files, this produces more than 300 messages (rating changed, rating collection changed, file history updates, ...).

Message Format

To keep messages short, IMWS uses a compact JSON-based message format with mandatory and optional elements. The meaning of the optional elements depends on the major and minor message code.

The IMWS Event Code enumeration lists all messages and explains the meaning of the message elements. The following table describes the principal message format.

maNoThe major message code or message group.
miNoThe minor message code.
d1YesFirst numerical element. This element usually contains a file or folder id or similar.
d2YesSecond numerical element. This element contains additional ids. For example, if a file is copied, this d2 contains the id of the new file while d1 contains the id of the original file.
d3YesThird numerical element.
s1YesFirst string element. May contain data like file names.
s2YesSecond string element.

Handling Messages

To receive messages from IMWS, you create a web socket with IMWS.openWebSocket method and then listen to incoming messages via onmessage.


IMWS.webSocket().onmessage = function(e) {
    // Parse the message from string format into JSON.
    var msg = JSON.parse(e.data);
    if (msg.ma == IMWS.EVENT_CODES.evObjectUpdate) {
        switch (msg.mi) {
        case IMWS.EVENT_CODES.evOUFileAdd:
            // A file was added to the database. d1 contains the id of the new file.


For a working example, see the App Spy sample app.