Workflows Overview

What it is

BotBat Workflows are automated sequences of actions that execute in response to triggers. You build workflows visually using a drag-and-drop Studio editor, connecting trigger nodes to action nodes to create anything from simple message sequences to complex multi-step business processes. Every workflow execution is logged, and you can test workflows in a simulator before activating them.

Workflows sit at the heart of the BotBat automation engine. Rather than requiring code or scripted integrations, the visual Studio editor lets marketing, support, and operations teams design sophisticated automation flows without developer involvement. Each workflow is a directed graph of nodes: it begins with exactly one trigger node and branches into as many action, condition, and subflow nodes as needed. The platform evaluates every node in sequence (or in parallel where branches diverge), passing data through variables from one node to the next.

Workflows are versioned automatically. Each time you save changes, a new version is created so you can roll back to a previous configuration if something goes wrong. Active workflows process events in real time, and the execution engine retries transient failures according to the retry policy you configure at the workflow or node level.

When to use

Use workflows whenever you need the platform to react to an event, schedule, or manual trigger and carry out a series of actions automatically. The following list covers the most common scenarios, but workflows are flexible enough to handle virtually any automation need.

• Automated message sequences: Send a welcome series when a new contact is created, or follow up after a purchase with a satisfaction survey. Sequence multiple messages with delays and conditions so each contact receives a personalized journey.
• Event-driven processes: Trigger actions when a customer replies, a tag is added, a form is submitted, or any custom event fires from your system via webhook. Event triggers are evaluated in under one second, so your responses feel instant to end users.
• Scheduled tasks: Run recurring workflows on a schedule, such as sending weekly reports, expiring inactive conversations, or syncing data with external systems. Schedule triggers accept standard cron expressions as well as friendly presets like "every weekday at 9 AM".
• Multi-step business logic with conditions: Build branching workflows that route contacts through different paths based on attributes, responses, or external data lookups. Condition nodes support rich expressions including comparisons, logical operators, and regular expressions.
• Human-in-the-loop processes: Include approval steps where a team member must review and approve before the workflow continues. See Workflow Approvals for full details on configuring approvers, timeouts, and escalation paths.
• Data enrichment and integration: Use API call nodes to fetch or push data from external CRMs, databases, or services as part of your workflow. Map response fields to workflow variables so downstream nodes can use the enriched data.

Understanding the workflow list page

When you navigate to Workflows in the main sidebar you land on the workflow list page. This page shows every workflow in your workspace with its name, current status (Active, Inactive, or Draft), trigger type, last-edited timestamp, and a quick-actions menu. You can filter and sort the list by any column, and bulk-activate or deactivate multiple workflows at once.

The list page also displays execution statistics for each workflow: the number of runs in the last 24 hours, the success rate, and the average duration. These metrics help you spot workflows that are failing frequently or running slower than expected. Click any workflow row to open it in the Studio editor.

The Studio editor

The Studio editor is the visual canvas where you design your workflow. The canvas occupies the center of the screen. On the left you will find the node palette, and on the right the properties panel appears when you select a node. The toolbar at the top provides Save, Test, Undo/Redo, Zoom, and Activate/Deactivate controls.

You can pan the canvas by clicking and dragging on empty space, and zoom with the scroll wheel or the toolbar buttons. Nodes snap to an invisible grid to keep your layout tidy. Connections between nodes are drawn as curved lines, and you can reroute them by dragging the line's midpoint.

Node palette and node types

The node palette on the left side of the Studio editor organizes available nodes into two categories: Triggers and Actions. Expand a category to see the individual node types, then drag one onto the canvas to add it to your workflow.

The following table summarizes every node type available in the palette.

Category	Node	Description
Trigger	Message Received	Fires when a contact sends a message on any connected channel. Supports channel and keyword filters.
Trigger	Event	Fires when a specific platform event occurs (contact created, tag added, conversation closed, and others).
Trigger	Schedule	Fires on a recurring cron schedule (daily, weekly, or custom expression).
Trigger	Webhook	Fires when an external system sends a POST request to the workflow's unique webhook URL.
Trigger	Manual	Fires when a console user clicks the "Run" button for this workflow.
Action	Send Message	Sends a message to a contact on a specified channel using a template or inline content.
Action	API Call	Makes an HTTP request to an external service and maps the response to workflow variables.
Action	Delay	Pauses execution for a specified duration (minutes, hours, or days).
Action	Condition / Branch	Evaluates an expression and routes execution to different output ports (True, False, Default).
Action	Loop	Iterates over a list variable and executes child nodes for each item.
Action	Human Approval	Pauses the workflow and sends a notification to designated approvers. Resumes on approval or rejection.
Action	Subflow	Executes another workflow as a nested step, passing variables in and receiving outputs back.
Action	Database Query	Reads from or writes to a connected database, returning results as a workflow variable.
Action	Collect Feedback	Prompts the contact for a rating or free-text feedback and stores the response.

