runtime.onMessageExternal

Use this event to listen for messages from another extension.

To send a message which will be 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 which it 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 will be called when this event occurs. The function will be passed the following 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:

• either keep a reference to the sendResponse argument and return true from the listener function. You will then be able to call sendResponse after the listener function has returned.
• or return a Promise from the listener function and resolve the promise when the response is ready.

Browser compatibility

Examples

In this example the extension "[email protected]" sends a message to the extension "[email protected]":

// sender: browser.runtime.id == "[email protected]"

// Send a message to the extension whose ID is "[email protected]"
browser.runtime.sendMessage(
    "[email protected]",
    "my message"
  );

// recipient: browser.runtime.id == "[email protected]"

function handleMessage(message, sender) {
  // check that the message is from "[email protected]"
  if (sender.id === "[email protected]") {
    // process message
  }
}

browser.runtime.onMessageExternal.addListener(handleMessage);