Workflows en profondeur

Un workflow réagit à un événement : un follow sur Twitch, un membre qui rejoint votre serveur Discord, un appel envoyé par un service tiers. Le moteur part du déclencheur et exécute les nœuds reliés, un par un, en transportant les données de l'événement. Les guides d'intégration de jeux renvoient ici pour tout ce qui concerne l'éditeur.

Un déclencheur, des nœuds, des données

Chaque chaîne part d'un déclencheur, son point d'entrée. Les nœuds suivants sont reliés par des flèches : des actions (envoyer un message, appeler une URL), des conditions (choisir une branche) et des attentes. Quand l'événement arrive, le moteur suit les flèches depuis le déclencheur et exécute chaque nœud rencontré.

Les données voyagent avec l'exécution. Le déclencheur « Nouveau follower » de Twitch fournit {user_name}, et un « Envoyer un message » Discord placé après peut écrire {user_name} suit maintenant la chaîne. Chaque action ajoute ses propres sorties pour les nœuds suivants : après un « Appel webhook / API », {webhook_response_status} contient le code HTTP reçu.

Un nœud peut avoir plusieurs flèches sortantes : chaque branche s'exécute, l'une après l'autre. Le graphe, lui, ne boucle jamais. Un nœud atteint une seconde fois par un cycle fait échouer la branche, et un nœud vers lequel convergent deux chemins ne s'exécute qu'une fois par déclenchement. Pour répéter une action, confiez la répétition au service appelé ou posez plusieurs nœuds à la suite.

Choisir le déclencheur

Écrire une variable

Une variable s'écrit entre accolades : {user_name}. À l'exécution, le moteur la remplace par sa valeur dans tous les champs texte d'un nœud : message, URL, corps, en-têtes. Les noms dépendent du déclencheur : {user_name} pour « Nouveau follower » (Twitch), {username} pour « Membre rejoint » (Discord), {chatter_name} pour « Commande reçue ».

Dans la configuration d'un nœud, le panneau « Variables disponibles (Trigger parent) » liste ce que fournissent le déclencheur et les nœuds précédents. Cliquez sur une variable pour l'insérer au lieu de la recopier : une faute de frappe laisse le nom en clair dans le résultat.

Variables système disponibles partout : {@now} (date et heure ISO), {@date}, {@time} (HH:MM), {@datetime} (JJ/MM/AAAA HH:MM), {@timestamp} (horodatage Unix), {@year}, {@month}, {@day}, {@discord_date}, {@discord_relative} et {@uuid}, un identifiant différent à chaque remplacement. Les heures sont celles du serveur, en UTC, sauf avec {@discord_date} et {@discord_relative} : Discord affiche la première dans le fuseau de chaque lecteur et la seconde en durée relative, comme « il y a 3 minutes ».

Ce que le moteur fait de vos accolades

• Une clé inconnue reste écrite telle quelle : une faute comme {usre_name} apparaît en clair dans le message envoyé. Des accolades visibles dans un résultat signalent presque toujours un nom mal écrit, ou propre à un autre déclencheur.
• Une variable prévue par le déclencheur mais absente de l'événement devient vide : {user_name} d'un cheer anonyme sur Twitch ne produit rien.
• Un objet ou une liste est écrit en JSON, un booléen en true ou false.
• Aucun calcul ni transformation : {bits / 100} reste écrit tel quel, et {user_name | upper} donne le pseudo sans le passer en majuscules. Faites le calcul dans le service qui reçoit l'appel, en lui envoyant la valeur brute.
• Pour cumuler une valeur dans la durée, « Enregistrer une donnée de communauté » en mode « Ajouter (compteur) » ajoute un nombre à un total conservé.

« Définir une variable »

L'action « Définir une variable » crée une valeur réutilisable dans les nœuds suivants de la même exécution. Le nom s'écrit sans accolades, en lettres sans accent, chiffres et _ : réponse deviendrait rponse. La valeur peut combiner d'autres variables. Exemple : nom annonce, valeur {user_name} vient de suivre la chaîne, puis {annonce} dans deux messages, l'un sur Discord, l'autre sur Twitch.

Rien n'est enregistré en base : la variable disparaît à la fin de l'exécution. Une valeur qui doit survivre d'un événement à l'autre passe par « Enregistrer une donnée de communauté ».

Une valeur faite d'une seule variable qui contient un objet garde l'objet entier. Avec le nom reponse et la valeur {webhook_response}, {reponse.data.0.title} reste lisible plus loin.

