Notifications Slack

Aperçu

• Source: https://slack.com/
• Prise en charge des images: Oui
• Prise en charge des pièces jointes: Oui
• Limites de caractères des messages:
  • Corps: 35000
• Créer votre URL Apprise

Configuration du compte

Slack est un peu plus complexe que certains autres services de notification. Voici donc un résumé rapide de ce que vous devez savoir et faire pour envoyer des notifications avec cet outil.

Méthode 1 : Webhook Entrant

Les notifications Slack exigent tout d’abord un incoming-webhook auquel se connecter.

1. Vous pouvez créer ce webhook ici. Suivez simplement l’assistant pour choisir à l’avance le ou les canaux où vos messages seront diffusés.
2. Vous pouvez aussi créer une Slack App ici et l’associer à l’un de vos espaces de travail Slack. Il suffit ensuite de quelques étapes supplémentaires, toutes effectuées depuis l’écran de configuration de l’application, pour récupérer votre URL webhook :
   • vous devez activer la fonctionnalité Incoming Webhook si ce n’est pas déjà fait ;
   • sur ce même écran de configuration, vous pouvez créer un webhook et l’associer à un canal ou à un utilisateur.

Quelle que soit l’option choisie ci-dessus, vous obtiendrez une URL webhook ressemblant à ceci :
https://hooks.slack.com/services/T1JJ3T3L2/A1BRTD4JD/TIiajkdnlazkcOXrIdevi7F

Cette URL correspond en pratique à :
https://hooks.slack.com/services/{tokenA}/{tokenB}/{tokenC}

Remarque : Apprise prend en charge cette URL telle quelle (depuis la version 0.7.7). Vous n’avez donc plus besoin de la reparser, même s’il y a un léger gain interne à le faire.

Si vous voulez la convertir en URL Apprise, procédez comme suit : la dernière partie de l’URL qui vous est fournie contient les 3 jetons nécessaires à l’envoi des notifications. Dans l’exemple ci-dessus, ils sont les suivants :

1. TokenA est T1JJ3T3L2
2. TokenB est A1BRTD4JD
3. TokenC est TIiajkdnlazkcOXrIdevi7F8

Méthode 2 : Créer un Robot

Les bots offrent un peu plus de souplesse que les webhooks. La principale différence est que les Slack Bots prennent en charge les pièces jointes, ce qui permet à Apprise d’en tirer parti.

1. Commencez par créer votre Slack App ici.
2. Choisissez un nom d’application, par exemple Apprise, sélectionnez votre espace de travail, puis cliquez sur Create App.
3. Vous pourrez ensuite ouvrir la section Bots, ajouter un utilisateur robot, lui donner un nom, puis choisir *Add Bot User.
4. Vous devrez fournir les bonnes permissions OAuth :
   
5. Sélectionnez ensuite Install App, puis Install App to Workspace.
6. Vous devrez autoriser l’application lorsqu’on vous le demandera.
7. Enfin, vous obtiendrez des informations très importantes pour Apprise. À partir de là, vous pourrez utiliser soit le jeton d’accès OAuth, soit le jeton d’accès OAuth de l’utilisateur robot, avec une syntaxe de type slack://{OAuth Access Token}.

Votre URL Apprise Slack, pour accéder à votre bot, peut ressembler à ceci :

• slack://xoxp-1234-1234-1234-4ddbc191d40ee098cbaae6f3523ada2d
• slack://xoxb-1234-1234-4ddbc191d40ee098cbaae6f3523ada2d

Les deux jetons OAuth fournis permettent de publier du texte dans des canaux et de joindre des fichiers. Le choix de l’un ou de l’autre depend donc de votre preference.

Syntaxe

La syntaxe valide est la suivante :

• slack://{tokenA}/{tokenB}/{tokenC}
• https://hooks.slack.com/services/{tokenA}/{tokenB}/{tokenC}
• slack://{OAuthToken}/
  • Un robot n’a pas de canal par défaut configurable dans Slack comme c’est le cas avec les webhooks. Si aucun canal n’est précisé, c’est #general qui sera utilisé.

Si vous utilisez l’ancienne méthode par webhook, sans passer par l’application, vous disposez d’un peu plus de liberté. Les URL suivantes fonctionneront donc également avec Apprise :

• slack://{tokenA}/{tokenB}/{tokenC}/#{channel}
• slack://{tokenA}/{tokenB}/{tokenC}/#{channel1}/#{channel2}/#{channelN}
• slack://{OAuthToken}/#{channel}
• slack://{botname}@{OAuthToken}/#{channel1}/#{channel2}/#{channelN}

Si vous connaissez l’Encoded-ID du canal que vous souhaitez cibler, vous pouvez utiliser le symbole plus (+) pour le distinguer des canaux dans l’URL. La syntaxe valide est la suivante :

