Workflows in depth

A workflow reacts to an event: a Twitch follow, a member joining your Discord server, a call sent by a third-party service. The engine starts at the trigger and runs the connected nodes one by one, carrying the event's data along. The game integration guides point here for everything about the editor.

One trigger, nodes, data

Every chain starts from a trigger, its entry point. The following nodes are connected by arrows: actions (send a message, call a URL), conditions (pick a branch) and waits. When the event happens, the engine follows the arrows from the trigger and runs each node it reaches.

Data travels with the run. Twitch's “New follower” trigger provides {user_name}, and a Discord “Send a message” placed after it can write {user_name} now follows the channel. Each action adds its own outputs for the next nodes: after a “Webhook / API call”, {webhook_response_status} holds the HTTP code received.

A node can have several outgoing arrows: each branch runs, one after the other. The graph itself never loops. A node reached a second time through a cycle makes the branch fail, and a node where two paths converge runs only once per trigger. To repeat an action, let the called service do the repeating or chain several nodes.

Choosing the trigger

Writing a variable

A variable is written between braces: {user_name}. At run time, the engine replaces it with its value in every text field of a node: message, URL, body, headers. Names depend on the trigger: {user_name} for “New follower” (Twitch), {username} for “Member joined” (Discord), {chatter_name} for “Command received”.

In a node's configuration, the “Available variables (Parent trigger)” panel lists what the trigger and previous nodes provide. Click a variable to insert it instead of retyping it: a typo leaves the name verbatim in the result.

System variables available everywhere: {@now} (ISO date and time), {@date}, {@time} (HH:MM), {@datetime} (DD/MM/YYYY HH:MM), {@timestamp} (Unix timestamp), {@year}, {@month}, {@day}, {@discord_date}, {@discord_relative} and {@uuid}, a different identifier each time it is replaced. Times are the server's, in UTC, except with {@discord_date} and {@discord_relative}: Discord shows the first in each reader's timezone and the second as a relative duration, such as “3 minutes ago”.

What the engine does with your braces

• An unknown key stays written as is: a typo like {usre_name} shows up verbatim in the sent message. Visible braces in a result almost always point to a misspelled name, or one that belongs to another trigger.
• A variable declared by the trigger but missing from the event becomes empty: {user_name} on an anonymous Twitch cheer produces nothing.
• An object or a list is written as JSON, a boolean as true or false.
• No arithmetic or transformation: {bits / 100} stays written as is, and {user_name | upper} gives the name without uppercasing it. Do the math in the service that receives the call, by sending it the raw value.
• To accumulate a value over time, “Set community data” in “Add (counter)” mode adds a number to a stored total.

“Set a variable”

The “Set a variable” action creates a value reusable in the following nodes of the same run. The name is written without braces, using unaccented letters, digits and _: réponse would become rponse. The value can combine other variables. Example: name announcement, value {user_name} just followed the channel, then {announcement} in two messages, one on Discord, the other on Twitch.

Nothing is saved to the database: the variable disappears when the run ends. A value that must survive from one event to the next goes through “Set community data”.

A value made of a single variable holding an object keeps the whole object. With the name reply and the value {webhook_response}, {reply.data.0.title} stays readable further down.

“If (classic)”

“If (classic)” evaluates one or more conditions and opens two outputs: the green handle for TRUE, the red one for FALSE. Several conditions combine with “All conditions (AND)” or “At least one condition (OR)”, in a single list. To mix both, chain two “If (classic)” nodes.

A condition reads a field, an operator and a value. The field can be written with or without braces (bits or {bits}). The value can contain variables: bits “> greater than” {threshold} compares two values of the run. With no condition at all, the TRUE branch is always taken.

“Switch”

The “Switch” replaces a cascade of “If” nodes when there are more than two cases. Each case has its own conditions and handle, and the “Else” branch runs when no case matches. In “Exclusive (first match)” mode, only the first matching case is followed. In “All matching (fan-out)” mode, every matching case is.

