onMessage

Implement interactive two-way communication between your component/template and the server

Summary

optional function onMessage(payload, options, callback)

Parameters	Description
payload	An object containing the onMessage payload as provided by your component file.
options	An options object with key value pairs representing the requesting user's options and their value
callback	A Node.js style callback which should return a response payload or empty object

If implemented, the onMessage method is used to process messages sent from the components sendIntegrationMessage method.

The onMessage method should always return an object (even an empty object) via its callback.

Parameters

payload

The payload parameter is an object containing the information passed from the integration component's sendIntegrationMessage method.

options

The second parameter to the onMessage method is the options object which contains the values for the integration options as set in the integration config.js. Note that for per-user settings the value in the options object will reflect the value of the user requesting the lookup.

The key in the options object is the same value of the key property set in the integration config.js file.

// sample options object
{
    "apiKey": "lkasjdioajsdoij12lk3j1lk23j12",
    "lookupHashes": true,
    "throttleLookups": false
}

callback(error, response)

The callback must be called before execution of the onMessage method completes. The callback accepts two parameters.

error

The first parameter is an error which can either be a string literal or an error object. In the case of a string literal the returned string is displayed as an error in the notification window as well as tracked as an error in the integration.

If you have no error to return you should return null for the error parameter.

response

The second parameter is the response parameter. The response parameter should consist of a JavaScript object that you wish to send back to the integration. Note that the object you provide will be serialized into JSON. As a result, objects such as JavaScript Dates() will be serialized into their string representation.

The response must always be wrapped in a JavaScript object literal. For example, you cannot just send a plain string back. If you don't need to send any information back then you MUST send back an empty object {}.

Examples

Basic Usage

The following example will return the message "Hello World!" along with a server incremented counter.

integration.js

let counter = 0;
function onMessage(payload, options, cb) {
    cb(null, {
        reply: `Hello World! ${++counter}`
    });
}

If you don't need to return any data from your onMessage method, the method MUST return an empty object.

integration.js

function onMessage(payload, options, cb) {
    cb(null, {});
}

Handling Multiple Message Types

If you want to handle different message types you can include a type property in your onMessage payload. For example, the payload might looks like this:

Example onMessage Payload

{
    "type": "create",
    "data": {
        // data properties
    }
}

You can then use a switch statement to branch to different logic depending on the type of the payload.

function onMessage(payload, options, cb) {
    switch (payload.type) {
        case 'create':
            cb(null, {
                result: 'Created Entry'
            });
            break;
        case 'delete':
            cb(null, {
                result: 'Deleted Entry'
            });
            break;
        default:
            cb("Unexpected message type");
    }
}