• slack://{botname}@{tokenA}/{tokenB}/{tokenC}/+{encoded_id}
• slack://{botname}@{tokenA}/{tokenB}/{tokenC}/+{encoded_id1}/+{encoded_id2}/+{encoded_id3}
• slack://{botname}@{OAuthToken}/+{encoded_id}
• slack://{botname}@{OAuthToken}/+{encoded_id1}/+{encoded_id2}/+{encoded_id3}

Si vous connaissez le user_id auquel vous souhaitez envoyer votre notification Slack, plutôt qu’un canal, utilisez le symbole arobase (@). La syntaxe valide est la suivante :

• slack://{botname}@{tokenA}/{tokenB}/{tokenC}/@{user_id}
• slack://{botname}@{tokenA}/{tokenB}/{tokenC}/@{user_id1}/@{user_id2}/@{user_id3}
• slack://{botname}@{OAuthToken}/@{user_id}
• slack://{botname}@{OAuthToken}/@{user_id1}/@{user_id2}/@{user_id3}

Vous pouvez également combiner librement toutes ces formes dans l’ordre de votre choix :

• slack://**{botname}@{tokenA}/{tokenB}/{tokenC}/@{user_id}/#{channel}/+{encoded_id}
• slack://{botname}@{OAuthToken}/@{user_id}/#{channel}/+{encoded_id}

Méthode 3 : Webhooks Slack Workflow Builder

Les webhooks Slack Workflow Builder utilisent un format d’URL différent et sont détectés automatiquement. Vous pouvez coller l’URL native directement, ou construire une URL Apprise avec ?mode=workflow ou ?mode=trigger.

Workflow Builder (chemin à 4 segments sous /workflows/) :

• https://hooks.slack.com/workflows/{seg1}/{seg2}/{seg3}/{seg4}
• slack://{seg1}/{seg2}/{seg3}/{seg4}/?mode=workflow

Workflow Trigger (chemin à 3 segments sous /triggers/) :

• https://hooks.slack.com/triggers/{seg1}/{seg2}/{seg3}
• slack://{seg1}/{seg2}/{seg3}/?mode=trigger

Les deux formes envoient {"text": "Titre : Corps"} par défaut (le titre est omis s’il est vide). Vous pouvez aussi passer un fichier template= pour envoyer un payload Block Kit personnalisé.

Détail des Paramètres

Variable	Requis	Description
tokenA	Oui	La première partie des 3 jetons fournis après la création d’un incoming-webhook. OAuthToken n’est pas requis si vous utilisez le webhook Slack.
tokenB	Oui	La deuxième partie des 3 jetons fournis après la création d’un incoming-webhook. OAuthToken n’est pas requis si vous utilisez le webhook Slack.
tokenC	Oui	La dernière partie des 3 jetons fournis après la création d’un incoming-webhook. OAuthToken n’est pas requis si vous utilisez le webhook Slack.
OAuthToken	Oui	Jeton OAuth fourni par la Slack App lorsque vous utilisez un robot au lieu d’un webhook. Les jetons A, B et C ne sont alors pas utilisés.
channel	Non	Les canaux doivent être préfixés par #. Vous pouvez en préciser autant que vous voulez en les séparant par des slashs (/) dans l’URL.
encoded_id	Non	Slack permet aussi de désigner des canaux et canaux privés par un encoded_id. Si vous les connaissez, vous pouvez les utiliser à la place d’un nom de canal. Tous les encoded_id doivent être préfixés par +.
user_id	Non	Les utilisateurs doivent être préfixés par @. Vous pouvez en préciser autant que nécessaire en les séparant par des slashs (/) dans l’URL.
botname	Non	Remplace le nom d’affichage de l’expéditeur. En mode webhook, s’il n’est pas défini, Slack utilise le nom d’affichage configuré dans les paramètres du webhook. Définissez-le pour que les notifications apparaissent sous un nom personnalisé, quel que soit le webhook utilisé.
footer	Non	Détermine si l’icône de pied de page Apprise doit être affichée à chaque message. La valeur par défaut est yes.
image	Non	Détermine si l’image Apprise, reflétant la couleur d’état, doit être affichée avec chaque message. La valeur par défaut est yes.
mode	Non	Permet de forcer le mode de fonctionnement du plugin Slack. Il est détecté automatiquement par défaut, mais les valeurs possibles sont hook (webhook), gov-hook (webhook gouvernemental), bot (API bot Slack), workflow (webhook Workflow Builder) et trigger (webhook de déclenchement de workflow).
template	Non	Chemin vers un fichier gabarit local. Lorsqu’il est défini, le contenu du fichier est utilisé pour construire la charge utile Slack à la place de la mise en page par défaut (le mode Block Kit est activé automatiquement). Le gabarit doit être un fichier JSON dont l’objet racine contient une liste "blocks" non vide (format Slack Block Kit). Utilisez {{app_body}}, {{app_title}}, {{app_color}}, {{app_color_hex}}, {{app_type}}, {{app_id}}, {{app_desc}}, {{app_image_url}} et {{app_url}} comme jetons de substitution.
:jeton	Non	Jeton(s) personnalisé(s) pour la substitution dans le gabarit. Préfixez chaque nom de jeton par un deux-points dans l’URL (par exemple ?:maclé=mavaleur). Tout jeton défini ici est accessible via {{maclé}} dans le fichier gabarit.

