Formatage et Pièces Jointes

Apprise peut envoyer du texte brut, du Markdown, du HTML et des pièces jointes, puis adapter ce que vous transmettez à ce que chaque service peut réellement accepter. Par exemple, un service qui ne prend en charge que du texte recevra tout de même votre notification, mais tout format enrichi sera réduit de manière appropriée.

Formats de Message

Apprise ne devine pas automatiquement votre type de contenu. À la place, vous lui indiquez le type de contenu fourni, et Apprise utilise cette information pour prendre des décisions intelligentes, service par service.

Apprise reconnaît quatre états de format d’entrée :

État	Description
(implicite) none	Aucun format déclaré. Le contenu est transmis tel quel.
text	Entrée en texte brut. Apprise peut simplifier le contenu pour les services texte uniquement.
markdown	Entrée en Markdown. Apprise peut convertir ou simplifier selon le besoin.
html	Entrée en HTML. Apprise peut supprimer ou convertir le balisage si nécessaire.

Note

• L’état none est implicite. Il est utilisé automatiquement lorsqu’aucun format n’est fourni.
• L’état none ne peut pas être défini explicitement via le CLI, la bibliothèque ou l’API.

En bref : Apprise préserve votre contenu autant que possible et ne l’adapte que lorsqu’une destination ne peut pas prendre en charge ce que vous avez fourni.

Déclarer l’Entrée vs Transformer la Sortie

Lorsque vous spécifiez un format (comme text, markdown ou html), vous décrivez votre entrée, vous ne forcez pas un format de sortie particulier.

Apprise utilise cette information pour déterminer si une transformation est nécessaire pour une destination donnée.

• Si le service de destination prend nativement en charge le format déclaré, le contenu est transmis tel quel
• Si la destination ne peut pas prendre en charge le format déclaré, Apprise effectue la conversion minimale nécessaire
• Si aucune conversion n’est requise, aucune transformation n’a lieu

Autrement dit, Apprise n’intervient que lorsqu’il existe un décalage entre le format d’entrée déclaré et ce que le fournisseur amont peut gérer. Cela n’est possible que si vous avez fourni un format d’entrée à exploiter.

Par exemple :

• Un message HTML envoyé par email peut être remis sous forme de HTML enrichi
• Le même HTML envoyé par SMS sera converti en texte brut lisible
• Un message Markdown envoyé à un service de discussion peut conserver sa mise en forme
• Ce même Markdown envoyé à un service texte uniquement sera automatiquement simplifié

Cela rend les destinations plus compatibles sans vous obliger à adapter manuellement le contenu pour chaque service.

Que se Passe-t-il si Vous ne Précisez Aucun Format ?

Si vous ne précisez pas de format, Apprise suppose des états légèrement différents selon le composant utilisé :

Interface	Format d’entrée par défaut
CLI	text
Python API	none - le contenu est transmis tel quel sauf si body_format est fourni dans l’appel notify() ou défini dans AppriseAsset()
Apprise-API	none - le contenu est transmis tel quel sauf si format est fourni dans la charge utile /notify/

À l’exception du CLI, si aucun input_format n’est précisé :

• Le contenu est transmis tel quel
• Aucune conversion ni assainissement n’a lieu dans Apprise
• Tout balisage (HTML, Markdown, etc.) est traité comme du texte littéral

Ce comportement est intentionnel et utile si :

• vous savez déjà que la destination ne prend en charge que du texte ;
• vous voulez un contrôle exact sur ce qui est envoyé.

Déclarer le bon format d’entrée est facultatif, mais cela permet à Apprise d’aider plus efficacement sur des destinations mixtes.

Exemples CLI

Utilisez --input-format pour indiquer à Apprise comment interpréter le contenu du corps du message.

# Corps en Markdown
apprise -t "Publication" -b "**v1.2.3** est maintenant en ligne" \
  --input-format=markdown \
  "discord://..."

# Corps en HTML
apprise -t "Rapport de build" -b "<b>Succès</b> : artefacts téléversés" \
  --input-format=html \
  "mailto://user:pass@example.com"

Exemples pour la Bibliothèque Python

Utilisez body_format pour préciser le format du message que vous fournissez.

from apprise import Apprise
from apprise import NotifyFormat

apobj = Apprise()
apobj.add("discord://...")

# Entrée Markdown
apobj.notify(
    title="Statut",
    body="**Tous les contrôles sont passés**",
    body_format=NotifyFormat.MARKDOWN,
)

