Create a Workflow

What it is

Creating a workflow in BotBat involves selecting a trigger, adding and configuring action nodes in the visual Studio editor, wiring them together, using variables for dynamic data, testing with the simulator, and activating the workflow. The Studio editor provides a drag-and-drop canvas where you visually design the entire automation flow.

The workflow creation process is designed to be accessible to non-technical users while still offering the depth that advanced users need. Every workflow starts from a dialog where you name it and choose a trigger type, then you are taken directly into the Studio editor canvas. From there, you build your automation by dragging nodes from the palette, connecting them with lines, and filling in each node's configuration in the properties panel. The platform validates your workflow as you build, highlighting missing required fields and unreachable nodes in real time.

Workflows support branching, looping, subflow composition, and human approval steps. This means a single workflow can handle complex business logic such as "if the contact is in segment A, send offer X; otherwise check their purchase history via API, and if they spent more than $500 this quarter, route to a VIP path with manager approval before sending a personalized discount." All of this is expressed visually without writing code.

When to use

• Automating a repetitive process: When you find yourself manually performing the same sequence of actions for contacts repeatedly, build a workflow to handle it. Common examples include onboarding sequences, appointment reminders, and post-purchase follow-ups.
• Responding to events in real time: Create a workflow triggered by incoming messages, contact events, or webhooks to take immediate action without manual intervention. Event-triggered workflows execute within seconds of the event occurring.
• Building multi-step campaigns: When a single campaign send is not enough and you need a sequence with delays, conditions, and follow-ups, a workflow gives you full control over timing and branching logic.
• Connecting BotBat to external systems: Use API Call nodes within a workflow to push data to your CRM, pull information from a database, or notify a Slack channel. The response data can be mapped to workflow variables and used in subsequent nodes.

Step 1: Open the workflow creator

Navigate to Workflows in the main sidebar and click the "Create Workflow" button. A dialog appears where you enter the workflow name and an optional description. The name should be descriptive enough that your team can identify the workflow's purpose at a glance, for example "Post-Purchase Satisfaction Survey" or "New Lead Qualification Flow".

After you confirm the dialog, you are taken directly into the Studio editor with an empty canvas. The trigger node is automatically placed on the canvas as the starting point. If you chose a trigger type in the dialog, it is pre-selected; otherwise you can configure it from the properties panel.

Step 2: Choose and configure a trigger

The first node on the canvas is always a trigger. Click the trigger node to open its configuration panel on the right side. Select the trigger type and configure its filters. The trigger type determines what event starts the workflow.

The following table describes each available trigger type and its configuration options.

Trigger type	Fires when	Key configuration options
Message Received	A contact sends a message on any connected channel	Channel filter (limit to specific channels), keyword patterns (regex or exact match), contact attribute filters
Event	A specific platform event occurs	Event type selector (contact created, tag added, conversation closed, custom events), optional attribute conditions
Schedule	A recurring time interval is reached	Cron expression input or friendly presets (daily at 9 AM, every Monday, first of the month), timezone selector
Webhook	An external system sends a POST request to the workflow's unique URL	Auto-generated webhook URL (copy to clipboard), optional payload schema validation, authentication token
Manual	A console user clicks "Run" for this workflow	Optional input form definition (fields the user must fill in before the workflow starts)

Choose your filters carefully. A "Message Received" trigger with no filters fires on every incoming message across all channels, which can generate a very high volume of executions. Add channel filters, keyword patterns, or contact attribute conditions to narrow the scope to only the messages you intend to handle.

Step 3: Add and connect nodes on the canvas

Drag action nodes from the left palette onto the canvas. Each node represents a single step in your workflow. Position nodes in the order they should execute, then connect them by clicking a node's output port and dragging to the next node's input port.

Condition nodes have multiple output ports labeled "True", "False", and optionally "Default". Connect each output to the appropriate downstream node. You can also create parallel branches by connecting a single output port to multiple nodes; the platform will execute those branches concurrently.

When the canvas becomes crowded, use the minimap in the bottom-right corner to navigate. You can also collapse groups of nodes into a "Group" container to keep the layout organized. Groups are purely visual and do not affect execution order.

Step 4: Configure each node's properties

Click any node on the canvas to open its properties panel on the right side. Required fields are marked with an asterisk. The panel contents vary by node type.