« Si (classique) »

« Si (classique) » évalue une ou plusieurs conditions et ouvre deux sorties : la poignée verte pour VRAI, la rouge pour FAUX. Plusieurs conditions se combinent avec « Toutes les conditions (ET) » ou « Au moins une condition (OU) », sur une seule liste. Pour mélanger les deux, enchaînez deux nœuds « Si (classique) ».

Une condition lit un champ, un opérateur et une valeur. Le champ s'écrit avec ou sans accolades (bits ou {bits}). La valeur peut contenir des variables : bits « > supérieur à » {seuil} compare deux valeurs de l'exécution. Sans aucune condition, la branche VRAI est toujours prise.

« Aiguillage (switch) »

L'« Aiguillage (switch) » remplace une cascade de « Si » quand il y a plus de deux cas. Chaque cas a ses conditions et sa poignée, et la branche « Sinon » part quand aucun cas n'est vrai. En mode « Exclusif (1er cas vrai) », seul le premier cas vrai est suivi. En mode « Tous les cas vrais (fan-out) », chaque cas vrai l'est.

Exemple avec « Récompense (points de chaîne) » sur Twitch : un cas par récompense, testé sur {reward_title}. Chaque cas mène à un « Définir une variable » nommé effet (vip, son ou defi), puis les trois branches rejoignent un seul « Appel webhook / API » vers https://example.com/hooks/{effet}. Un seul nœud d'appel au lieu de trois : ajouter une récompense ne fait qu'ajouter un cas.

« Si réseau » et « Si config »

« Si réseau » compare le réseau qui a déclenché l'exécution à celui choisi dans le nœud (Discord, Twitch, YouTube…), quand une même chaîne sert plusieurs réseaux. « Si config » lit une réponse donnée à l'installation d'un widget : il est décrit dans la partie 6.

Les opérateurs et leurs pièges

L'éditeur propose les opérateurs selon le type de la variable : texte, nombre, oui/non ou date. Les variables d'un « Webhook entrant », les « Variables simulées » d'un « Déclenchement manuel » et la sortie de « Définir une variable » sont du texte pour l'éditeur, qui n'y propose donc pas les comparaisons numériques.

« Appel webhook / API »

Cette action envoie une requête HTTP : « URL de destination », « Méthode HTTP » (POST, GET, PUT, PATCH ou DELETE), « Corps (JSON) » et « En-têtes supplémentaires (JSON) ». Les variables fonctionnent dans l'URL, le corps et les en-têtes. Seules les adresses publiques sont acceptées : localhost ou une adresse de réseau privé fait échouer l'étape.

{
  "event": "cheer",
  "user_name": "{user_name}",
  "bits": "{bits}",
  "message": "{message}"
}

Mettez chaque variable entre guillemets, comme ci-dessus. Quand le corps est un JSON valide, LibertyTalk échappe les valeurs remplacées : un guillemet tapé par un viewer dans {message} ne casse pas la requête. Les valeurs partent en texte ("bits":"500") : le service qui reçoit doit les convertir s'il attend des nombres.

{"Authorization": "Bearer {api_token}"}

La réponse alimente les nœuds suivants : {webhook_response_status} (code HTTP), {webhook_response_ok} (vrai pour un code 2xx), {webhook_response_body} (corps brut) et {webhook_response}, la réponse JSON lisible par chemin, par exemple {webhook_response.data.0.title}. Le champ « Chemin JSON (optionnel) » extrait une seule valeur dans {webhook_response_value}. Le service a 10 secondes pour répondre.

« Appel webhook / API (arrière-plan) » envoie la même requête depuis une file d'attente : la requête ne bloque pas le moteur, et les nœuds suivants reprennent une fois la réponse reçue. Entre-temps, l'étape affiche « En attente ». Il ne fournit que {webhook_response_status}, {webhook_response_body} et {webhook_response_ok}.

L'option « Signer la requête » ajoute l'en-tête X-LibertyTalk-Signature, calculé avec une clé propre à LibertyTalk : il sert aux outils LibertyTalk comme LibertyBroad, et un service tiers ne peut pas le vérifier. Pour authentifier vos appels auprès de votre propre service, placez plutôt un jeton dans les en-têtes.

« Attendre »

