Notifications Telegram

Aperçu

Source: https://telegram.org/
Prise en charge des images: Oui
Prise en charge des pièces jointes: Oui
Limites de caractères des messages:
- Corps: 4096
Format(s) de message pris en charge:
- ✓HTML
- MARKDOWN
Créer votre URL Apprise

Format du Message

Telegram utilise le HTML par défaut et accepte aussi le Markdown. Déclarer le format d’entrée permet à Apprise de convertir et de réparer le balisage pris en charge avant l’envoi.

Telegram n’accepte qu’un petit nombre de balises HTML. Lorsque votre format d’entrée est déclaré, Apprise remplace les autres par un rendu que Telegram sait afficher : les titres deviennent des lignes en gras, les éléments de liste deviennent des lignes -, les lignes de tableau deviennent des lignes dont les cellules sont séparées par |, et toute autre balise non prise en charge est retirée en conservant son texte.

Sans format d’entrée, Apprise suppose que le corps convient déjà au format Telegram choisi. overflow=split reste alors une solution au mieux et peut couper le balisage au mauvais endroit ; utilisez overflow=upstream si le message doit rester intact.

Configuration du Compte

Pour envoyer des notifications Telegram, commencez par créer un compte et un robot.

Si vous n’avez pas encore de compte, installez Telegram pour Android ou iOS. Telegram utilise votre numéro de téléphone pour vous connecter.

Une fois votre compte configuré, il peut être plus pratique d’utiliser l’interface web disponible ici depuis un PC, surtout pour le développement. Cette partie reste toutefois à votre convenance.

Configuration du Robot

Les notifications Telegram exigent que vous créiez un robot. Ce n’est qu’après cette étape que vous obtiendrez une information essentielle dont Apprise a besoin, appelée identifiant de jeton (ou bot_token).

Pour cela, vous devez ouvrir une conversation dans Telegram avec BotFather. Il est accessible à tous les utilisateurs inscrits sur la plateforme. Une fois la boîte de dialogue ouverte avec lui :

Tapez : /newbot
Répondez aux questions posées ensuite, notamment pour définir son nom, etc.
Une fois l’étape 2 terminée, un bot_token vous sera fourni, sous une forme ressemblant à 123456789:alphanumeric_characters.
Saisissez ensuite /start dans la même boîte de dialogue afin d’activer et d’initialiser votre tout nouveau robot.

La bonne nouvelle, c’est que cette procédure ne doit être effectuée qu’une seule fois. Une fois votre bot_token obtenu, conservez-le et vous n’aurez plus à recommencer. C’est via ce robot qu’Apprise peut envoyer des notifications Telegram à différents utilisateurs.

Le Casse-Tête du Chat ID

Mise à jour du 2021.12.23 : les développeurs de Telegram ont récemment facilité l’obtention de cet identifiant grâce à leur propre outil intégré, expliqué ici. Merci à @mattpackwood pour cette astuce !

En coulisses, Telegram notifie les utilisateurs à l’aide de leur {chat_id} et non de leur nom d’utilisateur, plus facile à retenir. Malheureusement, à l’heure actuelle, Telegram ne facilite pas vraiment la récupération de ce {chat_id} sans quelques astuces ou contournements que l’on peut trouver en cherchant en ligne ou en contactant leur équipe de support.

Cependant, Apprise peut simplifier cette tâche si votre objectif est simplement de vous envoyer un message privé. Dans ce cas, il suffit d’envoyer un message privé au nouveau robot que vous venez de créer. C’est tout !

En procédant ainsi, Apprise pourra détecter automatiquement votre {chat_id} à partir du message envoyé au robot.

tgram://{bot_token}/

Lorsque vous utilisez la forme courte de l’URL Telegram/Apprise et que le propriétaire du robot, probablement vous, est détecté correctement, le {chat_id} trouvé apparaîtra dans les journaux après l’envoi de la notification. Notez que l’API Telegram ne conserve les messages entrants que pendant 24 heures. Il est donc recommandé de mettre à jour ensuite votre URL Apprise pour y faire explicitement référence.

