diff --git a/src-docs/SUMMARY.md b/src-docs/SUMMARY.md
index a945103..d165d8a 100644
--- a/src-docs/SUMMARY.md
+++ b/src-docs/SUMMARY.md
@@ -5,13 +5,14 @@
 - [Webxdc Specification](./spec/README.md)
   - [Container file format (`.xdc`)](./spec/format.md)
   - [Javascript API](./spec/api.md)
-      - [sendUpdate](./spec/sendUpdate.md)
-      - [setUpdateListener](./spec/setUpdateListener.md)
-      - [sendToChat](./spec/sendToChat.md)
-      - [importFiles](./spec/importFiles.md)
-      - [selfAddr & selfName](./spec/selfAddr_and_selfName.md)
+    - [sendUpdate](./spec/sendUpdate.md)
+    - [setUpdateListener](./spec/setUpdateListener.md)
+    - [sendEphemeral](./spec/sendEphemeral.md)
+    - [setEphemeralListener](./spec/setEphemeralListener.md)
+    - [sendToChat](./spec/sendToChat.md)
+    - [importFiles](./spec/importFiles.md)
+    - [selfAddr & selfName](./spec/selfAddr_and_selfName.md)
   - [Messenger implementations](./spec/messenger.md)
-
 - [Shared Web Application state](./shared_state/README.md)
   - [Detecting conflicts](./shared_state/conflicts.md)
   - [Theory of Conflict-free Replicated Data Types (CRDTs)](./shared_state/crdts.md)
diff --git a/src-docs/spec/sendEphemeral.md b/src-docs/spec/sendEphemeral.md
new file mode 100644
index 0000000..8200b8c
--- /dev/null
+++ b/src-docs/spec/sendEphemeral.md
@@ -0,0 +1,9 @@
+# sendEphemeral
+
+```js
+window.webxdc.sendEphemeral(payload);
+```
+
+Send an ephemeral message to all peers. [setEphemeralListener](./setEphemeralListener.md) has to be called first to create a connection to at least on peer. See the documentation for [setEphemeralListener](./setEphemeralListener.md) to find out more.
+
+- `payload` any javascript object that can be given to `JSON.stringify`
diff --git a/src-docs/spec/setEphemeralListener.md b/src-docs/spec/setEphemeralListener.md
new file mode 100644
index 0000000..c30144b
--- /dev/null
+++ b/src-docs/spec/setEphemeralListener.md
@@ -0,0 +1,31 @@
+# setEphemeralListener
+
+```js
+window.webxdc.setEphemeralListener((payload) => {});
+```
+
+`setEphemeralListener` can be used to set a callback that receives the _ephemeral_ messages
+sent by [`sendEphemeral`](./sendEphemeral.md). Ephemeral messages are messages that are delivered only to peers that are currently connected with a direct connection to the sender. These messages are not persisted and should thus only be used for unimportant synchronization like cursor positions and live game data. Members of a chat that are not currently connected will never receive these messages.
+The `setEphemeralListener` function returnes a promise that resolves as soon as at least one peer is online. The completion of the promise thus signales that the connection is usable for message delivery. Messages that are send with [`sendEphemeral`](./sendEphemeral.md) before this promise resolves are discarded and will never reach any peer.
+
+- `payload`: Any json object deserialized by `JSON.parse`.
+
+Calling `setEphemeralListener()` multiple times is undefined behavior: in current implementations the callback is simply replaced. 
+
+
+## Example
+```js
+// stub implementation until the channel is ready
+let sendGossip = () => { console.error("transport not ready") }
+
+window.webxdc.setEphemeralListener(function (message) {
+    console.log("Received ephemeral message: ", message);
+    /* Application code */
+}).then(() => {
+    // Replace `sendGossip` with proper implementation
+    sendGossip = () => {
+        console.log("New ephemeral message: ", msg);
+        window.webxdc.sendEphemeral(msg);
+    }
+});
+```
\ No newline at end of file