« Attendre » met la branche en pause pendant une « Durée » et une « Unité » (secondes, minutes, heures ou jours). Le maximum est de 7 jours : une durée plus longue est ramenée à 7 jours. L'attente ne bloque rien d'autre : les autres branches continuent, et l'étape affiche « En attente » jusqu'à la reprise. Exemple : un message de bienvenue, « Attendre » 10 minutes, puis un second message avec les règles du serveur.

Si le workflow est modifié pendant une attente, la reprise échoue au lieu d'exécuter un graphe qui a changé entre-temps.

« Webhook entrant »

Le déclencheur « Webhook entrant » donne une adresse à votre workflow. L'URL et le secret apparaissent dans le champ « URL & secret du webhook » après le premier enregistrement. Un service tiers s'en sert pour envoyer un POST avec un corps JSON, et chaque appel accepté lance une exécution.

Le secret s'envoie dans l'en-tête X-Webhook-Secret. Le champ « Header du secret » change ce nom quand l'émetteur impose le sien, par exemple X-Gitlab-Token pour GitLab. Ne placez pas le secret dans l'URL (?secret=) : il finirait en clair dans les journaux des serveurs.

curl -X POST "<webhook-url>" \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Secret: <webhook-secret>" \
  -d '{"player":"Alex","score":42}'

LibertyTalk répond 202 quand l'appel est accepté, 401 si le secret ou la signature est faux, 404 si l'URL est inconnue ou si le workflow est inactif, 400 si un corps annoncé en JSON est illisible, et 429 au-delà de 120 appels acceptés par minute.

Pour une protection plus forte, signez la requête. Envoyez l'horodatage Unix en secondes dans X-LT-Timestamp, et dans X-LT-Signature la valeur sha256= suivie du HMAC-SHA256 de {horodatage}.{corps}, calculé avec le secret. LibertyTalk refuse un horodatage écarté de plus de 5 minutes et une signature déjà reçue : une requête interceptée ne peut pas être rejouée.

import { createHmac } from 'node:crypto'

const url = process.env.LT_WEBHOOK_URL
const secret = process.env.LT_WEBHOOK_SECRET

const body = JSON.stringify({ player: 'Alex', score: 42 })
const timestamp = Math.floor(Date.now() / 1000).toString()
const signature = createHmac('sha256', secret)
  .update(`${timestamp}.${body}`)
  .digest('hex')

const res = await fetch(url, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-LT-Timestamp': timestamp,
    'X-LT-Signature': `sha256=${signature}`,
  },
  body,
})
console.log(res.status)

Dans le workflow, {payload} contient tout le corps reçu et {payload.score} un champ précis. Le champ « Variables depuis le payload » crée des noms courts : « Variable cible » score, « Clé dans le payload reçu » score, et {score} devient utilisable dans les nœuds comme dans les conditions. Ces variables sont du texte pour l'éditeur : plutôt qu'un score à comparer à un seuil, demandez au service d'envoyer une valeur prête pour « = égal à », par exemple "palier":"or".

Dans un widget, chaque installation reçoit sa propre URL et son propre secret, affichés sur la page de l'installation.

Enregistrer, activer, tester

Enregistrer conserve le graphe. Pour que les événements réseau, la planification et le webhook entrant atteignent le workflow, il doit aussi être actif. À l'activation, LibertyTalk vérifie les règles des plateformes : un enchaînement interdit par une plateforme bloque l'activation. La page Règles des plateformes détaille chaque règle.

Le « Déclenchement manuel » s'exécute même quand le workflow est inactif : c'est la façon de tester sans attendre un vrai événement. Ajoutez-le à côté du vrai déclencheur, remplissez ses « Variables simulées » (user_name = Test, bits = 500), reliez-le au premier nœud de la chaîne et cliquez sur « Exécuter maintenant ». L'exécution utilise la version enregistrée : « Enregistrer et exécuter » évite de tester une version périmée.

Lire la console d'exécution

La « Console d'exécution », sous l'éditeur, affiche chaque exécution étape par étape, déclencheur compris. Cliquez sur son en-tête pour l'ouvrir : les exécutions y arrivent en direct, et « Charger le dernier run » recharge la plus récente. Chaque étape montre son « Entrée » (les valeurs reçues, variables remplacées) et sa « Sortie » (les variables produites). Pour une condition, elle montre les valeurs comparées et la branche prise.

Sur chaque étape, l'icône d'accolades « Variables » affiche toutes les variables disponibles à ce moment, secrets masqués. C'est là que l'on comprend pourquoi un jeton est sorti vide ou tel quel : vous lisez le nom exact de chaque clé et sa valeur.

