Add some docs about Jitsi widgets and Jitsi configuration

docs/config.md

@@ -84,7 +84,8 @@ For a good example, see https://riot.im/develop/config.json.
    By default, this is "https://matrix.to" to generate matrix.to (spec) permalinks.
    Set this to your Riot instance URL if you run an unfederated server (eg:
    "https://riot.example.org").
-1. `jitsi`: Used to change the default conference options.
+1. `jitsi`: Used to change the default conference options. Learn more about the
+   Jitsi options at [jitsi.md](./jitsi.md).
     1. `preferredDomain`: The domain name of the preferred Jitsi instance. Defaults
        to `jitsi.riot.im`. This is used whenever a user clicks on the voice/video
        call buttons - integration managers may use a different domain.

docs/jitsi-dev.md

@@ -0,0 +1,90 @@
+# Jitsi wrapper developer docs
+
+*If you're looking for information on how to set up Jitsi in your Riot, see 
+[jitsi.md](./jitsi.md) instead.*
+
+These docs are for developers wondering how the different conference buttons work
+within Riot. If you're not a developer, you're probably looking for [jitsi.md](./jitsi.md).
+
+## Brief introduction to widgets
+
+Widgets are embedded web applications in a room, controlled through state events, and
+have a `url` property. They are largely specified by [MSC1236](https://github.com/matrix-org/matrix-doc/issues/1236)
+and have extensions proposed under [MSC1286](https://github.com/matrix-org/matrix-doc/issues/1286).
+
+The `url` is typically something we shove into an iframe with sandboxing (see `AppTile`
+in the react-sdk), though for some widgets special integration can be done. v2 widgets
+have a `data` object which helps achieve that special integration, though v1 widgets
+are best iframed and left alone.
+
+Widgets have a `postMessage` API they can use to interact with Riot, which also allows
+Riot to interact with them. Typically this is most used by the sticker picker (an
+account-level widget), though widgets like the Jitsi widget will request permissions to
+get 'stuck' into the room list during a conference.
+
+Widgets can be added with the `/addwidget <url>` command.
+
+## Brief introduction to integration managers
+
+Integration managers (like Scalar and Dimension) are accessible via the 4 squares in
+the top right of the room and provide a simple UI over top of bridges, bots, and other
+stuff to plug into a room. They are a separate service to Riot and are thus iframed
+in a dialog as well. They also have a `postMessage` API they can use to interact with
+the client to create things like widgets, give permissions to bridges, and generally
+set everything up for the integration the user is working with.
+
+Integration managers do not currently have a spec associated with them, though efforts
+are underway in [MSC1286](https://github.com/matrix-org/matrix-doc/issues/1286).
+
+## Widgets configured by integration managers
+
+Integration managers will often "wrap" a widget by using a widget `url` which points
+to the integration manager instead of to where the user requested the widget be. For
+example, a custom widget added in an integration manager for https://matrix.org will
+end up creating a widget with a URL like `https://integrations.example.org?widgetUrl=https%3A%2F%2Fmatrix.org`.
+
+The integration manager's wrapper will typically have another iframe to isolate the
+widget from the client by yet another layer. The wrapper often provides other functionality
+which might not be available on the embedded site, such as a fullscreen button or the
+communication layer with the client (all widgets *should* be talking to the client
+over `postMessage`, even if they aren't going to be using the widget APIs).
+
+Widgets added with the `/addwidget` command will *not* be wrapped as they are not going
+through an integration manager.
+
+## Jitsi widgets from integration managers
+
+Integration managers will create an entire widget event and send it over `postMessage`
+for the client to add to the room. This means that the integration manager gets to 
+decide the conference domain, conference name, and other aspects of the widget. As
+a result, users can end up with a Jitsi widget that does not use the same conference
+server they specified in their config.json - this is expected.
+
+Some integration managers allow the user to change the conference name while others
+will generate one for the user. 
+
+## Jitsi widgets generated by Riot itself
+
+When the user clicks on the call buttons by the composer, the integration manager is
+not involved in the slightest. Instead, Riot itself generates a widget event, this time
+using the config.json parameters, and publishes that to the room. 
+
+The Jitsi widget created by Riot uses a local `jitsi.html` wrapper (or one hosted by
+`https://riot.im/app` for desktop users or those on non-https domains) as the widget
+`url`. The wrapper has some basic functionality for talking to Riot to ensure the
+required `postMessage` calls are fulfilled.
+
+## The Jitsi wrapper in Riot
+
+Whenever Riot sees a Jitsi widget, it ditches the `url` and instead replaces it with
+its local wrapper, much like what it would do when creating a widget. However, instead
+of using one from riot.im/app, it will use one local to the client instead.
+
+The wrapper is used to provide a consistent experience to users, as well as being faster
+and less risky to load. The local wrapper URL is populated with the conference information
+from the original widget (which could be a v1 or v2 widget) so the user joins the right
+call.
+
+Critically, when the widget URL is reconstructed it does *not* take into account the
+config.json's `preferredDomain` for Jitsi. If it did this, users would end up on different
+conference servers and therefore different calls entirely. 

docs/jitsi.md

@@ -0,0 +1,47 @@
+# Jitsi in Riot
+
+Riot uses [Jitsi](https://jitsi.org/) for conference calls, which provides options for
+self-hosting your own server and supports most major platforms.
+
+1:1 calls, or calls between you and one other person, do not use Jitsi. Instead, those
+calls work through a TURN server configured on your respective homeservers.
+
+There's a number of ways to start a Jitsi call: the easiest way is to click on the 
+voice or video buttons near the message composer in a room with more than 2 people. This
+will add a Jitsi widget which allows anyone in the room to join.
+
+Integration managers (available through the 4 squares in the top right of the room) may
+provide their own approaches for adding Jitsi widgets, though these are now considered
+legacy and should only be used in specific circumstances.
+
+## Configuring Riot to use your self-hosted Jitsi server
+
+Riot will use the Jitsi server that is embedded in the widget, even if it is not the
+one you configured. This is because conference calls must be held on a single Jitsi
+server and cannot be split over multiple servers.
+
+However, you can configure Riot to *start* a conference with your Jitsi server by adding
+to your [config](./config.md) the following:
+```json
+{
+  "jitsi": {
+    "preferredDomain": "your.jitsi.example.org"
+  }
+}
+```
+
+The default is `jitsi.riot.im` (a free service offered by Riot), and the demo site for
+Jitsi uses `meet.jit.si` (also free).
+
+Once you've applied the config change, refresh Riot and press the call button. This
+should start a new conference on your Jitsi server. 
+
+**Note**: The widget URL will point to a `jitsi.html` page hosted by Riot. The Jitsi
+domain will appear later in the URL as a configuration parameter.
+
+## Mobile app support
+
+Currently the Riot mobile apps do not support custom Jitsi servers and will instead
+use the default `jitsi.riot.im` server. When users on the mobile apps join the call,
+they will be joining a different conference which has the same name, but not the same
+participants.