Flow Widget Workflow User Guide

This guide covers setup, every workflow node/module, API integration examples, and real-world use cases. Use it to design reliable Hybrid AI Chat Workflows from first draft to production rollout.

Quick Start All Nodes & Modules

1) Quick Start

  1. Open Dashboard → Workflow Builder.
  2. Create a new workflow and name it by channel/use case (for example: Council Service Requests).
  3. Add your core path: Welcome → Data Capture → Routing → Handoff/Outcome.
  4. Configure global settings (CSRF, analytics, timeout).
  5. Preview with test sessions in Workflow Preview.
  6. Activate workflow and publish embed code on your website.

2) Setup & Activation

Prerequisites

  • Admin access (power level suitable for workflow management).
  • Site has valid embed script configured for Flow Widget.
  • At least one active department/operator or AI agent path configured.

Recommended Build Sequence

  1. Start Node: Add a `message` introduction.
  2. Capture Node: Use `form_field` or `api_form` for essential details.
  3. Routing Node: Use `conditional`, `time_of_day`, `queue_gate`, or `language_router`.
  4. Outcome Node: `agent_handoff`, `human_handoff`, `ai_handoff`, or `offline_message`.
  5. Post-Outcome: Add `feedback`, `webhook`, or follow-up content nodes.

3) Workflow Settings

These are the root settings applied to the whole workflow.

Setting Purpose Recommended Value
enable_auto_restart Restarts flow automatically when session completes/ends. true for public support journeys.
session_timeout_minutes Timeout window for inactive sessions. 20–45 minutes (depending on complexity).
require_csrf Enforces CSRF validation on state-changing operations. true in production.
log_analytics Tracks viewed/completed/abandoned steps. true for optimisation and reporting.

4) Complete Node & Module Index

The platform currently supports the following node/module types:

  • message
  • button_group
  • form_field
  • conditional
  • time_of_day
  • queue_gate
  • holiday_override
  • language_router
  • agent_handoff
  • ai_handoff
  • human_handoff
  • offline_message
  • feedback
  • link
  • dept_select
  • set_department
  • youtube_video
  • image_carousel
  • image
  • gif
  • webhook
  • api_form
  • api_conditional

5) Node Configuration Guide

Each entry below includes purpose, key configuration points, and one practical use case.

message - Send a conversational message

Use for: welcome prompts, guidance, and transition messaging.

Key config: sender, content, delay, allow_skip.

Use case: A law firm greets visitors and sets response expectations before intake.

button_group - Collect one-tap choices

Use for: intent capture, department selection, service categories.

Key config: question text, button labels/values, per-button next step.

Use case: Council routes users to bins, housing, roads, or payments in one interaction.

form_field - Ask one validated field

Use for: name, email, reference numbers, policy acknowledgement inputs.

Key config: field_name, field_type, required, validation regex/error, placeholders.

Use case: Hotel asks for booking reference before connecting to concierge.

conditional - Branch by workflow/session conditions

Use for: business rules and custom branching logic.

Key config: condition type and true/false branch targets.

Use case: Finance site branches based on whether user has an existing account.

time_of_day - Route by local office hours

Use for: opening-hours logic, region-aware support routing.

Key config: timezone, day filter, business/custom window, true/false routes.

Use case: Police digital contact uses live handoff in-hours and secure message intake out-of-hours.

queue_gate - Route by queue load

Use for: resilience under high demand.

Key config: comparison mode, threshold, true/false routes.

Use case: E-commerce routes overflow to AI-first path when waiting queue exceeds threshold.

holiday_override - Route by holiday/date rules

Use for: planned closures and special hours.

Key config: match mode, dates/range/days, timezone, branch routes.

Use case: Legal firm switches to callback request path on public holidays.

language_router - Route by browser locale

Use for: multilingual entry flows.

Key config: language source, routes array, default route.

Use case: Travel brand routes English, Spanish, and French users to dedicated paths.

agent_handoff - Generic handoff (AI or human)

Use for: central transfer node where mode is configured per context.

Key config: handoff_type, transfer message, pass captured data.

Use case: Council sends high-confidence FAQs to AI; complex cases to operators.

ai_handoff - Force AI chat path

Use for: AI-first automation journeys.

Key config: AI greeting/context and data pass-through.

Use case: Hotel answers common booking and facilities questions instantly.

human_handoff - Force live operator path

Use for: sensitive or regulated interactions.

Key config: target department, transfer messaging, queue behaviour.

Use case: Finance firm routes complaint escalation directly to accredited staff.

offline_message - Structured out-of-hours capture

Use for: missed-chat prevention when no operators are available.

Key config: require email, confirmation message, captured fields.

