Important
This section covers the requirements for deploying a Matrix site compatible with MatrixRTC, the foundation of Element Call. These requirements apply to both Standalone as well as Widget mode operation of Element Call.
The following MSCs are required for Element Call to work properly:
-
MSC3266: Room Summary API: In Standalone mode Element Call is able to join rooms over federation using knocking. In this context MSC3266 is required as it allows to request a room summary of rooms you are not joined. The summary contains the room join rules. We need that information to decide if the user gets prompted with the option to knock ("Request to join call"), a "cannot join error" or "the join view".
-
MSC4140 Delayed Events: Delayed events are required for proper call participation signalling. If disabled it is very likely that you end up with stuck calls in Matrix rooms.
-
MSC4222 Adding
state_afterto sync v2: Allow clients to opt-in to a change of the sync v2 API that allows them to correctly track the state of the room. This is required by Element Call to track room state reliably.
If you're using Synapse as your
homeserver, you'll need to additionally add the following config items to
homeserver.yaml to comply with Element Call:
experimental_features:
# MSC3266: Room summary API. Used for knocking over federation
msc3266_enabled: true
# MSC4222 needed for syncv2 state_after. This allow clients to
# correctly track the state of the room.
msc4222_enabled: true
# The maximum allowed duration by which sent events can be delayed, as
# per MSC4140.
max_event_delay_duration: 24h
rc_message:
# This needs to match at least e2ee key sharing frequency plus a bit of headroom
# Note key sharing events are bursty
per_second: 0.5
burst_count: 30
# This needs to match at least the heart-beat frequency plus a bit of headroom
# Currently the heart-beat is every 5 seconds which translates into a rate of 0.2s
rc_delayed_event_mgmt:
per_second: 1
burst_count: 20In order to guarantee smooth operation of Element Call MatrixRTC backend is required for each site deployment.
As depicted above in the example.com site deployment, Element Call requires a
Livekit SFU alongside a
Matrix Livekit JWT auth service
to implement
MSC4195: MatrixRTC using LiveKit backend.
In the context of MatrixRTC, we suggest using a single hostname for backend communication by implementing endpoint routing within a reverse proxy setup. For the example above, this results in:
| Service | Endpoint | Example |
|---|---|---|
| Livekit SFU WebSocket signalling connection | /livekit/sfu |
matrix-rtc.example.com/livekit/sfu |
| Matrix Livekit JWT auth service | /livekit/jwt |
matrix-rtc.example.com/livekit/jwt |
Using Nginx, you can achieve this by:
Important
As defined in
MSC4143
MatrixRTC backend must be announced to the client via your Matrix site's
.well-known/matrix/client file (e.g.
example.com/.well-known/matrix/client matching the site deployment example
from above). The configuration is a list of Foci configs:
"org.matrix.msc4143.rtc_foci": [
{
"type": "livekit",
"livekit_service_url": "https://matrix-rtc.example.com/livekit/jwt"
},
{
"type": "livekit",
"livekit_service_url": "https://matrix-rtc-2.example.com/livekit/jwt"
},
{
"type": "nextgen_new_foci_type",
"props_for_nextgen_foci": "val"
}
]Note
Most org.matrix.msc4143.rtc_foci configurations will only have one entry in
the array
Note
This step is only required if you want to deploy Element Call in Standalone mode.
Until prebuilt tarballs are available, you'll need to build Element Call from source. First, clone and install the package:
git clone https://github.com/element-hq/element-call.git
cd element-call
corepack enable
yarn
yarn buildIf all went well, you can now find the build output under dist as a series of
static files. These can be hosted using any web server that can be configured
with custom routes (see below).
You also need to add a configuration file which goes in public/config.json -
you can use the sample as a starting point:
cp config/config.sample.json public/config.json
# edit public/config.jsonThe sample needs editing to contain the homeserver that you are using.
Because Element Call uses client-side routing, your server must be able to route
any requests to non-existing paths back to /index.html. For example, in Nginx
you can achieve this with the try_files directive:
server {
...
location / {
...
try_files $uri /$uri /index.html;
}
}There are currently two different config files. .env holds variables that are
used at build time, while public/config.json holds variables that are used at
runtime. Documentation and default values for public/config.json can be found
in ConfigOptions.ts.
Caution
Please note configuring MatrixRTC backend via config.json of
Element Call is only available for developing and debug purposes. Relying on
it might break Element Call going forward!
Element Call in Standalone mode requires a homeserver with registration enabled without any 3pid or token requirements, if you want it to be used by unregistered users. Furthermore, it is not recommended to use it with an existing homeserver where user accounts have joined normal rooms, as it may not be able to handle those yet and it may behave unreliably.
Therefore, to use a self-hosted homeserver, this is recommended to be a new server where any user account created has not joined any normal rooms anywhere in the Matrix federated network. The homeserver used can be setup to disable federation, so as to prevent spam registrations (if you keep registrations open) and to ensure Element Call continues to work in case any user decides to log in to their Element Call account using the standard Element app and joins normal rooms that Element Call cannot handle.
server { ... location ^~ /livekit/jwt/ { proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; # JWT Service running at port 8080 proxy_pass http://localhost:8080/; } location ^~ /livekit/sfu/ { proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_send_timeout 120; proxy_read_timeout 120; proxy_buffering off; proxy_set_header Accept-Encoding gzip; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; # LiveKit SFU websocket connection running at port 7880 proxy_pass http://localhost:7880/; } }