tgram://{bot_token}/{chat_id}

Remarque : vous pouvez aussi récupérer vous-même le {chat_id} après vous être d’abord envoyé un message, comme expliqué ci-dessus. Ensuite, il vous suffit de visiter https://api.telegram.org/bot{bot_token}/getUpdates.

Remarque : le mot-clé bot doit figurer devant le {bot_token} réel qui vous a été fourni par BotFather.
Le résultat contiendra le message que vous avez envoyé. Vous y trouverez également une section intitulée chat, avec l’id indiqué. Il s’agit du {chat_id} que vous pouvez utiliser pour envoyer directement des messages via Apprise.

Syntaxe

La syntaxe valide est la suivante :

tgram://{bot_token}/
- Remarque : comme indiqué plus haut, Apprise est suffisamment intelligent pour déterminer le chat_id du propriétaire du robot (vous), uniquement si vous lui avez d’abord envoyé au moins 1 message privé.
tgram://{bot_token}/{chat_id}/
tgram://{bot_token}/{chat_id1}/{chat_id2}/{chat_id3}/
tgram://{bot_token}/{chat_id}:{topic}/
tgram://{bot_token}/{chat_id1}:{topic1}/{chat_id2}:{topic2}/{chat_id3}:{topic3}/

Si vous souhaitez afficher l’icône ou l’image associée à la notification, vous pouvez l’activer en ajoutant ?image=yes à votre URL, comme ceci :

tgram://{bot_token}/?image=Yes
tgram://{bot_token}/{chat_id}/?image=Yes
tgram://{bot_token}/{chat_id1}/{chat_id2}/{chat_id3}/?image=Yes

Détail des Paramètres

Variable	Obligatoire	Description
bot_token	Oui	Jeton identifiant le robot que vous avez créé via BotFather.
chat_id	Oui	Identifie les utilisateurs auxquels votre robot doit livrer les notifications. Vous devez indiquer au moins 1 chat_id. Si aucun chat_id n’est précisé, le script de notification tentera de détecter celui du propriétaire du robot, vous, et l’utilisera.
image	Non	Vous pouvez ajouter l’argument ?image=Yes à la fin de votre URL afin qu’un message Telegram soit généré avant l’avis principal pour téléverser l’image associée. En raison des limitations du service, Telegram ne permet pas d’inclure une image directement dans un message texte. En revanche, vous pouvez envoyer un message contenant uniquement une image. Si ce drapeau est activé, apprise enverra d’abord une notification image, puis l’avis lui-même. Comme recevoir 2 messages pour 1 seul avis peut être gênant, cette option est désactivée par défaut.
format	Non	La valeur par défaut est html. Définissez-la sur markdown lorsque vous voulez utiliser le traitement Markdown de Telegram.
silent	Non	Indicateur `yes/no` permettant d’envoyer la notification en mode silencieux. La valeur par défaut est `no`.
preview	Non	Indicateur `yes/no` permettant d’afficher les aperçus web de votre publication. La valeur par défaut est `no`.
album	Non	Regroupe les photos et les vidéos dans des albums Telegram avec la valeur `yes`. Les GIF, les fichiers audio et les documents sont envoyés séparément dans leur ordre d’origine. Si Telegram refuse un album, chaque élément est envoyé séparément. Une photo ou une vidéo encore refusée est alors envoyée comme un fichier ordinaire. La valeur par défaut est `no`.
mdv	Non	Permet de définir la version de `markdown` à utiliser, soit `v1`, soit `v2`. La valeur par défaut est `v2` si rien n’est précisé. Cette valeur n’est prise en compte que si `?format=markdown` a également été défini.
topic	Non	Identifiant du fil de sujet dans lequel vous souhaitez publier votre message. Voici une publication StackOverflow expliquant comment récupérer le Topic Thread ID.
template	Non	Chemin vers un fichier gabarit de Message Riche local. Lorsqu’il est défini, le contenu du fichier est utilisé pour construire un Message Riche Telegram (`sendRichMessage`) à la place du message texte/Markdown/HTML par défaut. Le gabarit doit être un fichier JSON dont l’objet racine contient une liste `"blocks"` non vide. Voir Gabarits ci-dessous.
:jeton	Non	Jeton(s) personnalisé(s) pour la substitution dans le gabarit. Préfixez chaque nom de jeton par deux-points dans l’URL (par exemple `?:macle=mavaleur`). Tout jeton défini ici est disponible sous la forme `{{macle}}` dans le fichier gabarit.

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.

