> For the complete documentation index, see [llms.txt](https://docs.polarity.io/integrations/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.polarity.io/integrations/build-an-integration/main/onmessage.md).

# onMessage

## 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](/integrations/build-an-integration/customizing-the-overlay-window/component-file.md#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](/integrations/build-an-integration/customizing-the-overlay-window/component-file.md#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.

```javascript
// 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](/integrations/build-an-integration/main/dolookup/error-objects.md). 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.

{% hint style="info" %}
If you have no error to return you should return `null` for the `error` parameter.
{% endhint %}

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

{% code title="integration.js" %}

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

{% endcode %}

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

{% code title="integration.js" %}

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

{% endcode %}

### 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:

{% code title="Example onMessage Payload" %}

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

{% endcode %}

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

```javascript
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");
    }
}
```