Pour attribuer une adresse à une salle Matrix, par exemple `example.com/room` #support:example.com, créez un alias local sur le serveur d'accueil dont le nom de serveur configuré est `example.com/room` example.com, puis sélectionnez cet alias comme adresse principale de la salle dans Element. Il n'est pas nécessaire de créer un enregistrement DNS distinct pour chaque alias de salle, mais vous ne pouvez pas modifier le domaine d'un alias de serveur d'accueil existant simplement en configurant le DNS.
Comprendre ce que contrôle le domaine personnalisé
Un alias de salle est une adresse lisible qui correspond à l'identifiant permanent d'une salle Matrix , un identifiant commençant généralement par ` matrix.room` !. Une salle peut avoir plusieurs alias, par exemple ` #support:example.commatrix.room #help:example.com...
Matrix définit les alias sous la forme `<nom_du_domaine>` #localpart:server-name. Pour Synapse, ce server_nameparamètre détermine le domaine utilisé pour les adresses des salles créées localement. Synapse indique que ce paramètre ne peut pas être modifié après la configuration initiale. Si votre serveur existant s'appelle `<nom_du_serveur>` matrix.example.com, Element ne transformera pas ses alias locaux en `<nom_du_domaine>` #support:example.comsimplement parce que vous possédez `<nom_du_domaine>` example.com. Consultez la spécification des identifiants Matrix et le manuel de configuration de Synapse .
Vérifiez les prérequis
- Un serveur Matrix fonctionnel : cet exemple suppose que Synapse traite déjà les requêtes API client à l’adresse indiquée,
https://matrix.example.comtandis que sa configuration server_nameest définie sur example.com. L’URL du client et le nom du serveur peuvent différer.
- Salle existante : Créez d’abord la salle si nécessaire. Choisissez un alias local court et facile à retenir, par exemple : `localpart`
support. Un alias doit être unique sur le serveur qui le crée.
- Autorisation de gestion des adresses : Connectez-vous avec un compte autorisé à créer l’alias local et à modifier l’adresse principale de la salle. La politique de création d’alias du serveur et les niveaux de puissance de la salle peuvent restreindre ces actions.
- Une méthode de test : conservez un deuxième compte Matrix disponible, idéalement sur un autre serveur domestique, afin de pouvoir vérifier la découverte indépendamment de votre session d’administrateur.
Créez l'alias dans Element Web
Le chemin suivant correspond à la terminologie des paramètres de salle de la documentation des paramètres de salle d'Element vérifiée en octobre 2026. Les positions des menus peuvent différer selon les versions d'Element et les autres clients Matrix.
1. Ouvrez les paramètres de la pièce
Dans Element Web ou Element Desktop, ouvrez la salle de destination. Sélectionnez « Paramètres de la salle » dans le panneau d'informations de la salle, ou utilisez le menu à trois points de la salle et choisissez « Paramètres » . Si vous avez besoin de l'identifiant interne de la salle pour le dépannage ultérieur, consultez la section « Avancé » et copiez-le sans modifier aucun caractère.
2. Ajouter une adresse locale
Sur la page des paramètres généraux , repérez Adresses des salles , puis Adresses locales . Saisissez l'alias localpart, par exemple support`localpart`, dans le champ Adresse de la salle et sélectionnez Ajouter ou l'option équivalente Enregistrer. Vérifiez que l'adresse complète obtenue est bien `localpart` #support:example.com. Si elle se termine par `localpart` :matrix.example.com, arrêtez-vous : il s'agit d'un problème lié au nom du serveur d'accueil, et non d'une faute de frappe que les paramètres de la salle peuvent corriger.
3. Choisissez l'adresse principale
Toujours dans la section « Adresses des salles » , recherchez « Adresses publiées » et définissez l' adresse principale#support:example.com . La documentation d'Element indique que la première adresse locale créée est généralement sélectionnée automatiquement comme adresse principale. La sélectionner explicitement est utile si la salle possède déjà plusieurs alias.
L'adresse principale est l' alias canonique de la salle : l'adresse privilégiée affichée dans l'état de la salle. Créer un alias et choisir l'alias canonique sont deux actions liées mais distinctes. Matrix prend également en charge d'autres alias. Un alias canonique doit déjà correspondre à la salle concernée avant d'être affiché.
4. Déterminer si la salle doit figurer dans un annuaire
N'activez l'option « Publier cette salle dans l'annuaire public » que si vous souhaitez qu'elle soit visible par tous. Définir une adresse ne rend pas automatiquement une salle publique, et la publication d'une salle est indépendante de ses règles d'accès. Une salle privée ou sur invitation peut avoir un alias facile à retenir sans pour autant autoriser tout le monde à la rejoindre. Pour les salles communautaires publiques, vérifiez à la fois les paramètres d'annuaire et les règles d'accès de la salle avant de diffuser largement son adresse.
Utilisez l'API Matrix si le client ne peut pas ajouter l'adresse.
Les administrateurs et les outils d'automatisation peuvent utiliser l' API client-serveur standard de Matrix . L'exemple ci-dessous crée le même alias ; ne l'exécutez pas#support:example.com si Element a déjà été créé . Remplacez l'identifiant de la salle par l'identifiant réel et un jeton d'accès valide pour un utilisateur autorisé par la politique d'alias du serveur d'accueil. Considérez ce jeton comme un mot de passe.
curl --request PUT \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--data '{"room_id":"!yourRoomId:example.com"}' \
'https://matrix.example.com/_matrix/client/v3/directory/room/%23support%3Aexample.com'
Une requête réussie renvoie une réponse HTTP 200avec un objet JSON vide. Les %23parties ` %3A<alias>` #et `<nom_de_la_salle>` correspondent à l'encodage URL :. La requête PUT crée une association entre un alias et une salle ; elle ne modifie pas nécessairement l'alias canonique de la salle. Après une création effectuée uniquement via l'API, retournez dans le contrôle « Adresse principale » d'Element si vous souhaitez que cet alias soit affiché comme alias principal. Ne collez pas de jeton d'authentification réel dans une commande shell partagée, une capture d'écran ou un ticket d'assistance.
Vérifiez que le mappage est résolu.
La recherche dans l'annuaire ne nécessite pas d'authentification. Remplacez l'hôte de l'URL par votre propre point de terminaison d'API client accessible :
curl --fail-with-body --silent --show-error \
'https://matrix.example.com/_matrix/client/v3/directory/room/%23support%3Aexample.com'
La réponse doit contenir une adresse IP room_idcorrespondant à la salle de destination et un serverstableau. Ce test vérifie la résolution des alias, et non la possibilité pour chaque serveur distant de se fédérer avec le vôtre.
Résoudre les problèmes courants
L'alias a un domaine incorrect
Vérifiez la configuration de Synapse server_name. Ne modifiez pas cette valeur sur un serveur existant pour tenter de renommer ses alias : son identité et ses identifiants Matrix existants en dépendent. Pour un nouveau déploiement, définissez le nom de serveur souhaité avant de créer des utilisateurs et des salons. Si vous utilisez déjà un autre nom, il est préférable d'utiliser son domaine d'alias réel, sauf si vous pouvez configurer un serveur principal portant un nom approprié pour gérer les nouveaux alias.
La création échoue avec une erreur 403 ou 409
L'erreur HTTP 403indique généralement un refus d'accès ou une politique serveur applicable. Vérifiez les privilèges de la salle de l'utilisateur et les alias_creation_rulesrègles de Synapse ; celles-ci sont évaluées séquentiellement et une liste vide empêche toute création d'alias. L'erreur HTTP 409signifie que l'alias existe déjà. Choisissez une autre partie locale ou examinez le mappage existant au lieu de le remplacer sans précaution. Le manuel de configuration de Synapse décrit les options de politique d'alias.
Les joueurs sur d'autres serveurs ne peuvent pas trouver la salle.
Vérifiez d'abord que l'alias est résolu localement. Si la résolution locale réussit mais que la découverte externe échoue, examinez la fédération pour le domaine de l'alias , notamment les certificats HTTPS, la /.well-known/matrix/serverdélégation correspondante et l'écouteur de fédération exposé. Un nom d'hôte utilisé pour le trafic client n'établit pas automatiquement la fédération pour un autre nom de serveur Matrix. L' API Serveur-Serveur de Matrix décrit la découverte et la délégation des serveurs. Vérifiez également que les utilisateurs distants sont autorisés à rejoindre la salle ; une salle sur invitation uniquement peut être résolue avec succès tout en refusant l'accès à une nouvelle session.
Vérifiez l'adresse de la chambre personnalisée
- Vérifiez que cette
#support:example.comadresse apparaît bien sous « Adresses locales » et comme adresse principale prévue dans l'élément.
- Exécutez la requête GET de répertoire non authentifiée ci-dessus et comparez-la avec l'ID affiché dans les paramètres avancés
room_id de la salle Element .
- Depuis un autre compte, essayez d'ouvrir le lien
https://matrix.to/#/%23support%3Aexample.com. Celui-ci devrait vous mener à la salle attendue ; la possibilité pour votre compte de rejoindre la salle dépendra toutefois des règles d'accès de celle-ci.
La documentation de Matrix concernant l'alias de salle et le format matrix.to définit le format du lien de partage encodé. Si les trois vérifications sont réussies, la nouvelle adresse est prête à être partagée tandis que l'identifiant de salle d'origine reste inchangé.