Example with Twitch's “Channel points reward”: one case per reward, tested on {reward_title}. Each case leads to a “Set a variable” named effect (vip, sound or challenge), then the three branches join a single “Webhook / API call” to https://example.com/hooks/{effect}. One call node instead of three: adding a reward only means adding a case.

“If network” and “If config”

“If network” compares the network that triggered the run with the one picked in the node (Discord, Twitch, YouTube…), when one chain serves several networks. “If config” reads an answer given when a widget is installed: it is covered in part 6.

Operators and their traps

The editor offers operators based on the variable's type: text, number, yes/no or date. “Incoming webhook” variables, the “Simulated variables” of a “Manual trigger” and the output of “Set a variable” are text for the editor, which therefore doesn't offer numeric comparisons on them.

“Webhook / API call”

This action sends an HTTP request: “Destination URL”, “HTTP method” (POST, GET, PUT, PATCH or DELETE), “Body (JSON)” and “Additional headers (JSON)”. Variables work in the URL, the body and the headers. Only public addresses are accepted: localhost or a private network address makes the step fail.

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

Put every variable in quotes, as above. When the body is valid JSON, LibertyTalk escapes the replaced values: a quote typed by a viewer in {message} doesn't break the request. Values are sent as text ("bits":"500"): the receiving service must convert them if it expects numbers.

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

The response feeds the next nodes: {webhook_response_status} (HTTP code), {webhook_response_ok} (true for a 2xx code), {webhook_response_body} (raw body) and {webhook_response}, the JSON response readable by path, for example {webhook_response.data.0.title}. The “JSON path (optional)” field extracts a single value into {webhook_response_value}. The service has 10 seconds to answer.

“Webhook / API call (background)” sends the same request from a queue: the request doesn't block the engine, and the next nodes resume once the response arrives. Meanwhile, the step shows “Waiting”. It only provides {webhook_response_status}, {webhook_response_body} and {webhook_response_ok}.

The “Sign the request” option adds the X-LibertyTalk-Signature header, computed with a key that belongs to LibertyTalk: it is meant for LibertyTalk tools such as LibertyBroad, and a third-party service cannot verify it. To authenticate your calls to your own service, put a token in the headers instead.

“Wait”

“Wait” pauses the branch for a “Duration” and a “Unit” (seconds, minutes, hours or days). The maximum is 7 days: a longer duration is brought back to 7 days. The wait blocks nothing else: other branches keep going, and the step shows “Waiting” until it resumes. Example: a welcome message, “Wait” 10 minutes, then a second message with the server rules.

If the workflow is edited during a wait, the resume fails instead of running a graph that changed in the meantime.

“Incoming webhook”

The “Incoming webhook” trigger gives your workflow an address. The URL and the secret appear in the “Webhook URL & secret” field after the first save. A third-party service uses them to send a POST with a JSON body, and each accepted call starts a run.

The secret goes in the X-Webhook-Secret header. The “Secret header” field changes that name when the sender imposes its own, for example X-Gitlab-Token for GitLab. Don't put the secret in the URL (?secret=): it would end up in plain text in server logs.

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

LibertyTalk answers 202 when the call is accepted, 401 if the secret or signature is wrong, 404 if the URL is unknown or the workflow is inactive, 400 if a body announced as JSON can't be read, and 429 beyond 120 accepted calls per minute.

For stronger protection, sign the request. Send the Unix timestamp in seconds in X-LT-Timestamp, and in X-LT-Signature the value sha256= followed by the HMAC-SHA256 of {timestamp}.{body}, computed with the secret. LibertyTalk rejects a timestamp more than 5 minutes off and a signature it has already received: an intercepted request can't be replayed.

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)

In the workflow, {payload} holds the whole received body and {payload.score} a single field. The “Variables from the payload” field creates short names: “Target variable” score, “Key in the received payload” score, and {score} becomes usable in nodes and conditions alike. These variables are text for the editor: rather than a score to compare with a threshold, have the service send a value ready for “= equal to”, for example "tier":"gold".

In a widget, each installation gets its own URL and secret, shown on the installation page.

