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, the listener is passed:
- a
sender
object with 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.
See runtime.onMessage
for additional information on receiving messages and sending responses, as well as examples of the various options for sending responses.
Syntax
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. Returnstrue
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. 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 one argument, which is a 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 can send a response.To send a response synchronously, call
sendResponse()
before the listener function returns.To send a response asynchronously, use one of these options:
-
Return a
Promise
from the listener function and resolve the promise when the response is ready. This is the preferred approach. -
Keep a reference to the
sendResponse()
argument and returntrue
from the listener function. You then callsendResponse()
after the listener function returns.Note: Promise as a return value is not supported in Chrome until Chrome bug 1185241 is resolved. As an alternative, return
true
and usesendResponse
as described forruntime.onMessage
.
-
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);
Browser compatibility
Report problems with this compatibility data on GitHubdesktop | mobile | ||||||
---|---|---|---|---|---|---|---|
onMessageExternal | |||||||
Respond with Promise |
Legend
Tip: you can click/tap on a cell for more information.
- Full support
- Full support
- Partial support
- Partial support
- No support
- No support
- Has more compatibility info.
Note:
This API is based on Chromium's chrome.runtime
API. This documentation is derived from runtime.json
in the Chromium code.