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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.polarity.io/integrations/build-an-integration/main/onmessage.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.