Notifications Matrix

Aperçu

• Source: https://matrix.org/
• Prise en charge des images: Oui
• Prise en charge des pièces jointes: Oui
• Limites de caractères des messages:
  • Corps non chiffré: 65000
  • Corps E2EE: 40000
• Format(s) de message pris en charge:
  • ✓TEXT
  • HTML
  • MARKDOWN
• Créer votre URL Apprise

Configuration du Compte

Par défaut, Apprise communique directement avec votre serveur Matrix via l’API Client officielle.

Vous pouvez aussi utiliser le mode webhook à la place de l’API Client Matrix. Ce mode est activé en précisant ?mode=matrix, ?mode=slack ou ?mode=hookshot, selon le service webhook que vous avez configuré.

Mise en Forme et Taille des Messages

Matrix accepte le texte brut, le HTML et le Markdown. Les messages HTML et Markdown incluent une version texte pour les clients qui ne peuvent pas afficher le contenu mis en forme. Avec ?mode=slack, le Markdown est envoyé inchangé et le HTML est converti en texte brut, car ce webhook affiche son texte tel quel.

Matrix limite l’événement complet à 65 536 octets, y compris les métadonnées ajoutées par le homeserver. Les limites ci-dessus sont des valeurs de repli prudentes pour le corps du message, et non des tailles d’événement fixes. Pour les envois directs, Apprise calcule chaque fragment selon son titre, son format, l’expansion UTF-8 et JSON ainsi que le surcoût E2EE éventuel ; le nombre réel de caractères peut donc être inférieur.

Si vous ne déclarez aucun format d’entrée, Apprise ne devine ni ne répare le balisage. Un réglage explicite ?format=html envoie le corps tel quel dans le message mis en forme, tandis que ?format=markdown interprète le corps comme du Markdown pour produire le message mis en forme. La version texte conserve alors votre texte d’origine. Les titres sont toujours traités comme du texte brut : des caractères comme < et & s’affichent donc exactement tels que vous les avez saisis. Avec overflow=split, le découpage d’un contenu inconnu ou structuré reste une solution au mieux ; consultez Pass-Through et Dépassement.

Syntaxe

La syntaxe valide est la suivante :

Avec un nom d’utilisateur et un mot de passe :

• matrix://{user}:{password}@{hostname}/#{room_alias}
• matrixs://{user}:{password}@{hostname}/!{room_id}

Avec un jeton d’accès pré-généré, sans nom d’utilisateur ni mot de passe :

• matrix://{token}@{hostname}/#{room_alias}
• matrixs://{token}@{hostname}/!{room_id}

Vous pouvez aussi fournir le jeton en paramètre de requête :

• matrixs://{hostname}/#{room_alias}?token={token}

Cibles de type Alias de Salon

Les alias de salon sont préfixés par #. Vous pouvez en préciser plusieurs en les séparant par des barres obliques :

• matrixs://{user}:{password}@{hostname}/#{room_alias}
• matrixs://{user}:{password}@{hostname}/#{room_alias1}/#{room_alias2}
• matrixs://{token}@{hostname}/#{room_alias1}/#{room_alias2}

Cibles de type Identifiant de Salon

Les identifiants de salon sont préfixés par !. Vous pouvez en préciser plusieurs de la même manière :

• matrixs://{user}:{password}@{hostname}/!{room_id}
• matrixs://{user}:{password}@{hostname}/!{room_id1}/!{room_id2}
• matrixs://{token}@{hostname}/!{room_id1}/!{room_id2}

Cibles de type Message Direct

Pour envoyer un message direct (DM) à un utilisateur Matrix, préfixez la cible avec @. Vous pouvez aussi inclure explicitement le homeserver dans la cible :

• matrixs://{user}:{password}@{hostname}/@{target_user}
• matrixs://{user}:{password}@{hostname}/@{target_user}:{homeserver}
• matrixs://{token}@{hostname}/@{target_user}
• matrixs://{token}@{hostname}/@{target_user}:{homeserver}

Vous pouvez notifier plusieurs utilisateurs en DM dans une seule URL :

• matrixs://{user}:{password}@{hostname}/@{user1}/@{user2}
• matrixs://{token}@{hostname}/@{user1}/@{user2}

