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.



Events have three functions:


Adds a listener to this event.


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


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

addListener syntax



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


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


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


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


In this example the extension "" sends a message to the extension "":

// sender: === ""

// Send a message to the extension whose ID is ""
browser.runtime.sendMessage("", "my message");
// recipient: === ""

function handleMessage(message, sender) {
  // check that the message is from ""
  if ( === "") {
    // process message


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