Save, activate, test

Saving stores the graph. For network events, schedules and incoming webhooks to reach the workflow, it must also be active. On activation, LibertyTalk checks the platform rules: a sequence a platform forbids blocks the activation. The Platform rules page details each rule.

The “Manual trigger” runs even when the workflow is inactive: it's the way to test without waiting for a real event. Add it next to the real trigger, fill in its “Simulated variables” (user_name = Test, bits = 500), connect it to the first node of the chain and click “Run now”. The run uses the saved version: “Save and run” avoids testing an outdated one.

Reading the execution console

The “Execution console”, below the editor, shows every run step by step, trigger included. Click its header to open it: runs show up live, and “Load last run” reloads the most recent one. Each step shows its “Input” (values received, variables replaced) and its “Output” (variables produced). For a condition, it shows the compared values and the branch taken.

On each step, the curly-brace “Variables” icon shows every variable available at that point, with secrets masked. That's where you find out why a token came out empty or unchanged: you read the exact name of each key and its value.

Common mistakes

Limits to know

• No loops: a cycle in the graph makes the branch fail, and a chain stops after 100 nodes in a row.
• At most 50 calls per trigger, counting “Webhook / API call”, its background version and “Call a workflow”, sub-workflows included. Beyond that, the step fails.
• More than 5 HTTP calls or sub-workflow launches reachable from one trigger: the editor shows a warning at save time, without blocking.
• “Wait”: 7 days at most.
• “Call a workflow”: at most 5 nested call levels. A workflow can call another “Sub-workflow entry” it contains, but a routine can't call itself again: calling an entry already running in the chain fails.
• “Incoming webhook”: 120 accepted calls per minute. After 3 minutes over the limit within 10 minutes, the URL is disabled until the workflow is saved again.
• No native arithmetic, random draw or cooldown: leave them to the called service.

Sub-workflows

A “Sub-workflow entry” makes a chain callable, like a function. Give it an “Entry name” and declare its “Expected parameters”, each with an optional default value: they become variables further down. One workflow can hold several entries.

The “Call a workflow” action picks the “Routine to call” and fills in the “Parameters passed”. With “Wait for the result” set to Yes, the rest of the chain gets the variables the routine produced, but the routine can contain neither a “Wait” nor a background call. Set to No, the routine runs in the background and nothing comes back.

Example: a “Warn the moderators” routine with a reason parameter, called by the anti-spam workflow and by the reports workflow. The alert message is edited in one place.

From workflow to widget

A widget is a group of nodes that can be installed in a community, with settings specific to each installation. Click “New widget” in the editor controls (or type “widget” in the “+” palette), put the trigger and actions inside the frame, then open its gear icon to give it a name, a category and its variables. A regular zone becomes a widget when you tick “Make this group an installable widget”. The trigger must sit inside the frame: triggers are what set the widget's compatible networks.

In “Widget variables”, declare what the installer must provide, for example service_url and api_token. These names are then used like any variable: {service_url}/events in a “Webhook / API call” URL, {api_token} in its headers. On a node field, the “Ask at install time” box lets the installer choose the value, yours being the default.

“If config” sets a “Question asked at install time”, for example “Enable daily stats?”, with a Yes / No, Text, Number or Choice answer. The TRUE branch runs when the node's comparison holds: each community turns a part of the widget on or off that way.

Installing a widget freezes a copy of it. After a change, the installation page offers an update: webhook URLs and secrets are kept, only settings tied to deleted nodes can be lost.

Clu, the editor assistant

The “Clu” button in the editor opens an assistant. Describe the scenario in one sentence, for example “When someone joins the Discord, send them a welcome message”: Clu asks questions if needed, then proposes nodes that you add with “Apply”. Review them before saving, especially networks and variable names. Clu needs an AI key, saved in Settings, “IA User” or “IA Account” tab.

Going further

• Open workflowsCreate a workflow or edit an existing one.
• Widget catalogueInstall a widget or edit your own.
• Platform rulesBlocked sequences, network by network.