Note

Lorsque vous écrivez @alice sans préciser de serveur, Apprise le renseigne automatiquement avec votre homeserver. Pour contacter quelqu’un sur un autre serveur, indiquez son adresse complète : @alice:otherhost.com. Si vos messages directs ne sont pas transmis, essayez d’ajouter ?hsreq=no à votre URL — cela aide sur certaines installations de serveurs auto-hébergés (voir ci-dessous).

Mélanger les Types de Cibles

Les alias de salon (#), les room IDs (!) et les utilisateurs DM (@) peuvent être librement combinés dans n’importe quel ordre au sein d’une même URL :

• matrixs://{user}:{password}@{hostname}/#{room_alias}/@{target_user}
• matrixs://{user}:{password}@{hostname}/#{room_alias}/!{room_id}/@{target_user}
• matrixs://{token}@{hostname}/#{room_alias}/!{room_id}/@{target_user}

Note

Si aucun utilisateur et/ou mot de passe n’est précisé, le processus d’enregistrement Matrix peut être déclenché. Certains serveurs Matrix autorisent l’enregistrement automatique d’utilisateurs temporaires, selon leur configuration. Dans la plupart des environnements de production, vous devriez toujours fournir {user} et {password}, ou bien un {token} pré-généré.

Identifiants de Salon et Comportement du Homeserver

Matrix prend en charge à la fois :

• les alias de salon préfixés par # ;
• les room IDs préfixés par !.

Les identifiants de salon peuvent inclure un composant homeserver, par exemple :example.com. Dans Matrix, les alias de salon sont souvent écrits avec un homeserver, et les room IDs sont eux aussi généralement attendus sous cette forme.

Exemples :

• #general
• #general:example.com
• !abc123
• !abc123:example.com

Comportement par Défaut (Recommandé)

Par défaut, Apprise impose la présence d’un homeserver sur les identifiants de salon lorsqu’il manque.

Si vous fournissez :

• #room : il est interprété en interne comme #room:{hostname}
• !room : il est interprété en interne comme !room:{hostname}

Si vous incluez explicitement un homeserver, Apprise le respecte exactement tel quel.

Désactivation de ce Comportement (Mode Compatibilité)

La plupart des utilisateurs n’auront jamais besoin de cette option. Si vos notifications fonctionnent, passez à la suite.

Si les choses ne fonctionnent pas — notamment si vous observez des erreurs 404 lorsqu’Apprise tente de rejoindre un salon — essayez d’ajouter ?hsreq=no à votre URL. Cela indique à Apprise d’utiliser les noms et identifiants de salon exactement tels que vous les avez saisis, sans y ajouter automatiquement le nom de votre serveur :

• #room est utilisé exactement tel qu’il est fourni.
• !room est utilisé exactement tel qu’il est fourni.

Avec cette URL :

matrix://user:pass@localhost/#room/!abc123

Avec le paramètre par défaut :

• #room devient #room:localhost
• !abc123 devient !abc123:localhost

Avec ?hsreq=no :

matrix://user:pass@localhost/#room/!abc123?hsreq=no

• #room reste #room
• !abc123 reste !abc123

Cela s’applique aussi aux cibles DM. La personne à qui vous écrivez est toujours recherchée avec son adresse complète (par exemple @alice:localhost) — cela ne change pas. Mais si la livraison des messages directs échoue quand même, ajouter ?hsreq=no peut aider sur certains serveurs. C’est la première chose à essayer.

Mode Webhook

Lorsque vous précisez l’argument ?mode=, le plugin bascule entièrement en comportement webhook et la syntaxe change :

• matrix://{user}:{token}@{hostname}?mode=matrix
• matrixs://{token}@{hostname}:{port}?mode=matrix
• matrix://{user}:{token}@{hostname}?mode=slack&format=markdown
• matrixs://{token}@{hostname}?mode=slack&format=markdown
• matrix://{user}:{token}@{hostname}?mode=hookshot
• matrixs://{user}:{token}@{hostname}?mode=hookshot&path=/webhook

Avec matrix-hookshot, le chemin du webhook est configurable et vaut /webhook par défaut :

• matrixs://{user}:{token}@{hostname}?mode=hookshot
• matrixs://{user}:{token}@{hostname}?mode=hookshot&path=/public-hooks

Si vous utilisez t2bot.io, vous pouvez utiliser :

• matrix://{t2bot_webhook_token}
• matrix://{user}@{t2bot_webhook_token}

Ou directement :

• https://webhooks.t2bot.io/api/v1/matrix/hook/{t2bot_webhook_token}

Détail des Paramètres

Variable	Requis	Description
hostname	*Oui	Le serveur Matrix auquel vous souhaitez vous connecter.
t2bot_webhook_token	*Oui	Utilisé en mode webhook t2bot. Dans ce cas, il tient lieu de nom d’hôte.
user	Non	L’utilisateur à authentifier, et éventuellement à enregistrer, auprès du serveur Matrix.
password	Non	Le mot de passe à utiliser pour l’authentification, et éventuellement l’enregistrement, auprès du serveur Matrix.
token	Non	Jeton d’accès Matrix pré-généré. Utilisez-le à la place de user et password lorsque votre serveur désactive la connexion par mot de passe, par exemple dans un déploiement SSO uniquement. Peut aussi être fourni avec ?token=. Lorsqu’il est utilisé sans nom d’utilisateur, placez-le dans la position utilisateur : matrix://{token}@{hostname}/.
port	Non	Port sur lequel le serveur Matrix écoute. Par défaut, matrixs:// utilise le port 443 tandis que matrix:// utilise le port 80.
room_alias	Non	Alias du salon à rejoindre et notifier. Il est recommandé de le préfixer avec #.
room_id	Non	Identifiant du salon à rejoindre et notifier. Il doit être préfixé avec !.
thumbnail	Non	Affiche une image avant chaque notification pour représenter le type de notification. La valeur par défaut est False.
mode	Non	Active le mode webhook. Les valeurs valides sont matrix, slack, t2bot et hookshot.
path	Non	Utilisé avec le mode hookshot pour définir le chemin webhook public. La valeur par défaut est /webhook. Par exemple, si votre instance hookshot est exposée à https://hookshot.example/public-hooks/{token}, alors utilisez ?mode=hookshot&path=/public-hooks.
format	Non	Sélectionne le format de sortie Matrix : text, html ou markdown. Apprise v1 utilise un seul format de sortie par URL. La valeur par défaut est text.
msgtype	Non	Type de message Matrix : text ou notice. La valeur par défaut est text.
version	Non	Surcharge la version de l’API Client Matrix. Les valeurs prises en charge sont 2 et 3. La valeur par défaut est 3. Peut aussi être fournie avec ?v=.
hsreq	Non	Lorsqu’il est activé, ce qui est le cas par défaut, Apprise ajoute automatiquement le homeserver authentifié aux identifiants de salon qui n’en contiennent pas déjà un. Par exemple, #room devient #room:hostname. Définissez no pour désactiver ce comportement et utiliser les identifiants exactement tels qu’ils sont fournis.
e2ee	Non	Contrôle le chiffrement de bout en bout via le protocole Matrix Olm/Megolm. Lorsqu’il est activé, ce qui est le cas par défaut, Apprise détecte automatiquement si chaque salon est configuré pour le chiffrement et chiffre alors les messages comme les pièces jointes pour ceux où il est configuré, tout en envoyant les autres en texte brut. Lorsqu’Apprise crée un nouveau salon avec e2ee=yes, il définit l’état m.room.encryption dès la création afin que le salon soit chiffré dès le premier message. Cela exige le paquet Python cryptography et une connexion matrixs:// (HTTPS). Non pris en charge en mode webhook. Définissez no pour toujours envoyer en clair et éviter la création de salons E2EE. La valeur par défaut est yes.
autoverify	Non	Active la vérification automatique de l’appareil avec le protocole SAS de Matrix. Lors de la première utilisation, Apprise attend jusqu’à deux minutes une demande provenant d’une autre session connectée au même compte. Une vérification réussie est mémorisée. Définir autoverify=yes active automatiquement e2ee=yes aussi ; inutile de définir les deux. Passez e2ee=no explicitement si vous souhaitez tout de même désactiver le chiffrement. Nécessite également une connexion matrixs:// (HTTPS). La valeur par défaut est no.
target_user	Non	Identifiant utilisateur Matrix à notifier en message direct. Doit être préfixé par @, par exemple @alice ou @alice:homeserver. Apprise cherche, ou crée, automatiquement un salon DM avec cet utilisateur. Non pris en charge en mode webhook.
discovery	Non	Lorsqu’elle est activée (par défaut), Apprise utilise .well-known/matrix/client au premier usage pour trouver l’adresse du homeserver. Définissez no pour vous connecter directement au nom d’hôte de votre URL Apprise. L’adresse découverte doit utiliser https:// et ne doit contenir ni nom d’utilisateur ni mot de passe. Sinon, la découverte échoue et rien n’est envoyé. Désactivée automatiquement en mode webhook. La valeur par défaut est yes.

Note

Si ni {room_alias}, ni {room_id}, ni {target_user} n’est précisé, Apprise interrogera le serveur pour récupérer les salons actuellement rejoints et les notifiera tous.

Note

Lors d’un envoi vers un {target_user}, Apprise recherche un salon DM existant via les données de compte m.direct, ou en crée un si nécessaire. Si l’utilisateur cible quitte ensuite ce salon, Apprise continuera à y envoyer les messages, qui seront acceptés par le serveur mais ne seront plus visibles pour l’utilisateur. Il n’existe pas de réinvitation automatique. Pour corriger cela, l’utilisateur doit rejoindre à nouveau le salon, ou vous devez effacer le stockage persistant Apprise afin qu’un nouveau salon DM soit créé lors du prochain envoi.

Note

E2EE exige à la fois une URL matrixs://, donc HTTPS, et le paquet Python cryptography, installé par exemple via pip install cryptography. Avec une connexion matrix:// en HTTP simple, E2EE est silencieusement ignoré et les messages sont envoyés en clair, quelle que soit la valeur de e2ee.

La vérification automatique peut retarder votre première notification

autoverify=yes active automatiquement e2ee=yes ; inutile de définir les deux. Passez e2ee=no explicitement si vous souhaitez conserver le chiffrement désactivé malgré tout.

Avec autoverify=yes, la première notification attend jusqu’à deux minutes une demande de vérification. Dans un autre client Matrix connecté au même compte, choisissez Vérifier la session, puis sélectionnez l’appareil Apprise.

Apprise inscrit un code à trois nombres dans ses journaux. Vérifiez qu’il correspond au code de votre autre client avant d’y approuver la vérification.

Si la vérification n’aboutit pas à temps, la notification chiffrée est tout de même envoyée. Apprise attend environ 15 minutes avant de réessayer. Après une vérification réussie, les notifications suivantes n’attendent pas.

Astuce

Apprise met en cache les clés de session E2EE ainsi que l’état de chiffrement des salons dans son stockage persistant afin d’éviter des allers-retours réseau inutiles. Si la configuration de chiffrement d’un salon change après le premier envoi, par exemple si le chiffrement est activé sur un salon auparavant non chiffré, Apprise continuera à utiliser l’état mis en cache jusqu’à réinitialisation du stockage. Pour forcer un nouvel échange de clés et une nouvelle lecture de l’état du salon, effacez le stockage persistant Apprise de cette instance du plugin.

Salons créés par Apprise lorsque e2ee=yes

Lorsque e2ee=yes, ce qui est la valeur par défaut, et qu’Apprise crée un nouveau salon, soit parce qu’un alias n’existe pas encore, soit parce qu’un nouveau salon DM est nécessaire, Apprise crée ce salon avec l’événement d’état m.room.encryption défini sur m.megolm.v1.aes-sha2.

• Le chiffrement est irréversible une fois activé sur un salon ; Apprise chiffre donc les nouveaux salons dès leur création afin que chaque message, y compris le tout premier, soit protégé.
• Les clients ne prenant pas en charge E2EE, anciens ou non standard, peuvent toujours rejoindre le salon, mais ils ne pourront pas lire les messages chiffrés.
• Si vous avez besoin d’un salon lisible par des clients non E2EE, précréez-le dans votre client Matrix sans activer le chiffrement avant de le cibler avec Apprise, ou utilisez e2ee=no dans votre URL Apprise.

Pour les salons qu’Apprise n’a pas créés, il vérifie l’état m.room.encryption à chaque envoi et chiffre automatiquement les messages pour les salons qui l’ont déjà défini, quelle que soit leur origine. Les salons sans état de chiffrement reçoivent toujours des messages en clair, même lorsque e2ee=yes.

Paramètres Globaux

Variable	Description
overflow	Gère les messages qui dépassent la limite documentée d’un service. La valeur par défaut est upstream. 👉 upstream : envoie un seul message sans le découper ni le tronquer selon cette limite. 👉 truncate : conserve la partie qui tient dans la limite et supprime le reste. 👉 split : privilégie une coupure lisible, utilise une coupure stricte si nécessaire, puis envoie toutes les parties dans l’ordre. Le découpage d’un contenu non déclaré ou structuré reste une solution au mieux. Utilisez upstream si le corps doit rester intact.
format	Ce paramètre peut être défini sur text, html ou markdown. Certains services prennent en charge plusieurs formats de publication du contenu. La valeur par défaut varie selon le service choisi et peut correspondre à l’un de ces trois formats. Vous pouvez facultativement forcer cette option pour vous écarter du comportement par défaut. Si le service ne prend pas en charge plusieurs formats de transmission, ce champ est ignoré.
verify	Les requêtes externes vers des emplacements sécurisés, par exemple via https, utilisent des certificats. Par défaut, Apprise vérifie la validité de ces certificats ; si ce n’est pas le cas, aucune notification n’est envoyée à la source. Dans certains cas, un utilisateur ne dispose pas d’une autorité de certification pour valider la clé ou fait simplement confiance à la source ; dans ce cas, vous pouvez définir ce drapeau sur no. Par défaut, il vaut yes.
redirect	Par défaut, Apprise suit les redirections HTTP (réponses 3xx) émises par le serveur distant, conformément au comportement de la bibliothèque requests sous-jacente. Si vous souhaitez empêcher la transmission des en-têtes personnalisés et des identifiants vers des destinations différentes de l’URL d’origine, définissez cette option sur no. Par défaut, elle vaut yes.
cto	Signifie Socket Connect Timeout. Il s’agit du nombre de secondes pendant lesquelles Requests attend que votre client établisse une connexion avec une machine distante, ce qui correspond à l’appel connect() sur la socket. La valeur par défaut est de 4.0 secondes.
rto	Signifie Socket Read Timeout. Il s’agit du nombre de secondes pendant lesquelles le client attend que le serveur envoie une réponse. La valeur par défaut est de 4.0 secondes.
emojis	Active la prise en charge des emojis, par exemple :+1: qui sera traduit en 👍. Par défaut, cette option vaut no. Remarque : selon la configuration côté serveur, l’administrateur peut désactiver globalement la prise en charge des emojis ; mais par défaut, ce n’est pas le cas.
tz	Identifie le fuseau horaire de la base IANA que vous souhaitez utiliser. Par défaut, celui-ci est détecté à partir de la configuration du serveur qui exécute Apprise. Vous pouvez le définir sur des valeurs comme America/Toronto, ou sur tout autre fuseau correctement formaté correspondant à votre région.
retry	Nombre de tentatives de remise supplémentaires après le premier échec, avant d’abandonner. Accepte un entier compris entre 0 et 10. La valeur par défaut est 0 (aucune nouvelle tentative — une seule tentative est effectuée). Lorsqu’il est combiné avec wait, Apprise marque une pause du nombre de secondes spécifié entre chaque tentative.
wait	Nombre de secondes à attendre entre les nouvelles tentatives. Accepte une valeur décimale comprise entre 0.0 et 20.0 ; les entiers sont automatiquement convertis en virgule flottante. La valeur par défaut est 0.5. Ce paramètre n’est utile que si retry est supérieur à zéro — un service avec retry=0 effectue exactement une tentative, quelle que soit la valeur de wait.
optional	Lorsqu’il est défini sur yes, un échec de remise pour ce service est silencieusement absorbé. Le résultat global de notify() est quand même considéré comme réussi même si ce point de terminaison était injoignable, à condition que tous les services requis (non optionnels) du même lot aient réussi. Ce drapeau ne saute pas la remise ni ne contourne la logique de nouvelles tentatives — toutes les tentatives configurées sont effectuées avant que l’échec soit absorbé. Par défaut, il vaut no, ce qui signifie que chaque échec est propagé à l’appelant.

Exemples

Envoyer une notification Matrix sécurisée avec nom d’utilisateur et mot de passe :

# Supposons que {hostname} soit matrix.example.com
# Supposons que {user} soit nuxref
# Supposons que {password} soit abc123
# Notifier #general et #apprise
apprise -vv -t "Titre du Message de Test" -b "Corps du Message de Test" \
   matrixs://nuxref:abc123@matrix.example.com/#general/#apprise

Envoyer une notification avec un jeton d’accès pré-généré, pratique lorsque la connexion par mot de passe est désactivée sur le serveur :

# Supposons que {hostname} soit matrix.example.com
# Supposons que {token} soit syt_abc123...
apprise -vv -t "Titre du Message de Test" -b "Corps du Message de Test" \
   "matrixs://syt_abc123@matrix.example.com/#general"

Si un salon ou une cible DM n’est pas trouvé (utilisez -vv pour voir l’erreur), ajoutez ?hsreq=no pour qu’Apprise n’ajoute pas automatiquement le nom du serveur :

# Cible de type room ID
apprise -vv -t "Titre du Message de Test" -b "Corps du Message de Test" \
   matrixs://nuxref:abc123@matrix.example.com/!abc123?hsreq=no

# Cible DM -- à essayer aussi si la livraison à @bob échoue
apprise -vv -t "Titre du Message de Test" -b "Corps du Message de Test" \
   matrixs://nuxref:abc123@matrix.example.com/@bob?hsreq=no

Utiliser l’API v2, requise pour les pièces jointes sur certains déploiements :

apprise -vv -t "Titre du Message de Test" -b "Corps du Message de Test" \
   matrixs://nuxref:abc123@matrix.example.com/#general?v=2

E2EE est activé par défaut lorsque le paquet cryptography est installé et que le salon le prend en charge. Pour désactiver explicitement E2EE et toujours envoyer en clair :

apprise -vv -t "Titre du Message de Test" -b "Corps du Message de Test" \
   "matrixs://nuxref:abc123@matrix.example.com/#general?e2ee=no"

Activer la vérification automatique de l’appareil par SAS (ceci active aussi le chiffrement E2EE, inutile de passer également e2ee=yes). Lors du premier envoi, lancez Vérifier cet appareil pour la session Apprise depuis un autre client connecté au même compte :

apprise -vv -t "Titre du Message de Test" -b "Corps du Message de Test" \
   "matrixs://nuxref:abc123@matrix.example.com/#general?autoverify=yes"

Envoyer un message direct à un utilisateur Matrix :

# Supposons que {hostname} soit matrix.example.com
# Supposons que {user} soit nuxref, et {password} abc123
# Envoyer un MP à @bob sur le même homeserver
apprise -vv -t "Titre du Message de Test" -b "Corps du Message de Test" \
   matrixs://nuxref:abc123@matrix.example.com/@bob

Envoyer un message direct avec un jeton d’accès pré-généré :

# Supposons que {hostname} soit matrix.example.com
# Supposons que {token} soit syt_abc123...
apprise -vv -t "Titre du Message de Test" -b "Corps du Message de Test" \
   "matrixs://syt_abc123@matrix.example.com/@bob"

Envoyer une requête webhook t2bot.io :

# Supposons que {webhook} soit ABCDEFG12345
apprise -vv -t "Titre du Message de Test" -b "Corps du Message de Test" \
   matrix://ABCDEFG12345

Envoyer une requête webhook matrix-hookshot :

# Supposons que {hostname} soit hookshot.example.com
# Supposons que {token} soit ABCDEFG12345
apprise -vv -t "Titre du Message de Test" -b "Corps du Message de Test" \
   "matrixs://apprise:ABCDEFG12345@hookshot.example.com?mode=hookshot"

Si votre instance hookshot est exposée derrière un chemin webhook public personnalisé :

apprise -vv -t "Titre du Message de Test" -b "Corps du Message de Test" \
   "matrixs://apprise:ABCDEFG12345@hookshot.example.com?mode=hookshot&path=/public-hooks"