# Entrée HTML
apobj.notify(
    title="Rapport de build",
    body="<b>Succès</b> : artefacts téléversés",
    body_format=NotifyFormat.HTML,
)

Exemples Apprise-API

Pour les charges utiles JSON, utilisez le champ format :

# Exemple sans état
curl -X POST http://localhost:8000/notify/ \
  -d 'urls=["discord://..."]' \
  -d 'title=Statut' \
  -d 'body=**Tous les contrôles sont passés**' \
  -d 'format=markdown'

# Exemple avec état
curl -X POST http://localhost:8000/notify/team-alerts/\
  -d 'tags=outage' \
  -d 'type=failure' \
  -d 'title=Rapport d''incident' \
  -d 'body=<strong>Le serveur de fichiers ne répond plus</strong>' \
  -d 'format=html'

Si vous utilisez déjà Apprise, envisagez simplement d’utiliser le service API Apprise pour simplifier les requêtes avec état :

# --config= vous permet de pointer vers une API Apprise amont pour votre
# configuration.
apprise --config=http://localhost:8000/cfg/team-alerts/ \
  --tag=outage \
  --input-format=html \
  --notification-type=failure \
  --title "Rapport d'incident" \
  --body "<strong>Le serveur de fichiers ne répond plus</strong>"

Pour les Développeurs

Si vous utilisez déjà l’API de manière intensive (en particulier pour les exemples multilingues et les envois multipart), la page Intégrations API reste la référence canonique.

Pour les Administrateurs

À condition que le serveur API Apprise n’ait pas activé APPRISE_CONFIG_LOCK, vous pouvez placer l’URL de configuration de votre API Apprise dans l’un des emplacements de configuration par défaut recherchés par le CLI Apprise pour simplifier encore davantage vos appels :

~/.config/apprise/apprise.yaml

include http://localhost:8000/cfg/team-alerts/

Votre commande CLI devient alors beaucoup plus simple :

apprise --tag=outage --input-format=html --notification-type=failure \
  --title "Rapport d'incident" \
  --body "<strong>Le serveur de fichiers ne répond plus</strong>"

Sélectionner un Format de Sortie (Diffusion Amont)

En plus de déclarer le format d’entrée, certains services vous permettent de choisir la manière dont le contenu est livré en amont en précisant un paramètre format= directement dans l’URL du service.

Cela ne décrit pas l’entrée que vous fournissez. Cela indique plutôt au plugin de service quelle route de diffusion ou quelle représentation utiliser, si elle est prise en charge.

Comment les Formats d’Entrée et de Sortie Fonctionnent Ensemble

• Format d’entrée (body_format, --input-format, API format)
  Indique à Apprise quel type de contenu vous fournissez

• Format de sortie (?format= dans une URL de service)
  Indique au plugin de service comment livrer ce contenu au fournisseur amont

Lorsque les deux sont précisés, Apprise adapte correctement le contenu si nécessaire avant de le transmettre à la route de diffusion amont sélectionnée.

Si le service amont ne prend pas en charge le format de sortie demandé, il est ignoré silencieusement et le comportement par défaut du service est utilisé à la place.

Exemples

Email

L’email prend en charge plusieurs formats de diffusion.

# Comportement par défaut (email HTML)
mailto://user:pass@example.com

# Forcer une diffusion en texte brut
mailto://user:pass@example.com?format=text

Dans ce cas :

• format=html est inutile car le HTML est le comportement par défaut
• format=text sélectionne explicitement la voie de diffusion en texte brut
• format=markdown est ignoré car l’email ne prend pas en charge la diffusion Markdown

Services avec Plusieurs Points de Terminaison

Certains services exposent plusieurs endpoints API selon la prise en charge du format.

Dans ces cas, définir format= peut :

• sélectionner un endpoint amont différent ;
• modifier la manière dont le contenu est rendu par le service ;
• contourner complètement les transformations de format.

Ce comportement est spécifique au plugin et ne s’applique que lorsque le service prend explicitement en charge plusieurs formats de sortie.

Quand est-ce Utile ?

Préciser un format de sortie est utile si :

• vous voulez imposer un type de diffusion spécifique (par exemple un email en texte brut) ;
• le service prend en charge plusieurs représentations du contenu ;
• vous envoyez du contenu tel quel et devez le faire passer par un chemin amont précis.

Si un service ne prend pas en charge le format de sortie demandé, Apprise revient en toute sécurité au comportement par défaut.

Pièces Jointes

