---
title: Channel Messaging API
slug: Web/API/Channel_Messaging_API
tags:
  - API
  - Channel messaging
  - HTML API
  - Overview
  - Reference
translation_of: Web/API/Channel_Messaging_API
---
<p>{{DefaultAPISidebar("Channel Messaging API")}}</p>

<p class="summary">The <strong>Channel Messaging API</strong> allows two separate scripts running in different browsing contexts attached to the same document (e.g., two IFrames, or the main document and an IFrame, two documents via a {{domxref("SharedWorker")}}, or two workers) to communicate directly, passing messages between one another through two-way channels (or pipes) with a port at each end.</p>

<p>{{AvailableInWorkers}}</p>

<h2 id="Channel_messaging_concepts_and_usage">Channel messaging concepts and usage</h2>

<p>A message channel is created using the {{domxref("MessageChannel.MessageChannel", "MessageChannel()")}} constructor. Once created, the two ports of the channel can be accessed through the {{domxref("MessageChannel.port1")}} and {{domxref("MessageChannel.port2")}} properties (which both return {{domxref("MessagePort")}} objects.) The app that created the channel uses <code>port1</code>, and the app at the other end of the port uses <code>port2</code> — you send a message to <code>port2</code>, and transfer the port over to the other browsing context using {{domxref("window.postMessage")}} along with two arguments (the message to send, and the object to transfer ownership of, in this case the port itself.)</p>

<p>When these transferable objects are transferred, they are 'neutered' on the previous context — the one they previously belonged to. For instance a port, when is sent, cannot be used anymore by the original context. Note that the only two objects that can currently be transferred are {{domxref("ArrayBuffer")}} and {{domxref("MessagePort")}}.</p>

<p>The other browsing context can listen for the message using {{domxref("MessagePort.onmessage")}}, and grab the contents of the message using the event's <code>data</code> attribute. You could then respond by sending a message back to the original document using {{domxref("MessagePort.postMessage")}}.</p>

<p>When you want to stop sending messages down the channel, you can invoke {{domxref("MessagePort.close")}} to close the ports.</p>

<p>Find out more about how to use this API in <a href="/en-US/docs/Web/API/Channel_Messaging_API/Using_channel_messaging">Using channel messaging</a>.</p>

<h2 id="Channel_messaging_interfaces">Channel messaging interfaces</h2>

<dl>
 <dt>{{domxref("MessageChannel")}}</dt>
 <dd>Creates a new message channel to send messages across.</dd>
 <dt>{{domxref("MessagePort")}}</dt>
 <dd>Controls the ports on the message channel, allowing sending of messages from one port and listening out for them arriving at the other.</dd>
 <dt>{{domxref("PortCollection")}}</dt>
 <dd>An array of <code>MessagePort</code>s; an experimental solution to allow broadcasting of a message to multiple ports simultaneously.</dd>
</dl>

<h2 id="Examples">Examples</h2>

<ul>
 <li>We have published a <a href="https://github.com/mdn/dom-examples/tree/master/channel-messaging-basic">channel messaging basic demo</a> on Github (<a href="http://mdn.github.io/dom-examples/channel-messaging-basic/">run it live too</a>), which shows a really simple single message transfer between a page and an embedded {{htmlelement("iframe")}}.</li>
 <li>You can also see a <a href="https://github.com/mdn/dom-examples/tree/master/channel-messaging-multimessage">multimessaging demo</a> (<a href="http://mdn.github.io/dom-examples/channel-messaging-multimessage/">run this live</a>), which shows a slightly more complex setup that can send multiple messages between main page and IFrame.</li>
</ul>

<h2 id="Specifications">Specifications</h2>

<table class="standard-table">
 <tbody>
  <tr>
   <th scope="col">Specification</th>
   <th scope="col">Status</th>
   <th scope="col">Comment</th>
  </tr>
  <tr>
   <td>{{SpecName('HTML WHATWG', 'web-messaging.html#channel-messaging', 'Channel messaging')}}</td>
   <td>{{Spec2('HTML WHATWG')}}</td>
   <td> </td>
  </tr>
 </tbody>
</table>

<h2 id="Browser_compatibility">Browser compatibility</h2>

<div>
<h3 id="MessageChannel"><code>MessageChannel</code></h3>

<div>


<p>{{Compat("api.MessageChannel", 0)}}</p>

<h3 id="MessagePort"><code>MessagePort</code></h3>

<div>
<div class="hidden">The compatibility table on this page is generated from structured data. If you'd like to contribute to the data, please check out <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> and send us a pull request.</div>

<p>{{Compat("api.MessagePort", 0)}}</p>
</div>
</div>
</div>

<h2 id="See_also">See also</h2>

<ul>
 <li><a href="/en-US/docs/Web/API/Channel_Messaging_API/Using_channel_messaging">Using channel messaging</a></li>
 <li><a href="/en-US/docs/Web/API/Web_Workers_API">Web Workers API</a></li>
 <li><a href="/en-US/docs/Web/API/Broadcast_Channel_API">Broadcast Channel API</a></li>
</ul>