Erreurs fréquentes

Limites à connaître

• Pas de boucle : un cycle dans le graphe fait échouer la branche, et une chaîne s'arrête au-delà de 100 nœuds à la suite.
• 50 appels au plus par déclenchement, en comptant « Appel webhook / API », sa version en arrière-plan et « Appeler un workflow », sous-workflows compris. Au-delà, l'étape échoue.
• Plus de 5 appels HTTP ou lancements de sous-workflow atteignables depuis un même déclencheur : l'éditeur affiche un avertissement à l'enregistrement, sans bloquer.
• « Attendre » : 7 jours au maximum.
• « Appeler un workflow » : 5 niveaux d'appels imbriqués au plus. Un workflow peut appeler une autre « Entrée de sous-workflow » qu'il contient, mais une routine ne peut pas se rappeler elle-même : l'appel d'une entrée déjà en cours dans la chaîne échoue.
• « Webhook entrant » : 120 appels acceptés par minute. Après 3 minutes en dépassement sur 10 minutes, l'URL est désactivée jusqu'au prochain enregistrement du workflow.
• Pas de calcul, de tirage au hasard ni de délai de récupération (cooldown) natif : confiez-les au service appelé.

Sous-workflows

Une « Entrée de sous-workflow » rend une chaîne appelable, comme une fonction. Donnez-lui un « Nom de l'entrée » et déclarez ses « Paramètres attendus », chacun avec une valeur par défaut facultative : ils deviennent des variables dans la suite. Un même workflow peut contenir plusieurs entrées.

L'action « Appeler un workflow » choisit la « Routine à appeler » et remplit les « Paramètres passés ». Avec « Attendre le résultat » sur Oui, la suite récupère les variables produites par la routine, mais celle-ci ne peut contenir ni « Attendre » ni appel en arrière-plan. Sur Non, la routine part en tâche de fond et rien ne revient.

Exemple : une routine « Prévenir les modérateurs » avec un paramètre raison, appelée par le workflow anti-spam et par celui des signalements. Le message d'alerte se modifie à un seul endroit.

Du workflow au widget

Un widget est un groupe de nœuds installable dans une communauté, avec des réglages propres à chaque installation. Cliquez sur « Nouveau widget » dans les contrôles de l'éditeur (ou tapez « widget » dans la palette « + »), placez le déclencheur et les actions dans le cadre, puis ouvrez sa roue crantée pour lui donner un nom, une catégorie et ses variables. Une zone ordinaire devient un widget en cochant « Faire de ce groupe un widget installable ». Le déclencheur doit être dans le cadre : ce sont les déclencheurs qui fixent les réseaux compatibles du widget.

Dans « Variables du widget », déclarez ce que l'installateur doit fournir, par exemple service_url et api_token. Ces noms s'utilisent ensuite comme toute variable : {service_url}/events dans l'URL d'un « Appel webhook / API », {api_token} dans ses en-têtes. Sur un champ de nœud, la case « Demander à l'installation » laisse l'installateur choisir la valeur, la vôtre servant de défaut.

« Si config » pose une « Question posée à l'installation », par exemple « Activer les stats quotidiennes ? », avec une réponse Oui / Non, Texte, Nombre ou Choix. La branche VRAI part quand la comparaison du nœud est vraie : chaque communauté active ou coupe ainsi une partie du widget.

Installer un widget en fige une copie. Après une modification, la page de l'installation propose une mise à jour : les URL et secrets de webhook sont conservés, seuls les réglages liés à des nœuds supprimés peuvent se perdre.

Clu, l'assistant de l'éditeur

Le bouton « Clu » de l'éditeur ouvre un assistant. Décrivez le scénario en une phrase, par exemple « Quand quelqu'un rejoint le Discord, lui envoyer un message de bienvenue » : Clu pose des questions si besoin, puis propose des nœuds que vous ajoutez avec « Appliquer ». Relisez-les avant d'enregistrer, surtout les réseaux et les noms de variables. Clu demande une clé IA, à enregistrer dans les Paramètres, onglet « IA Utilisateur » ou « IA Compte ».

Pour aller plus loin

• Ouvrir les workflowsCréer un workflow ou reprendre un existant.
• Catalogue des widgetsInstaller un widget ou modifier les vôtres.
• Règles des plateformesLes enchaînements bloqués, réseau par réseau.