DOCSEARCHbyAlgolia
Submit Docs

matrix.to Documentation

repository·main·Indexed 21 days ago

https://github.com/matrix-org/matrix.to

A URL redirection service for the Matrix ecosystem that allows sharing links to rooms, users, and messages independently of specific clients. The service performs client-side redirection via JavaScript to preserve privacy. Documentation covers URL schemes for Matrix entities, optional redirection parameters, local build and development instructions using yarn, and API references for parsing Matrix URL fragments and identifiers via the Link class.

Tokens
3.1K
Snippets
5
Records
30
Agent score
80%

What's inside matrix.to

  1. Add a Matrix chat badge to your website

    main

    You can display a 'Chat on Matrix' badge on your website by using the provided SVG image and linking it to your Matrix room or user.

    Markdown implementation

    [![Chat on Matrix](https://matrix.to/img/matrix-badge.svg)](https://matrix.to/#/#matrix.to:matrix.org)

    HTML implementation

    <a href="https://matrix.to/#/#matrix.to:matrix.org" rel="noopener" target="_blank"><img src="https://matrix.to/img/matrix-badge.svg" alt="Chat on Matrix"></a>

    Note: Replace https://matrix.to/#/#matrix.to:matrix.org with your actual Matrix entity link.

    [![Chat on Matrix](https://matrix.to/img/matrix-badge.svg)](https://matrix.to/#/#matrix.to:matrix.org)

<a href="https://matrix.to/#/#matrix.to:matrix.org" rel="noopener" target="_blank"><img src="https://matrix.to/img/matrix-badge.svg" alt="Chat on Matrix"></a>

  2. Build and run Matrix.to locally

    main

    To host your own instance of Matrix.to, follow these steps using yarn:

    1. Install yarn.
    2. Clone the repository:
      git clone https://github.com/matrix-org/matrix.to
    3. Navigate to the directory:
      cd matrix.to
    4. Install dependencies:
      yarn
    5. Start the development server:
      yarn start
    6. Access the application at http://localhost:5000 in your browser.
    git clone https://github.com/matrix-org/matrix.to
cd matrix.to
yarn
yarn start

  8. URL Scheme for Matrix entities

    main

    Matrix.to uses a specific URL structure to redirect users to Matrix entities. The #/ component is mandatory to prevent the hosting server from seeing the target URL via the fragment.

    Entity typeExample URL
    Roomshttps://matrix.to/#/#matrix:matrix.org
    Rooms by IDhttps://matrix.to/#/!cURbafjkfsMDVwdRDQ:matrix.org
    Usershttps://matrix.to/#/@matthew:matrix.org
    Messageshttps://matrix.to/#/#matrix:matrix.org/$1448831580433WbpiJ:jki.re

    Important Notes:

    • Spaces: There is no specific entity type for Spaces; they are treated as rooms.
    • Room IDs: Linking via Room ID (!ID:server) should only be used for rooms where the target user has been invited, as these links may not work for all visitors.
    • Escaping: While # and @ characters in the fragment should technically be escaped, Matrix.to allows them verbatim for legibility.
    https://matrix.to/#/#matrix:matrix.org
https://matrix.to/#/!cURbafjkfsMDVwdRDQ:matrix.org
https://matrix.to/#/@matthew:matrix.org
https://matrix.to/#/#matrix:matrix.org/$1448831580433WbpiJ:jki.re

  9. Optional parameters for Matrix.to URLs

    main

    You can append optional parameters to the Matrix.to URL to customize the redirection behavior. These are appended to the URL fragment.

    • client: Specifies a preferred client (e.g., client=im.fluffychat, client=element.io).
    • web-instance[]: Maps a client to a specific web instance (e.g., web-instance[element.io]=chat.mozilla.org). The service uses a list of trustedWebInstances for this.
    • via: Specifies a source/origin (e.g., via=mozilla.org).

    Example URL with parameters: https://matrix.to/#/#matrix:matrix.org?web-instance[element.io]=chat.mozilla.org

  10. Guess applicable platforms from user agent

    main

    The guessApplicablePlatforms function analyzes a userAgent string and the current platform (from navigator.platform) to return an array containing both the detected native platform and the corresponding web platform.

    Parameters:

    • userAgent (string): The browser's user agent string.
    • platform (string): The value of navigator.platform.

    Returns: An array of two Platform enum values: [nativePlatform, webPlatform].

    Mapping Logic:

    • Android: [Platform.Android, Platform.MobileWeb]
    • iOS (iPhone/iPad/iPod): [Platform.iOS, Platform.MobileWeb]
    • Linux: [Platform.Linux, Platform.DesktopWeb]
    • macOS: [Platform.macOS, Platform.DesktopWeb]
    • Other (Windows): [Platform.Windows, Platform.DesktopWeb]

  11. Generate installation URLs for various platforms

    main

    The src/open/types.js module provides classes to generate standardized installation URLs for different app distribution platforms. Each class implements createInstallURL(link), channelId, and getDescription() methods.

    Supported Platform Link Classes

    ClassChannel IDDescription PatternURL Format
    AppleStoreLinkapple-app-store"Download on the App Store"https://apps.apple.com/app/{org}/{appId}
    PlayStoreLinkplay-store"Get it on Google Play"https://play.google.com/store/apps/details?id={appId}&referrer={link.identifier}
    FDroidLinkfdroid"Get it on F-Droid"https://f-droid.org/packages/{appId}
    FlathubLinkflathub"Get it on Flathub"https://flathub.org/apps/details/{appId}
    WebsiteLinkwebsite"Download for {platform}"{url}

  12. Fix broken Matrix URL fragments with tryFixUrl()

    main
    If you have a fragment that might be missing the required #/ prefix or has incorrect routing, tryFixUrl(fragment) attempts to generate several valid variations by prepending common prefixes (#/@, /#/, /#/!) and checking if they result in valid Link objects. It returns an array of objects containing the attempted url and the resulting link object.