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

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

Events have three functions:

addListener(callback)

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

function

A callback function that is 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

Examples

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

// 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"
  );

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