How to Configure Custom Matrix Room Aliases on Your Domain

A Matrix room alias gives a room a human-readable address such as #support:example.org. The part after the colon is the homeserver’s server name, the domain that owns the alias namespace. It is not an arbitrary domain label that can be changed by adding a DNS record. To use your own domain, your homeserver must be configured with that domain as its server name; federation can then be delegated to a separate host.

This guide uses example.org as the domain, matrix.example.org as the Synapse host, and #support:example.org as the target alias. Replace these placeholders with your own values. It focuses on self-hosted Synapse. If you use a hosted Matrix provider, check whether it lets you use a custom server name; many hosted accounts can create aliases only under the provider’s domain.

What a Matrix room alias does

A homeserver is the Matrix server that stores users’ room data and connects to other servers. A room ID, such as !opaqueid:example.org, identifies a room technically. A room alias, such as #support:example.org, is a readable directory entry that resolves to a room ID and a list of servers that can help a user join.

An alias does not rename the room, change its privacy, or guarantee that it appears in a public room directory. Those are separate room settings. The room may have multiple aliases. A canonical alias is the preferred address shown or shared by clients; it is published as room state, while the homeserver maintains the alias-to-room mapping. The Matrix specification cautions that alias mappings can change, so resolve an address before relying on it.

Before you begin

• Control the domain you want to use, such as example.org, including the ability to serve HTTPS content at that domain.
• Run a homeserver such as Synapse with its Matrix server_name set to example.org. This value is chosen when the server is set up and should not be casually changed later: user IDs and aliases use it as their namespace.
• Have a working TLS certificate and federation route. The delegated Matrix host, such as matrix.example.org, must present a valid certificate.
• Be joined to the room and have the room permission required to change its addresses. Synapse also has server-side rules that can allow or deny alias creation.

If the server is already running with a different server name, for example provider.net, creating #support:example.org is not a domain-mapping shortcut. Ask the provider about custom-domain support or plan a separate homeserver deployment and migration. Matrix does not define a process for one homeserver to create aliases in another server’s namespace.

Step 1: Choose the server name and federation route

Decide which name will appear after the colon before setting up the homeserver. In this example, Synapse uses example.org as its server name, while its client and federation services run at matrix.example.org. A DNS record sends traffic for matrix.example.org to the host or reverse proxy. The DNS record by itself does not establish the alias namespace; Synapse’s server name does.

When the homeserver is not directly reachable at example.org on the default federation port 8448, Matrix needs a way to discover its federation endpoint. One common method is .well-known delegation: a small HTTPS JSON response at the server-name domain points federation traffic to the actual Matrix host. Serve this at https://example.org/.well-known/matrix/server:

{
  "m.server": "matrix.example.org:443"
}

Make sure the response is valid JSON, served over HTTPS, and that the target host has a valid certificate and routes federation requests to Synapse. The port can be omitted when the federation endpoint uses 8448; in this example, port 443 is explicit. If Synapse already serves federation on the server-name domain at port 8448, delegation may not be needed. The client-facing /.well-known/matrix/client file is a different discovery mechanism and is not a substitute for server delegation.

Synapse’s current configuration documentation includes the serve_server_wellknown option for cases where requests to the server-name domain on port 443 are routed to Synapse. Use that option only if your proxy and domain routing match its documented requirements. Otherwise, configure the JSON response at your web server or proxy.

Step 2: Check Synapse’s alias policies

Synapse can restrict who may create aliases and which room addresses are permitted. In homeserver.yaml, inspect alias_creation_rules if an alias creation request is denied. Synapse evaluates configured rules in order; the first matching rule decides the request, and if no rule matches, the request is denied. An empty list denies all alias creation requests. A null or omitted list permits alias creation by default, subject to other checks.

Also check require_membership_for_aliases, which defaults to requiring the user to be in the room. If you change Synapse configuration, follow your deployment’s normal validation and restart process, and avoid loosening policy more broadly than needed. A room’s power levels and the client’s available controls can also affect whether a regular member can set the preferred alias.

Step 3: Create an alias for the room

Join the intended room in a Matrix client and open its room settings. Look for an address or alias section; client wording and layout can vary by version. Enter the full address, including the leading # and the homeserver domain, for example #support:example.org. Add it as a room address and, if the client offers the option, set it as the canonical or preferred alias. Save the change.

If your client does not provide an alias control, a client-server API request can create the mapping. The authenticated PUT /_matrix/client/v3/directory/room/{roomAlias} endpoint requires a room ID in the request body. For example, an authorized room member or server account can send a request to the homeserver that owns example.org:

curl -X PUT \
  "https://matrix.example.org/_matrix/client/v3/directory/room/%23support%3Aexample.org" \
  -H "Authorization: Bearer $MATRIX_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"room_id":"!yourRoomId:example.org"}'

Replace the sample room ID with the exact ID of the room, and use a valid access token with the necessary authorization. Treat the token like a password: do not publish it, paste it into a support post, or commit it to source control. The percent escapes in the URL encode # and : for the HTTP path. A successful response indicates that the mapping was created. An “already exists” response means the name is occupied; confirm who owns it before changing or removing anything.

Step 4: Verify the address and share it

Resolve the alias using the public client-server API. This lookup does not require authentication:

curl -i \
  "https://matrix.example.org/_matrix/client/v3/directory/room/%23support%3Aexample.org"

A successful response should contain the expected room_id and a servers list. Compare the returned room ID with the intended room. A 404 means the alias has no mapping on the server that handles that namespace. A 400 points to an invalidly formatted address. Then test the full alias in a second Matrix account or client to confirm the room resolves and can be joined according to its join rules.

If you set a canonical alias, check the room details again and confirm that the preferred address is the one you intend to publish. Share the alias or a Matrix permalink only after confirming it resolves to the correct room. Remember that a public alias does not make a private room public; a user still needs permission to join.

Common problems to avoid

• Using a domain the homeserver does not own: The server name in an alias must match the homeserver namespace that creates it. A DNS CNAME alone cannot authorize another server’s domain.
• Mixing up the domain and the host: example.org can be the alias namespace while matrix.example.org is the service host. Set the Synapse server name and delegation deliberately.
• Putting the client discovery file in the wrong place: Federation delegation uses /.well-known/matrix/server. The client discovery file has a different path and purpose.
• Assuming an alias publishes a room publicly: Alias resolution and public room-directory publication are separate operations governed by separate policies.
• Changing the server name on an established deployment: Existing Matrix IDs depend on that namespace. Treat a domain change as an architectural migration, not a quick alias setting.
• Sharing without checking the mapping: Resolve the alias and compare the returned room ID before you publish it. A readable address is convenient, but the server’s mapping is what determines where it leads.

For the protocol details, see the Matrix identifier and alias format and the Matrix room-alias API. For Synapse setup, consult Element’s federation delegation guide and configuration manual. Synapse options and client screens can change between releases; check the documentation for the version you operate.