Element Call Integration#

Overview#

Element Call is an MSC3401-based group call backend embedded as a widget in Element Web. The core implementation lives in the ElementCall class, which extends the abstract Call class in src/models/Call.ts. Element Web supports two call backends: JitsiCall for legacy video rooms 1 and ElementCall for MSC3401-based calls 2. Call.get(room) selects the right backend — ElementCall first, then JitsiCall 3.

ElementCall is enabled by the feature_group_calls setting, or by both feature_video_rooms + feature_element_call_video_rooms when the room is a call room 4. Rather than requiring a room state event, Element Call runs as a virtual widget created by createOrGetCallWidget() and added to WidgetStore in memory only. The widget is rendered as a sandboxed iframe by AppTile and communicates with Element Web over a postMessage channel via ClientWidgetApi.

Widget URL Parameters#

ElementCall.generateWidgetUrl() constructs the Element Call iframe URL. The base URL is SdkConfig.get("element_call").url + /room; parameters are passed as a URL hash fragment (#?params) using $variable template syntax so they can be overridden at runtime via widget data 5.

Lobby / behavior parameters (the most commonly modified):

Client context (always present): userId, deviceId, roomId, baseUrl, lang, fontScale, theme, analyticsID 12.

Conditional parameters appended based on settings:

• allowIceFallback=true if fallbackICEServerAllowed is enabled 13
• allowVoipWithNoMedia=true if feature_allow_screen_share_only_mode is enabled — enables screen-share-only calls 14
• font (repeated) if useSystemFont is set 15

skipLobby and returnToLobby#

These two parameters govern the pre-join and post-call lobby experience. Only ElementCall supports them; JitsiCall and legacy calls do not.

skipLobby — when true, Element Call skips its own pre-join lobby and connects the user directly 6. Scenarios:

• Shift+click the call button: user explicitly requests direct join → skipLobby=true
• Video rooms: always set to false (lobby always shown) 16
• Default: passed as undefined (not false) so Element Call applies its own defaults 17

On the Element Web side, when skipLobby is false/unset, performConnection() sets connectionState = ConnectionState.Lobby and waits indefinitely for a MatrixRTC membership change 18. When true, that wait is bypassed.

returnToLobby — when true, Element Call shows the lobby again after the call ends rather than a blank screen 7. Automatically true for video rooms via isVideoRoom() 16.

Parameter flow: placeCall() dispatches a ViewRoomPayload with skipLobby → RoomViewStore → CallView updates call.widget.data.skipLobby 19. PR #30848 refactored this to regenerate the widget URL just before start(), and changed the default from false to undefined to defer lobby decisions to Element Call.

Default Media Device States#

Before widget messaging begins, Call.start() reads MediaDeviceHandler to select which devices to pass:

• Microphone: MediaDeviceHandler.startWithAudioMuted reads the audioInputMuted setting. Default: false (mic starts on).
• Camera: MediaDeviceHandler.startWithVideoMuted reads the videoInputMuted setting. Default: false (camera starts on).
• Both settings are stored at the DEVICE level (local browser storage, not server-synced) 20.

Call.start() selects the saved device ID or falls back to the first available device and passes audioInput/videoInput (MediaDeviceInfo | null) to performConnection(). For Element Call, these are forwarded via the JoinCall widget action only when the deprecated preload=true is set 21; otherwise Element Call manages device selection internally.

Screen sharing: no mute default. Enabled by setting feature_allow_screen_share_only_mode, which appends allowVoipWithNoMedia=true to the widget URL 14, allowing screen-share-only participation without audio/video.

Connection States and Lobby Flow#

The ConnectionState enum 22 tracks the call lifecycle. The Lobby, WidgetLoading, and Disconnected states all represent a disconnected user but carry different context:

ElementCall.performConnection() drives the join flow:

1. If widget.data.preload (deprecated), sends JoinCall with device labels immediately 23.
2. If skipLobby is not true, sets state to ConnectionState.Lobby 18; user sees EC's own pre-join lobby.
3. Waits (no timeout) for the user's MatrixRTC membership to appear via MembershipsChanged or SessionStarted 24.
4. Calls sendCallNotify() to emit m.call.notify for other participants 25.
5. Base Call.start() sets state to Connected 26.

Widget messaging actions registered during connection 27: HangupCall, TileLayout, SpotlightLayout, DeviceMute.

Video room persistence: on hangup, onHangup immediately calls start() again to re-show the lobby — both ElementCall 28 and JitsiCall 29 implement this.

Widget Iframe and Messaging Infrastructure#

For the full iframe lifecycle, see the Widget Iframe Management KB article. Element Call-specific notes:

• Virtual widget: no room state event. createOrGetCallWidget() calls WidgetStore.addVirtualWidget() with a random 24-char ID. If a CALL-type widget already exists, it is reused and its data updated 30.
• iframe sandbox: allow-forms allow-popups allow-popups-to-escape-sandbox allow-same-origin allow-scripts allow-presentation allow-downloads 31
• iframe feature policy: microphone; camera; encrypted-media; autoplay; display-capture; clipboard-write; clipboard-read 32
• E2EE: perParticipantE2EE is auto-set to true for encrypted rooms unless feature_disable_call_per_sender_encryption is enabled 33.
• Destruction: ElementCall.destroy() calls ActiveWidgetStore.destroyPersistentWidget() (tears down ClientWidgetApi) and WidgetStore.removeVirtualWidget().