Les pièces jointes vous permettent d’envoyer des fichiers tels que des images, des journaux, des PDF et des artefacts en même temps que votre message. Leur arrivée sous forme de véritables pièces jointes dépend de ce que le service de destination prend en charge.

Pièces jointes via le CLI

Utilisez --attach une ou plusieurs fois :

apprise -t "Alerte système" -b "Voir le journal en pièce jointe" \
  --attach /var/log/syslog \
  "mailto://user:pass@example.com"

apprise -b "Voici les fichiers" \
  --attach /tmp/photo1.jpg \
  --attach /tmp/photo2.jpg \
  "tgram://..."

Pièces Jointes en Python

Passez un chemin unique ou une liste de chemins via attach :

from apprise import Apprise

apobj = Apprise()
apobj.add("tgram://...")

# Pièce jointe unique
apobj.notify(body="Voir la pièce jointe", attach="/path/to/file.txt")

# Plusieurs pièces jointes
apobj.notify(
    body="Artefacts joints",
    attach=[
        "/path/to/build.log",
        "/path/to/report.pdf",
    ],
)

Pièces Jointes Distantes (URLs)

Vous pouvez également fournir une URL et Apprise la récupérera avant la diffusion :

# Apprise téléchargera cette image et l'enverra à la destination
# si vous fournissez un couple user/pass, il s'authentifiera même
# avant de récupérer la pièce jointe
apobj.notify(
    body="Capture de la caméra de sécurité",
    attach="http://admin:pass@example.local/cam/snapshot.jpg"
)

Attention

Si l’URL d’une pièce jointe distante contient des identifiants, traitez-la comme un secret. Évitez de la versionner dans un dépôt ou de l’écrire dans les journaux.

Pièces Jointes en Mémoire (AttachMemory)

Lorsque vous générez du contenu à la volée — HTML rendu, graphiques, CSV, PDF — vous pouvez le transmettre directement sous forme d’objet AttachMemory sans écrire quoi que ce soit sur disque.

CSV (général)

Passez directement une chaîne ou des bytes — aucun fichier temporaire n’est créé :

import apprise
from apprise.attachment import AttachMemory

apobj = apprise.Apprise()
apobj.add("discord://webhook_id/webhook_token/")

apobj.notify(
    body="Les relevés du jour sont en pièce jointe.",
    attach=AttachMemory(
        content="date,value\n2026-03-20,42\n2026-03-21,38\n",
        name="readings.csv",
        mimetype="text/csv",
    ),
)

Le contenu str est automatiquement encodé en UTF-8. Utilisez bytes si vous disposez déjà de données binaires.

Pillow (image)

Générez une image avec Pillow et envoyez-la sans l’enregistrer sur disque :

import io
import apprise
from apprise.attachment import AttachMemory
from PIL import Image, ImageDraw

# Dessiner une image simple
img = Image.new("RGB", (400, 200), color=(30, 30, 30))
draw = ImageDraw.Draw(img)
draw.text((20, 80), "Bonjour depuis Apprise !", fill=(255, 255, 0))

# Rendre dans un tampon mémoire
buf = io.BytesIO()
img.save(buf, format="PNG")

apobj = apprise.Apprise()
apobj.add("tgram://bottoken/ChatID")

apobj.notify(
    body="Image générée en pièce jointe.",
    attach=AttachMemory(
        content=buf.getvalue(),
        name="hello.png",
        mimetype="image/png",
    ),
)

Matplotlib (graphique)

Générez un graphique avec Matplotlib et joignez-le directement :

import io
import apprise
from apprise.attachment import AttachMemory
import matplotlib.pyplot as plt

# Construire le graphique
fig, ax = plt.subplots()
ax.plot([1, 2, 3, 4], [10, 24, 18, 32])
ax.set_title("Mesure quotidienne")
ax.set_xlabel("Jour")
ax.set_ylabel("Valeur")

# Rendre dans un tampon mémoire
buf = io.BytesIO()
fig.savefig(buf, format="png")
plt.close(fig)

apobj = apprise.Apprise()
apobj.add("tgram://bottoken/ChatID")

apobj.notify(
    body="Graphique de tendance nocturne en pièce jointe.",
    attach=AttachMemory(
        content=buf.getvalue(),
        name="trend.png",
        mimetype="image/png",
    ),
)

Astuce

Pour tous les détails sur les trois types de pièces jointes (AttachFile, AttachHTTP, AttachMemory) ainsi que les recommandations pour les auteurs de plugins, consultez la référence sur les pièces jointes.