Configuring node properties

When you click a node on the canvas, its properties panel opens on the right side of the editor. The panel contains all configurable fields for that node type. Required fields are marked with an asterisk, and each field includes a tooltip explaining its purpose. You can insert dynamic variables into most text fields by typing {{ to open the autocomplete dropdown.

For Send Message nodes the panel includes a channel selector, a template picker (or an inline content editor), and a variable mapping section. For API Call nodes you will see fields for HTTP method, URL, headers, request body, and response variable mapping. Condition nodes present an expression builder with variable suggestions and operator dropdowns.

Variables and dynamic data

Workflows support dynamic variables that resolve at execution time. Variables follow the {{scope.path}} syntax. The three primary scopes are trigger (data from the trigger event), contact (attributes of the contact the workflow is running for), and nodes (outputs from previously executed nodes, referenced by node name). For example, {{trigger.message.text}} resolves to the text of the incoming message, and {{nodes.apiLookup.output.email}} resolves to the email field returned by an API Call node named "apiLookup".

Variables can be used in message content, condition expressions, API call URLs and bodies, delay durations (when driven by a contact attribute), and virtually any text field in a node's properties. The autocomplete dropdown lists all available variables at the current point in the workflow, so you do not need to memorize paths.

Testing with the simulator

Before activating a workflow, use the built-in simulator to verify its behavior. Click "Test" in the Studio toolbar to open the simulator panel. You provide sample trigger data (for example, a mock incoming message or a sample webhook payload) and the simulator executes the workflow step by step on the canvas. Each node highlights green on success or red on failure, and the simulator panel shows the input and output data for every step.

The simulator does not send real messages or make real API calls by default. External calls are mocked, and you can provide custom mock responses for API Call nodes. If you need to test with live external services, enable "Live Mode" in the simulator settings, but use this carefully in production workspaces.

Viewing execution history

The Executions tab on each workflow page shows a log of every workflow run. Each entry displays the execution ID, start time, duration, final status (Completed, Failed, or Waiting), and the trigger data that initiated the run. Click an execution row to expand its full step-by-step trace.

Inside the trace view, every node shows its status, execution duration, input data, and output data. Failed nodes display the error message and stack trace. You can re-run a failed execution from the point of failure (or from the beginning) using the "Retry" button. Execution logs are retained for 30 days by default; you can adjust this in workspace settings.

Common pitfalls

Workflow automation is powerful, but a few recurring mistakes can cause unexpected behavior. Review these pitfalls before building your first workflow, and revisit them when debugging issues.

• No error handling on API calls: If an API Call node fails due to a timeout or server error, the workflow stops at that step unless you add branching logic. Always follow an API Call node with a Condition node that checks the response status code and routes to an error-handling path.
• Infinite loops: A workflow triggered by "Message Received" that itself sends a message can re-trigger endlessly. Prevent this by adding a Condition node that checks whether the sender is the bot, or by applying a cooldown delay that suppresses re-triggering within a time window.
• Oversized workflows: Workflows with 50 or more nodes become difficult to read, maintain, and debug. Break large processes into smaller, focused subflows and compose them using Subflow nodes. This also makes individual pieces reusable across multiple parent workflows.
• Hardcoded values instead of variables: Typing literal values into message content and condition expressions makes workflows brittle. Use contact attributes and trigger data variables so the workflow adapts dynamically to each execution context.
• Skipping the simulator: Activating a workflow without testing it first can result in incorrect messages being sent to real contacts. Always run at least one simulator pass with realistic sample data before toggling the workflow to Active.

tip

Start by sketching your workflow on paper or a whiteboard before building it in Studio. Identify the trigger, the happy path, the error paths, and the exit conditions first. Then translate that design into nodes on the canvas.

• Workflow List
• Studio Editor
• Node Palette
• Node Properties
• Workflow Variables
• Workflow Simulator
• Execution History