Gabarits

L’API Bot Telegram 10.1 a introduit les Messages Riches, une façon structurée, basée sur des blocks, de mettre en forme un message (titres de section, paragraphes, tableaux, citations, et plus) qui va bien au-delà de la prise en charge texte/Markdown/HTML décrite ci-dessus. Apprise ne tente pas de construire automatiquement ces blocs à votre place — l’argument ?template= vous permet plutôt de fournir votre propre fichier JSON de Message Riche préconstruit. Apprise lit ce fichier, substitue les espaces réservés {{jeton}}, puis envoie le résultat directement, vous donnant un contrôle total sur la structure.

Le gabarit doit être un objet JSON valide avec une liste "blocks" non vide. Chaque bloc doit être un objet JSON avec son propre champ "type" (par exemple paragraph, section_heading) ; Telegram valide lui-même la structure exacte des blocs, donc un bloc invalide entraînera le rejet de la notification. Consultez la documentation Telegram sur les Messages Riches pour la liste complète et à jour des types de blocs pris en charge et de leurs champs — Apprise vérifie seulement que chaque bloc est un objet muni d’un "type", il ne valide pas les champs internes d’un type de bloc particulier.

Lorsqu’un gabarit est utilisé, le title et le body de la notification ne sont pas fusionnés ni convertis de format comme c’est normalement le cas pour tgram:// — ils sont transmis tels quels sous forme de jetons de substitution {{app_title}}/{{app_body}} décrits ci-dessous, puisque c’est le gabarit lui-même qui définit la structure du message. Les pièces jointes (attach=) ne sont quant à elles pas affectées : elles continuent toujours d’être envoyées sous forme de messages de suivi séparés, exactement comme décrit plus haut.

Jetons intégrés

Les jetons suivants sont toujours disponibles dans votre gabarit :

Jeton	Description
`app_id`	L’identifiant de l’application ; par défaut `Apprise`.
`app_desc`	La description de l’application ; par défaut `Apprise Notification`.
`app_color`	Une chaîne de couleur hexadécimale pour le type de message (par exemple `#3AA3E3` pour info).
`app_color_hex`	Alias explicite de `app_color` ; même chaîne hexadécimale, nom auto-documenté.
`app_type`	Le type de message : `info`, `warning`, `success` ou `failure`.
`app_title`	Le titre de la notification transmis via `--title` / `-t`.
`app_body`	Le corps de la notification transmis via `--body` / `-b`.
`app_image_url`	L’URL de l’image associée au type de message, si `?image=yes` est défini.
`app_url`	L’URL de l’instance Apprise (par défaut `https://github.com/caronc/apprise`).

Jetons personnalisés

Tout jeton que vous inventez au-delà de l’ensemble intégré peut être fourni lors de l’envoi via la syntaxe :cle=valeur dans l’URL Apprise :

tgram://{bot_token}/{chat_id}/?template=/chemin/gabarit.json&:env=production

Dans le gabarit, référencez-le sous la forme {{env}}.

Exemples de gabarit

Enregistrez l’un des exemples suivants sous forme de fichier .json et pointez ?template= vers ce fichier. Chacun est prêt à être copié-collé comme point de départ.

Un titre de section construit à partir du titre, suivi d’un paragraphe construit à partir du corps :

{
  "blocks": [
    {
      "type": "section_heading",
      "text": "{{app_title}}"
    },
    {
      "type": "paragraph",
      "text": "{{app_body}}"
    }
  ]
}

