runtime.onMessageExternal
=========================

Use this event to listen for messages from other extensions or web pages.

By default, an extension can receive messages from any other extension. However, the `externally_connectable` manifest key can be used to limit communication to specific extensions and enable communication with websites.

To send a message that is received by the `onMessageExternal` listener, use `runtime.sendMessage()`, passing the ID of the recipient in the `extensionId` parameter.

Along with the message itself, the listener is passed:

* a `sender` object giving details about the message sender
* a `sendResponse` function that the listener can use to send a response back to the sender.

This API can't be used in a content script.

Syntax
------


```js
browser.runtime.onMessageExternal.addListener()
browser.runtime.onMessageExternal.removeListener(listener)
browser.runtime.onMessageExternal.hasListener(listener)
```


Events have three functions:

`addListener(listener)`

Adds a listener to this event.

`removeListener(listener)`

Stop listening to this event. The `listener` argument is the listener to remove.

`hasListener(listener)`

Checks whether a `listener` is registered for this event. Returns `true` if it is listening, `false` otherwise.

addListener syntax
------------------

### Parameters

`listener`

The function called when this event occurs. The function is passed these arguments:

`message`

`object`. The message itself. This is a JSON-ifiable object.

`sender`

A `runtime.MessageSender` object representing the sender of the message.

`sendResponse`

A function to call, at most once, to send a response to the message. The function takes a single argument, which may be any JSON-ifiable object. This argument is passed back to the message sender.

If you have more than one `onMessageExternal` listener in the same document, then only one may send a response.

To send a response synchronously, call `sendResponse` before the listener function returns. To send a response asynchronously, do one of these:

* keep a reference to the `sendResponse` argument and return `true` from the listener function. You can then call `sendResponse` after the listener function has returned.
* return a `Promise` from the listener function and resolve the promise when the response is ready.


Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

In this example the extension "blue@mozilla.org" sends a message to the extension "red@mozilla.org":


```js
// sender: browser.runtime.id === "blue@mozilla.org"

// Send a message to the extension whose ID is "red@mozilla.org"
browser.runtime.sendMessage("red@mozilla.org", "my message");
```



```js
// recipient: browser.runtime.id === "red@mozilla.org"

function handleMessage(message, sender) {
  // check that the message is from "blue@mozilla.org"
  if (sender.id === "blue@mozilla.org") {
    // process message
  }
}

browser.runtime.onMessageExternal.addListener(handleMessage);
```


**Note:** This API is based on Chromium's `chrome.runtime` API. This documentation is derived from `runtime.json` in the Chromium code.