Matrix/element-call-Github
1
0
Fork 0
mirror of https://github.com/vector-im/element-call.git synced 2024-11-24 00:38:31 +08:00
Code Issues Packages Projects Releases Wiki Activity
9ce16b68e9
element-call-Github/docs/url-params.md
Hugh Nimmo-Smith 9ce16b68e9
Refactor URL parameters into table (#2827) 
* Refactor URL parameters into table

This is for readability and ahead of some possible changes

* Whitespace

* Lint

* Cleanup and correct fontScale
2024-11-23 08:51:27 +00:00

17 KiB
Raw Blame History

Url Format and parameters

There are two formats for Element Call urls.

  • Current Format

    https://element_call.domain/room/#
/<room_name_alias>?roomId=!id:domain&password=1234&<other params see below>

    The url is split into two sections. The https://element_call.domain/room/# contains the app and the intend that the link brings you into a specific room (https://call.element.io/# would be the homepage). The fragment is used for query parameters to make sure they never get sent to the element_call.domain server. Here we have the actual matrix roomId and the password which are used to connect all participants with e2ee. This allows that <room_name_alias> does not need to be unique. Multiple meetings with the label weekly-sync can be created without collisions.

  • deprecated

    https://element_call.domain/<room_name>

    With this format the livekit alias that will be used is the <room_name>. All people connecting to this URL will end up in the same unencrypted room. This does not scale, is super unsecure (people could end up in the same room by accident) and it also is not really possible to support encryption.

Parameters

Name Values Required for widget Required for SPA Description
allowIceFallback true or false No, defaults to false No, defaults to false Allows use of fallback STUN servers for ICE if the user's homeserver doesn’t provide any.
analyticsID Posthog analytics ID No No Available only with user's consent for sharing telemetry in Element Web.
appPrompt true or false No, defaults to true No, defaults to true Prompts the user to launch the native mobile app upon entering a room, applicable only on Android and iOS, and must be enabled in config.
baseUrl Yes Not applicable The base URL of the homeserver to use for media lookups.
confineToRoom true or false No, defaults to false No, defaults to false Keeps the user confined to the current call/room.
deviceId Matrix device ID Yes Not applicable The Matrix device ID for the widget host.
displayName No No Display name used for auto-registration.
enableE2EE (deprecated) true or false No, defaults to true No, defaults to true Legacy flag to enable end-to-end encryption, not used in the livekit branch.
fontScale A decimal number such as 0.9 No No Factor by which to scale the interface's font size.
fonts No No Defines the font(s) used by the interface. Multiple font parameters can be specified: ?font=font-one&font=font-two....
hideHeader true or false No, defaults to false No, defaults to false Hides the room header when in a call.
hideScreensharing true or false No, defaults to false No, defaults to false Hides the screen-sharing button.
homeserver Not applicable No Homeserver for registering a new (guest) user, configures non-default guest user server when creating a spa link.
lang BCP 47 code No No The language the app should use.
parentUrl Yes Not applicable The url used to send widget action postMessages. This should be the domain of the client or the webview the widget is hosted in. (in case the widget is not in an Iframe but in a dedicated webview we send the postMessages same WebView the widget lives in. Filtering is done in the widget so it ignores the messages it receives from itself)
password No No E2EE password when using a shared secret. (For individual sender keys in embedded mode this is not required.)
perParticipantE2EE true or false No, defaults to false No, defaults to false Enables per participant encryption with Keys exchanged over encrypted matrix room messages.
preload true or false No, defaults to false Not applicable Pauses app before joining a call until an io.element.join widget action is seen, allowing preloading.
returnToLobby true or false No, defaults to false Not applicable Displays the lobby in widget mode after leaving a call; shows a blank page if set to false. Useful for video rooms.
roomId Matrix Room ID Yes No Anything about what room we're pointed to should be from useRoomIdentifier which parses the path and resolves alias with respect to the default server name, however roomId is an exception as we need the room ID in embedded widget mode, and not the room alias (or even the via params because we are not trying to join it). This is also not validated, where it is in useRoomIdentifier().
showControls true or false No, defaults to true No, defaults to true Displays controls like mute, screen-share, invite, and hangup buttons during a call.
skipLobby true or false No, defaults to false No, defaults to false Skips the lobby to join a call directly, can be combined with preload in widget.
theme One of: light, dark, light-high-contrast, dark-high-contrast No, defaults to dark No, defaults to dark UI theme to use.
userId Matrix User Identifier Yes Not applicable The Matrix user ID.
viaServers Comma separated list of Matrix Server Names Not applicable No Homeserver for joining a room, non-empty value required for rooms not on the user’s default homeserver.
widgetId MSC2774 format widget ID Yes Not applicable The id used by the widget. The presence of this parameter implies that element call will not connect to a homeserver directly and instead tries to establish postMessage communication via the parentUrl.