Le même titre et le même corps, avec un séparateur qui sépare le message d’une petite ligne de signature :

{
  "blocks": [
    {
      "type": "section_heading",
      "text": "{{app_title}}"
    },
    {
      "type": "paragraph",
      "text": "{{app_body}}"
    },
    {
      "type": "divider"
    },
    {
      "type": "paragraph",
      "text": "Envoyé par {{app_id}}"
    }
  ]
}

Un avis de type déploiement qui injecte un jeton personnalisé env. Envoyez-le avec &:env=production dans l’URL :

{
  "blocks": [
    {
      "type": "section_heading",
      "text": "Déploiement : {{app_title}}"
    },
    {
      "type": "paragraph",
      "text": "{{app_body}}"
    },
    {
      "type": "divider"
    },
    {
      "type": "paragraph",
      "text": "Environnement : {{env}}"
    }
  ]
}

Exemples

Envoyer une notification Telegram à lead2gold :

# Supposons que notre {bot_token} soit 123456789:abcdefg_hijklmnop
# Supposons que le {chat_id} de lead2gold soit 12315544
apprise -vv -t "Titre du Message de Test" -b "Corps du Message de Test" \
   tgram://123456789:abcdefg_hijklmnop/12315544/

Vous voulez utiliser les fonctionnalités Markdown de Telegram ? Faites plutôt ceci :

# Supposons que notre {bot_token} soit 123456789:abcdefg_hijklmnop
# Supposons que le {chat_id} de lead2gold soit 12315544
# Nous forçons le format de sortie en markdown dans cet exemple
apprise -vv -t "Titre du Message de Test" -b "Corps du Message de Test" \
   tgram://123456789:abcdefg_hijklmnop/12315544/?format=markdown

Vous avez un sujet précis à notifier ?

# Supposons que notre {bot_token} soit 123456789:abcdefg_hijklmnop
# Supposons que le {chat_id} de lead2gold soit 12315544
# Supposons que le {topic_id} soit 1234567
apprise -vv -t "Titre du Message de Test" -b "Corps du Message de Test" \
   tgram://123456789:abcdefg_hijklmnop/12315544/?topic=1234567

Les sujets peuvent également être définis pour chaque chat_id :

# Supposons que notre {bot_token} soit 123456789:abcdefg_hijklmnop
# Supposons que le {chat_id} de lead2gold soit 12315544
# Supposons que le {topic_id} soit 1234567
apprise -vv -t "Titre du Message de Test" -b "Corps du Message de Test" \
   tgram://123456789:abcdefg_hijklmnop/12315544:1234567/

Vous avez plusieurs photos à envoyer ? Regroupez-les dans un seul album Telegram :

# Supposons que notre {bot_token} soit 123456789:abcdefg_hijklmnop
# Supposons que le {chat_id} de lead2gold soit 12315544
# Les photos arrivent dans un seul album au lieu de trois messages séparés
apprise -vv -t "Titre du Message de Test" -b "Corps du Message de Test" \
   --attach=/chemin/vers/une.jpg \
   --attach=/chemin/vers/deux.jpg \
   --attach=/chemin/vers/trois.jpg \
   tgram://123456789:abcdefg_hijklmnop/12315544/?album=yes

Envoyer une notification à l’aide d’un gabarit de Message Riche personnalisé (voir Gabarits ci-dessus), en injectant un jeton personnalisé avec le préfixe :cle=valeur :

# Supposons que le gabarit soit enregistré dans /etc/apprise/telegram-blocks.json
apprise -vv -t "Déploiement" -b "v2.3.1 déployé" \
   "tgram://123456789:abcdefg_hijklmnop/12315544/?template=/etc/apprise/telegram-blocks.json&:env=production"

Questions ou commentaires ?

Documentation

Vous avez repéré une faute de frappe ou une erreur ?

Problèmes Techniques

Vous rencontrez un problème avec le code ? Ouvrez un ticket sur GitHub :