Paramètres Globaux

Variable	Description
overflow	Ce paramètre peut être défini sur split, truncate ou upstream. Il détermine la manière dont Apprise remet le message que vous lui transmettez. Par défaut, il vaut upstream. 👉 upstream : ne fait aucune modification et transmet le message exactement tel qu’il a été reçu au service. 👉 truncate : veille à ce que le message tienne dans la limite amont documentée par le service. Si plus d’informations sont fournies que la limite définie, l’excédent est tronqué. 👉 split : similaire à truncate, sauf que si le message dépasse la limite amont documentée par le service, il est découpé en plusieurs morceaux plus petits puis envoyés séquentiellement.
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é. L’appel global notify() retourne quand même True 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’argument ?template= permet de fournir un fichier JSON Slack Block Kit preconstruit. Apprise lit le fichier, substitue les espaces reserves {{jeton}}, puis envoie le resultat directement — vous donnant un controle total sur la mise en page sans modifier le code d’Apprise.

Le gabarit doit etre un objet JSON valide avec une liste "blocks" non vide (format Slack Block Kit). La structure est validee par l’API Slack ; un format invalide entrainera le rejet de la notification.

Jetons integres

Les jetons suivants sont toujours disponibles dans votre gabarit :

Jeton	Description
app_id	L’identifiant de l’application ; par defaut Apprise.
app_desc	La description de l’application ; par defaut Apprise Notification.
app_color	Une chaine de couleur hexadecimale pour le type de message (par exemple #3AA3E3 pour info).
app_color_hex	Alias explicite de app_color ; meme chaine hexadecimale, 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 associee au type de message, si elle existe.
app_url	L’URL de l’instance Apprise (par defaut https://github.com/caronc/apprise).

Jetons personnalises

Tout jeton que vous inventez au-dela de l’ensemble integre peut etre fourni lors de l’envoi via la syntaxe :cle=valeur dans l’URL Apprise :

slack://{tokenA}/{tokenB}/{tokenC}/?template=/chemin/gabarit.json&:env=production&:team=platform

Dans le gabarit, referenciez-le sous la forme {{env}} ou {{team}}.

Exemple de gabarit

Enregistrez le contenu suivant sous forme de fichier .json et pointez ?template= vers ce fichier. Cet exemple produit un bloc d’en-tete avec le titre, un bloc de section avec le corps, et une barre laterale coloree via le champ color :

{
  "blocks": [
    {
      "type": "header",
      "text": { "type": "plain_text", "text": "{{app_title}}" }
    },
    {
      "type": "section",
      "text": { "type": "mrkdwn", "text": "{{app_body}}" }
    }
  ],
  "color": "{{app_color}}"
}

Exemples

Envoyer une notification Slack vers le canal #nuxref :

# Supposons que notre {tokenA} soit T1JJ3T3L2
# Supposons que notre {tokenB} soit A1BRTD4JD
# Supposons que notre {tokenC} soit TIiajkdnlazkcOXrIdevi7F
# Notre canal nuxref est represente par #nuxref
apprise -vv -t "Titre du Message de Test" -b "Corps du Message de Test" \
   slack:///T1JJ3T3L2/A1BRTD4JD/TIiajkdnlazkcOXrIdevi7F/#nuxref

Autrement, si vous utilisez un bot, une notification Slack vers le canal #general pourrait ressembler à ceci :

# Supposons que notre {OAuthToken} soit xoxb-1234-1234-4ddbc191d40ee098cbaae6f3523ada2d
# Notre canal general est represente par #general
apprise -vv -t "Titre du Message de Test" -b "Corps du Message de Test" \
   slack://xoxb-1234-1234-4ddbc191d40ee098cbaae6f3523ada2d/#general

Vous pouvez aussi désactiver le pied de page, par exemple ainsi :

# Supposons que notre {OAuthToken} soit xoxb-1234-1234-4ddbc191d40ee098cbaae6f3523ada2d
# Nous voulons l'envoyer vers notre canal #general ; %23 est la forme encodee du symbole #
# Nous definissons aussi footer sur no
apprise -vv -t "Titre du Message de Test" -b "Corps du Message de Test" \
   slack://xoxb-1234-1234-4ddbc191d40ee098cbaae6f3523ada2d/%23general?footer=no

Envoyer une notification via un gabarit Block Kit personnalise (voir l’Exemple de gabarit ci-dessus), en injectant des jetons personnalises avec le prefixe :cle=valeur :

# Supposons que le gabarit soit enregistre sous /etc/apprise/slack-blocks.json
apprise -vv -t "Deploiement" -b "v2.3.1 deploye" \
   "slack://xoxb-1234-1234-4ddbc191d40ee098cbaae6f3523ada2d/%23ops/?template=/etc/apprise/slack-blocks.json&:env=production&:team=platform"