Node type	Key properties
Send Message	Channel selector, template picker or inline content editor, variable mapping for personalization
API Call	HTTP method (GET, POST, PUT, DELETE), URL, headers (key-value pairs), request body (JSON editor), response variable mapping, timeout and retry settings
Delay	Duration value and unit (minutes, hours, days), or a dynamic expression referencing a variable
Condition / Branch	Expression builder with variable selectors and comparison operators; supports AND/OR grouping
Loop	List variable selector, iterator variable name, maximum iterations limit
Human Approval	Approver selector (user, team, or role), timeout duration, timeout action (auto-approve, auto-reject, escalate), notification message
Subflow	Workflow selector, input variable mapping, output variable mapping
Database Query	Query type (SELECT, INSERT, UPDATE), connection selector, query template with variable placeholders
Collect Feedback	Feedback type (star rating, NPS, free text), prompt message, storage variable

Fill in every required field before moving to the next node. The platform highlights incomplete nodes with an orange warning badge so you can easily spot what still needs attention.

Step 5: Use variables for dynamic data

Insert variables anywhere in node fields using the {{variable}} syntax. When you type {{ in any text field, an autocomplete dropdown appears listing all available variables at that point in the workflow.

Variables are organized into three scopes. The trigger scope contains data from the trigger event, such as {{trigger.message.text}} or {{trigger.webhook.payload.orderId}}. The contact scope contains attributes of the contact the workflow is running for, such as {{contact.name}}, {{contact.email}}, and {{contact.tags}}. The nodes scope contains outputs from previously executed nodes, referenced by node name, such as {{nodes.apiLookup.output.status}} or {{nodes.dbQuery.output.rows[0].balance}}.

You can also use built-in utility variables like {{now}} (current timestamp), {{randomId}} (a generated UUID), and {{env.WORKSPACE_ID}} (workspace identifier). These are useful for generating unique reference codes, setting timestamps in API requests, or routing logic based on the workspace.

Step 6: Test with the simulator

Click "Test" in the Studio toolbar to open the simulator panel. Provide sample trigger data that matches your trigger type (for example, a mock incoming message JSON for a Message Received trigger). The simulator executes each node in sequence, highlighting nodes green on success or red on failure.

The simulator panel shows the input and output data for every step, making it easy to trace how data flows through the workflow. External API calls are mocked by default to prevent side effects during testing. You can provide custom mock responses for API Call nodes, or enable "Live Mode" to make real external calls if needed. Always test with at least two or three different sample inputs to cover the main branches of your workflow.

Step 7: Review execution history and activate

After running simulator tests, check the Executions tab to see the full trace of each test run. Every step shows its status, duration, input data, and output data. Failed steps include the error message and a link to the relevant node on the canvas.

When you are satisfied that the workflow behaves correctly, toggle the workflow status to "Active" using the button in the top toolbar. The workflow will now execute automatically whenever its trigger condition is met. To stop the workflow, toggle it back to "Inactive". In-progress executions will complete, but no new executions will start. You can also set an expiration date on a workflow so it automatically deactivates after a campaign ends.

note

For detailed guidance on adding approval steps to your workflows, see Workflow Approvals.

Common pitfalls

These are the most frequent mistakes teams encounter when creating workflows. Review them before building your first workflow, and revisit them when troubleshooting unexpected behavior.

• Forgetting to save before testing: The simulator runs the last saved version of the workflow. If you make changes but do not click Save, the test will execute the old version and the results will not reflect your recent edits. Get into the habit of saving after every significant change.
• Missing variable mappings: If a node references a variable that does not exist (for example, a typo like {{contact.naem}} instead of {{contact.name}}), the variable resolves to an empty string at runtime. Use the autocomplete dropdown to select variables rather than typing paths manually.
• Trigger filters too broad: A "Message Received" trigger with no filters fires on every single incoming message across all channels. This can generate thousands of executions per hour in a busy workspace. Always add channel, keyword, or contact-attribute filters to narrow the scope.
• Not handling all condition branches: If a Condition node evaluates to neither True nor False (for example, when the variable is null or undefined), the workflow may stall at that node. Always connect a Default output port as a fallback path.
• Ignoring execution failures: Check the Executions tab regularly. Failed executions display the exact step and error message. Address failures promptly to avoid silent data loss or contacts stuck mid-workflow.

tip

Use the "Subflow" node to keep your workflows modular. Build reusable sub-workflows for common patterns like "send message and wait for reply" or "look up contact in CRM". Call them from multiple parent workflows to avoid duplicating logic.

• Create Workflow Dialog
• Trigger Configuration
• Studio Canvas
• Node Properties
• Workflow Variables
• Workflow Simulator
• Execution History
• Activate Workflow