index.md

---

title: runtime.onConnectExternal
slug: Mozilla/Add-ons/WebExtensions/API/runtime/onConnectExternal
page-type: webextension-api-event
tags:
  - API
  - Add-ons
  - Event
  - Extensions
  - Non-standard
  - Reference
  - WebExtensions
  - onConnectExternal
  - runtime
browser-compat: webextensions.api.runtime.onConnectExternal

---

{{AddonSidebar()}}

Fired when an extension receives a connection request from a different extension.

To send a message which will be received by the onConnectExternal listener, use {{WebExtAPIRef("runtime.connect()")}}, passing the ID of the recipient in the extensionId parameter.

The listener is passed a {{WebExtAPIRef('runtime.Port')}} object which it can then use to send and receive messages. The Port object also contains a sender property, which is a {{WebExtAPIRef("runtime.MessageSender")}} object, and which the recipient can use to check the sender's ID.

Syntax

browser.runtime.onConnectExternal.addListener(listener)
browser.runtime.onConnectExternal.removeListener(listener)
browser.runtime.onConnectExternal.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:

    • port

      • : A {{WebExtAPIRef('runtime.Port')}} object connecting the current script to the other extension it is connecting to.

Browser compatibility

{{Compat}}

Examples

In this example the extension Hansel connects to the extension Gretel:

console.log("connecting to Gretel");
let myPort = browser.runtime.connect(
  "[email protected]"
);

myPort.onMessage.addListener((message) => {
  console.log(`From Gretel: ${message.content}`);
});

browser.browserAction.onClicked.addListener(() => {
  myPort.postMessage({content: "Hello from Hansel"});
});

Gretel listens for the connection and checks that the sender is really Hansel:

let portFromHansel;

browser.runtime.onConnectExternal.addListener((port) => {
  console.log(port);
  if (port.sender.id === "[email protected]") {
    console.log("connection attempt from Hansel");
    portFromHansel = port;
    portFromHansel.onMessage.addListener((message) => {
      console.log(`From Hansel: ${message.content}`);
    });
  }
});

browser.browserAction.onClicked.addListener(() => {
   portFromHansel.postMessage({content: "Message from Gretel"});
});

{{WebExtExamples}}

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