Add comments and outbound postmessage action to request a widget screenshot.

src/WidgetMessaging.js

@@ -52,8 +52,8 @@ They look like:
 }
 The "message" key should be a human-friendly string.
 
-ACTIONS
+INBOUND ACTIONS
-=======
+===============
 ** All actions must include an "api" field with valie "widget".**
 All actions can return an error response instead of the response outlined below.
 
@@ -109,6 +109,45 @@ Example:
     action: "supported_api_versions",
 }
 
+
+OUTBOUND ACTIONS
+================
+
+In addition to listening for inbound requests, the API can be used to initiate
+actionss in the widget iframe, and request data from the widget instance.
+
+Outbound actions use the "widget_client" API key / name, which must be included
+on all requests.
+
+{
+    api: "widget_client",
+    action: "screenshot",
+    widgetId: $WIDGET_ID,
+    data: {}
+    // additional request fields
+}
+
+
+screenshot
+----------
+
+Request a screenshot from the widget (if supported).
+This can only be supported by widgets that have access to all of their DOM tree.
+For example, widgets that nest further levels of iframes can not support this.
+
+Request:
+ - No additional fields.
+Response:
+{
+    screenshot: {data...}
+}
+Example:
+{
+    api: "widget_client",
+    action: "screenshot",
+    widgetId: $WIDGET_ID
+}
+
 */
 
 import URL from 'url';
@@ -323,6 +362,16 @@ export default class WidgetMessaging extends MatrixPostMessageApi {
         }
         event.source.postMessage(data, event.origin);
     }
+
+    /**
+     * Request a screenshot from a widget
+     */
+    getScreenshot() {
+        const screenshot = this.exec({
+            action: "screenshot",
+        });
+        console.warn("got screenshot", screenshot);
+    }
 }