Use case: Police non-emergency captures incident details for next-shift review.

feedback - Collect sentiment and quality score

Use for: closure quality loops and service monitoring.

Key config: rating scale, follow-up comments, optional skip controls.

Use case: Legal intake team tracks satisfaction after initial response quality.

link - Present key URLs in-flow

Use for: policy pages, payment links, and guidance resources.

Key config: label, URL, target behaviour, next_step.

Use case: Council shares self-service portal while keeping chat path open.

dept_select - Let user choose department

Use for: transparent routing with online/offline state visibility.

Key config: prompt message, show_offline, offline label.

Use case: Hotel offers Reservations, Existing Booking, and Events teams.

set_department - Silent hard-route to department

Use for: pre-determined routes from campaign/page context.

Key config: department, optional message, delay.

Use case: Pricing page traffic is auto-routed to Sales specialists.

youtube_video, image, gif, image_carousel - Rich media nodes

Use for: visual explainers, product tours, onboarding hints.

Key config: media URL(s), alt text/captions, timing/navigation options.

Use case: SaaS onboarding flow shows short video then routes to setup support.

webhook - Server-side outbound POST integration

Use for: pushing captured data to CRM/case-management/alerting systems.

Key config: URL, auth type, payload mapping, retry policy, status messaging.

Use case: Council sends pothole reports directly into case-management queue.

api_form - Conversational form + external API submit

Use for: creating leads, booking records, tickets, or sign-up profiles.

Key config: fields array, endpoint auth, response template, error/sending messages.

Use case: Hotel creates reservation callback records in PMS/CRM during chat.

api_conditional - API lookup then true/false branch

Use for: eligibility checks, account lookup, ticket existence checks.

Key config: prompt/input, endpoint, response path, operator, expected value, branch steps.

Use case: Finance validates customer reference then routes to verified support path.

6) API Examples

Use these examples as templates for external integrations used by webhook, api_form, and api_conditional.

Example A: Webhook endpoint payload (server receives)

{
  "siteid": "1234567890",
  "workflow_id": 42,
  "jsSessionId": "session_abc123",
  "event": "workflow_completed",
  "data": {
    "visitor_name": "Alex Morgan",
    "visitor_email": "alex@example.com",
    "intent": "housing_enquiry"
  }
}

Example B: API Form endpoint response (JSON)

{
  "success": true,
  "id": "CASE-10045",
  "username": "alex.m",
  "message": "Case created"
}

Template in workflow config: Your case ID is %id%.

Example C: API Conditional response

{
  "data": {
    "isEligible": true,
    "tier": "gold"
  }
}

Config example: response_path: data.isEligible, operator: eq, expected_value: true

cURL test pattern

curl -X POST "https://example.com/api/check-ticket" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_KEY" \
  -d '{"ticket_id":"TICK-12345"}'

7) Industry Use Cases by Section

Councils

Flow: message → button_group (service type) → form_field (address/reference) → webhook (case system) → feedback.

Police 101 (Non-Emergency)

Flow: message disclaimer → api_conditional (risk check) → human_handoff (priority) or offline_message (non-urgent out-of-hours).

Law Firms

Flow: form_field intake → conditional (new/existing client) → set_department (practice area) → human_handoff.

Finance Firms

Flow: api_conditional (client verification) → queue_gate (load handling) → ai_handoff or specialist human_handoff.

Hotels

Flow: language_router → button_group (new/existing booking) → api_form (request capture) → dept_select (reservations/concierge).

Enterprise Support

Flow: message → time_of_day/holiday_override → webhook (ticket create) → ai_handoff with contextual data.

8) Testing & QA Checklist

  • Verify every branch has a valid destination (no dead-end steps).
  • Validate all required fields and regex rules with both valid/invalid input.
  • Test each handoff path during in-hours and out-of-hours windows.
  • Confirm webhook/API auth works and errors are user-safe.
  • Check keyboard navigation, focus visibility, and readable labels.
  • Review analytics logs for step_viewed/step_completed/abandoned.

9) Troubleshooting

Common Issues

  • No active workflow found: ensure one workflow is active for the site.
  • API step fails: recheck endpoint URL, auth headers, timeout, and response JSON.
  • Unexpected routing: verify branch IDs and condition operator/values.
  • Offline path triggers in-hours: confirm timezone and day filters.
  • Poor completion rate: simplify early questions and add clearer choice labels.
Need implementation help? Contact support via our contact form and include your workflow name, site ID, and the step ID where the issue occurs.

Next Steps

After your first production flow, create versions for major intents (sales, support, complaints, booking, and feedback) and optimise each using analytics drop-off points.

Create Account Hybrid Workflows Overview