Flow Node Playbook (Non-Technical)

start -> message

Use case: Kick off onboarding with a clear welcome and next step.

Limitation: If the first message is too broad, users may respond unpredictably.

Setup tip: Keep the first message short and action oriented.

start -> intent-router

Use case: Route users quickly when one entry point serves many intents.

Limitation: Weak intent labels can misroute first-time users.

Setup tip: Define top intents from real chat logs, not assumptions.

start -> input

Use case: Ask for the first detail immediately when the flow needs one quick answer.

Limitation: Users may abandon the flow if the first question feels too demanding.

Setup tip: Keep the first question simple and explain why you need the answer.

start -> setVariable

Use case: Tag campaign/source metadata before the main journey starts.

Limitation: Wrong initial tags create reporting confusion downstream.

Setup tip: Use one naming convention for all startup tags.

message -> input

Use case: Ask a question and capture the answer in one clean step.

Limitation: Vague prompts produce low-quality input.

Setup tip: Show example formats in the message text.

message -> decision

Use case: Give context first, then ask a binary qualification question.

Limitation: Too much context before the decision can reduce completion.

Setup tip: Limit pre-decision copy to one message block.

message -> media

Use case: Explain what the user will receive before sending a file or image.

Limitation: Users may skip media if context is unclear.

Setup tip: Use a one-line intro that names the benefit of the file.

message -> handover

Use case: Tell the user why they are being transferred before sending them to an agent.

Limitation: Too much pre-handover text can delay urgent escalation.

Setup tip: Keep the handover message short and reassuring.

message -> end

Use case: Close the journey after a final confirmation or completion update.

Limitation: Ending immediately after a message can confuse the user if they still need to act.

Setup tip: End only when the message already contains the complete outcome.

email -> end

Use case: Send the email and then finish the branch cleanly.

Limitation: Ending immediately is only safe when no more user action is needed.

Setup tip: Use this for simple confirmations and internal notifications.

email -> decision

Use case: Check the stored send result and branch on success or failure.

Limitation: Branching should happen after inspecting the stored output, not from the email node itself.

Setup tip: Use the decision node to inspect `{{emailResult.status}}`.

message -> email

Use case: Tell the user a follow-up email is being sent before the email action runs.

Limitation: Too much pre-email text can make the flow feel repetitive.

Setup tip: Keep the pre-email message short and reassuring.

sms -> end

Use case: Send the SMS and finish the branch when no more action is required.

Limitation: Only safe when the SMS already contains the full final outcome.

Setup tip: Use this for simple confirmations and fallback notices.

sms -> decision

Use case: Branch after inspecting the stored SMS result.

Limitation: Branching should happen after the result is written, not from the SMS node itself.

Setup tip: Use `{{smsResult.status}}` in the decision logic.

message -> sms

Use case: Tell the user an SMS will be sent before the SMS action runs.

Limitation: Too much pre-SMS text can make the flow feel repetitive.

Setup tip: Keep the pre-SMS message short and reassuring.

media -> input

Use case: Share reference content and immediately collect confirmation.

Limitation: Users may respond before media is fully loaded on slow networks.

Setup tip: Add a simple confirmation question right after media.

media -> decision

Use case: Send brochure/demo, then ask if user wants next action.

Limitation: Decision quality depends on whether the media was actually viewed.

Setup tip: Mention key points in caption so users can decide quickly.

media -> handover

Use case: Send policy document, then transfer to an agent for complex questions.

Limitation: Agents need context on what media was shared.

Setup tip: Store file name or URL in a variable before handover.

form -> message

Use case: Confirm successful submission and tell the user what happens next.

Limitation: Skipping confirmation can make users unsure whether the form was saved.

Setup tip: Show the saved form name or next action in the message.

form -> api

Use case: Send structured form data to backend systems after capture.

Limitation: Badly named fields can break downstream mapping.

Setup tip: Map the captured object to the API payload explicitly.

form -> decision

Use case: Check whether the form is complete enough for the next step.

Limitation: Decision rules should not duplicate form validation.

Setup tip: Use the decision node only for post-submit branching.

appointment -> message

Use case: Confirm the selected slot and explain the next step.

Limitation: Skipping confirmation can make users unsure whether the booking was saved.

Setup tip: Show the selected date and slot in the message.

appointment -> api

Use case: Send the selected appointment to a backend booking system.

Limitation: Missing booking fields can break the API mapping.

Setup tip: Map the stored booking object explicitly to the API payload.

appointment -> handover

Use case: Escalate high-value or special-case bookings to an agent.

Limitation: Escalating every booking can overwhelm support teams.

Setup tip: Use handover only when manual confirmation is required.

decision -> setVariable

Use case: Record Yes/No outcomes for analytics and later personalization.

Limitation: If branches are mislabeled, saved outcomes become misleading.

Setup tip: Use explicit values like qualified=true or qualified=false.

decision -> api

Use case: Run external checks only for users who pass qualification.

Limitation: Calling API for both branches can increase cost and latency.

Setup tip: Connect API only from the qualifying branch.

decision -> handover

Use case: Escalate immediately when user selects high-risk or urgent option.

Limitation: Over-escalation can overload support operations.

Setup tip: Reserve handover branch for clear escalation criteria.

faq -> fallback

Use case: Recover safely when FAQ confidence is low or no answer is found.

Limitation: Fallback overuse hides knowledge gaps.

Setup tip: Track fallback reasons to improve FAQ coverage weekly.

faq -> handover

Use case: Move to live support when policy exceptions are requested.

Limitation: Without triage notes, agents may re-ask the same question.

Setup tip: Pass detected FAQ topic to agent context.

faq -> ai-sentiment

Use case: Measure frustration after FAQ reply and escalate when needed.

Limitation: Sentiment signals can be noisy for very short replies.

Setup tip: Use sentiment threshold with one additional escalation rule.

api -> condition

Use case: Branch based on API status, eligibility, or returned flags.

Limitation: Condition rules break if response mapping is incomplete.

Setup tip: Map required response keys before writing conditions.

api -> error

Use case: Protect user experience when API fails or times out.

Limitation: Generic error text can increase repeated retries by users.

Setup tip: Give one clear recovery action in error message.

api -> message

Use case: Display API results in plain language after successful fetch.

Limitation: Raw technical values can confuse non-technical users.

Setup tip: Translate values to business-friendly wording.

input -> condition

Use case: Validate entered value format before moving forward.

Limitation: Strict validation can block valid edge-case entries.

Setup tip: Provide error hints and accepted format examples.

input -> ai-extract

Use case: Convert free text into structured fields for downstream logic.

Limitation: Extraction accuracy drops when prompts are unclear.

Setup tip: Ask one focused question before extraction.

input -> retry

Use case: Allow safe re-entry when user sends incomplete information.

Limitation: Too many retries can frustrate users.

Setup tip: Cap retries and route to handover after max attempts.

delay -> message

Use case: Simulate pacing before sending the next informational response.

Limitation: Long delays feel broken in live chat.

Setup tip: Use short delay windows only (for example under 2 seconds).

delay -> api

Use case: Wait briefly before polling data that may take time to update.

Limitation: Fixed delay does not guarantee backend readiness.

Setup tip: Pair with retry/error path, not delay alone.

delay -> timeout

Use case: Provide pacing first, then enforce response deadline.

Limitation: Combined waits can lengthen overall journey time.

Setup tip: Count total wait time from user perspective.

timeout -> fallback

Use case: Offer recovery choices when user does not respond in time.

Limitation: Fallback wording can feel repetitive across multiple timeouts.

Setup tip: Rotate timeout messaging by journey stage.

timeout -> handover

Use case: Escalate stalled high-value or sensitive sessions to agents.

Limitation: Escalating every timeout can overwhelm support teams.

Setup tip: Escalate only after one reminder and clear inactivity threshold.

timeout -> end

Use case: Close inactive low-priority sessions gracefully.

Limitation: Premature closure may lose users who return late.

Setup tip: Include a re-entry instruction in closing message.

retry -> api

Use case: Retry temporary API failures before final error handling.

Limitation: Retrying non-transient errors only increases delay.

Setup tip: Use low retry count and route hard failures to error node.

retry -> input

Use case: Ask user to re-enter a value after validation failure.

Limitation: Repeated re-entry requests can reduce trust.

Setup tip: Explain exactly what was wrong and what is expected.

retry -> error

Use case: Stop retry loop safely when max attempts are exhausted.

Limitation: Poor error messaging can trigger support complaints.

Setup tip: Provide one direct escalation or retry-later option.

setVariable -> switch

Use case: Save segment/intent first, then route to the right journey.

Limitation: Routing fails if variable key is misspelled.

Setup tip: Use predefined variable names in team documentation.

setVariable -> api

Use case: Build API payloads from captured variables.

Limitation: Missing values can cause API validation errors.

Setup tip: Set defaults for optional values before API call.

setVariable -> ai-generate

Use case: Personalize generated responses using saved context fields.

Limitation: Wrong variable mapping can produce awkward responses.

Setup tip: Preview generated text with sample variable sets.

handover -> end

Use case: Close bot flow cleanly after successful transfer.

Limitation: If transfer fails silently, users may think conversation ended.

Setup tip: Confirm transfer status before ending flow.

ai-memory -> handover

Use case: Persist key details before routing to live support.

Limitation: Storing unnecessary data increases governance risk.

Setup tip: Persist only fields agents need immediately.

fallback -> handover

Use case: Escalate when repeated misunderstandings occur.

Limitation: Frequent fallback escalation can spike support queue volume.

Setup tip: Trigger after defined fallback threshold, not on first miss.

fallback -> input

Use case: Recover by asking the user for a clearer phrasing.

Limitation: Users may repeat same unclear input.

Setup tip: Offer example phrases to guide the next response.

fallback -> intent-router

Use case: Retry intent classification after clarification prompt.

Limitation: Repeated misclassification causes user frustration.

Setup tip: Use fallback-specific intent hints before rerouting.

fallback -> handover

Use case: Escalate when bot confidence remains low after retries.

Limitation: Can create unnecessary escalations if threshold is too low.

Setup tip: Escalate only after two low-confidence recovery attempts.

switch -> message

Use case: Route each segment to tailored messaging paths.

Limitation: Missing default branch leaves unknown values unhandled.

Setup tip: Always configure a default branch message.

switch -> api

Use case: Call different backends based on plan or region.

Limitation: Branch sprawl is hard to maintain at scale.

Setup tip: Keep routing logic documented with owner per branch.

switch -> end

Use case: Close low-value or unsupported branches gracefully.

Limitation: Overuse can terminate valid user journeys too early.

Setup tip: End only where business policy requires closure.

condition -> message

Use case: Show validation feedback based on pass/fail outcomes.

Limitation: Too many condition outcomes can create fragmented messaging.

Setup tip: Standardize pass/fail message templates.

condition -> retry

Use case: Retry only when condition indicates recoverable issue.

Limitation: Retrying non-recoverable states wastes user time.

Setup tip: Use condition to separate recoverable vs hard-fail states.

condition -> handover

Use case: Escalate for policy exceptions or high-risk conditions.

Limitation: Too-broad conditions increase manual load.

Setup tip: Define escalation conditions with clear business thresholds.

loop -> input

Use case: Collect missing details in controlled repeated attempts.

Limitation: Users can feel trapped if no visible progress is shown.

Setup tip: Tell users remaining attempts and next escalation step.

loop -> condition

Use case: Check after each attempt whether exit criteria are met.

Limitation: Complex loop exit rules are difficult to debug.

Setup tip: Keep one simple exit condition per loop path.

loop -> handover

Use case: Escalate to human after max retry attempts are exhausted.

Limitation: No handover path can create dead-end loops.

Setup tip: Always pair loops with explicit max-attempt escape path.

message -> end

Use case: Close with confirmation and gratitude once journey completes.

Limitation: If end follows without confirmation, users may be confused.

Setup tip: Send a clear completion message before ending.

handover -> end

Use case: Terminate bot branch after successful human transfer.

Limitation: Premature end before transfer acceptance can drop conversations.

Setup tip: End only after transfer acknowledgement event and a final status message.

timeout -> end

Use case: Auto-close stale sessions with clear re-entry instructions.

Limitation: Users returning late may need to restart from scratch.

Setup tip: Include quick restart path or keyword in final message.

fallback -> end

Use case: Stop safely after a fallback message when no further recovery path exists.

Limitation: Ending too soon can hide a usable recovery path.

Setup tip: Use this only when the fallback message already gives a safe exit or restart instruction.

intent-router -> faq

Use case: Send informational intents directly to self-service answers.

Limitation: Knowledge freshness impacts answer quality.

Setup tip: Map only clear FAQ intents to this branch.

intent-router -> api

Use case: Route transactional intents to backend operations.

Limitation: Intent mistakes can trigger wrong API calls.

Setup tip: Add confirmation step before sensitive API actions.

intent-router -> fallback

Use case: Handle unknown intent safely with guided recovery.

Limitation: Overuse of unknown intent indicates routing model drift.

Setup tip: Review unknown-intent logs weekly and refine intent set.

ai-extract -> setVariable

Use case: Normalize extracted fields into stable variable keys.

Limitation: Field mismatch causes downstream lookup failures.

Setup tip: Map extraction schema keys to your standard variable dictionary.

ai-extract -> condition

Use case: Validate extracted values before operational actions.

Limitation: Overly strict conditions can reject valid natural language.

Setup tip: Allow acceptable ranges and fallback path for uncertain values.

ai-extract -> api

Use case: Use structured extraction output to call backend endpoints.

Limitation: Malformed extracted fields can break payload schema.

Setup tip: Sanitize key fields before API call.

error -> message

Use case: Provide user-friendly explanation after technical failure.

Limitation: If message lacks next steps, users abandon the session.

Setup tip: Always include one clear recovery option.

error -> handover

Use case: Escalate critical failures to support team quickly.

Limitation: Can overwhelm support if used for minor recoverable errors.

Setup tip: Trigger handover only for high-severity failure classes.

error -> end

Use case: Safely terminate flows when no reliable recovery is possible.

Limitation: Hard termination may reduce customer satisfaction.

Setup tip: Use only after offering retry or support alternatives.

ai-sentiment -> handover

Use case: Escalate negative or high-risk conversations to a live agent quickly.

Limitation: False positives may escalate neutral conversations.

Setup tip: Combine sentiment with a second rule such as repeated fallback or keyword detection.

ai-sentiment -> message

Use case: Send empathetic or celebratory replies based on the sentiment label.

Limitation: Tone changes without context can feel unnatural.

Setup tip: Use sentiment-specific templates for consistency.

ai-sentiment -> setVariable

Use case: Store sentiment label and score for reporting and prioritization.

Limitation: Single-message sentiment is not always reliable.

Setup tip: Store the label and score together so later nodes can branch or audit the decision.

ai-memory -> ai-generate

Use case: Generate replies that reference saved user context.

Limitation: Outdated memory can create inaccurate personalization.

Setup tip: Refresh memory fields at key conversation milestones.

ai-memory -> handover

Use case: Pass remembered user facts to agents to reduce repetition.

Limitation: Too much memory data can clutter agent handoff view.

Setup tip: Persist and transfer only support-relevant fields.

ai-memory -> switch

Use case: Route users based on previously stored preferences or status.

Limitation: Stale values can route to wrong branch.

Setup tip: Add periodic memory refresh rules for long-running users.

agent-handoff -> message

Use case: Send a short follow-up after the specialist bot completes.

Limitation: Too many post-handoff messages can make the child bot feel disconnected.

Setup tip: Use the message to summarize the specialist result for the user.

agent-handoff -> handover

Use case: Escalate the conversation to a human if the specialist bot cannot resolve it.

Limitation: Unclear escalation rules can create duplicate transfers.

Setup tip: Pass the handoff metadata and the child bot summary into the handover context.

agent-handoff -> fallback

Use case: Recover safely when the specialist bot is unavailable or exceeds depth limits.

Limitation: Fallback copy should not expose internal bot-routing details.

Setup tip: Tell the user the request is being retried or rerouted in plain language.

ai-generate -> message

Use case: Generate dynamic draft, then present polished business-safe output.

Limitation: Two-step output can add latency if overused.

Setup tip: Use concise prompt templates and small output scope.

ai-generate -> condition

Use case: Check generated content for required keywords or policy flags.

Limitation: Simple checks may miss nuanced compliance issues.

Setup tip: Combine keyword checks with human review for sensitive flows.

ai-generate -> ai-memory

Use case: Store generated summary for future steps or handover notes.

Limitation: Storing verbose generated text can create noise.

Setup tip: Persist short summaries, not full transcripts.

ai-grounded -> message

Use case: Send the grounded answer back to the user in a readable message.

Limitation: Skipping message formatting can make the answer feel raw.

Setup tip: Keep answer text short and user-friendly.

ai-grounded -> condition

Use case: Branch on grounded versus fallback outcome or on the generated answer content.

Limitation: Condition checks should not be overly strict on natural language.

Setup tip: Branch on `groundedResult.grounded` or a dedicated flag.

ai-grounded -> handover

Use case: Escalate fallback cases when the evidence is insufficient.

Limitation: Overusing handover reduces the value of grounded automation.

Setup tip: Include the fallback reason and evidence summary in handover context.

form -> api

Use case: Push captured form data to CRM, LMS, or ticketing systems.

Limitation: Bad field mapping can break API payload validation.

Setup tip: Validate required form keys before API call.

form -> condition

Use case: Branch based on captured values like budget, urgency, or eligibility.

Limitation: Inconsistent field values can misroute users.

Setup tip: Normalize values before condition checks.

form -> handover

Use case: Route complete context to a human specialist.

Limitation: Missing fields reduce agent efficiency.

Setup tip: Ensure mandatory fields are validated before handover.

appointment -> message

Use case: Confirm selected slot to the customer immediately.

Limitation: Without confirmation, users may doubt booking success.

Setup tip: Include slot label and next-step expectation.

appointment -> api

Use case: Persist booking in external scheduling systems.

Limitation: Failed sync can create double-booking risks.

Setup tip: Add error fallback and retry strategy.

appointment -> handover

Use case: Escalate custom scheduling requests to staff.

Limitation: Manual follow-up may increase response time.

Setup tip: Pass selected slot and notes in handover context.

payment -> condition

Use case: Route by paid or failed status for next actions.

Limitation: Unclear status mapping can misroute customers.

Setup tip: Use explicit status values with tested branch rules.

payment -> api

Use case: Update backend payment state using captured reference.

Limitation: Missing reference can block reconciliation.

Setup tip: Enforce reference capture in paid path.

payment -> handover

Use case: Escalate disputed or failed payments to support.

Limitation: High false escalation increases support volume.

Setup tip: Escalate only after retry or policy check.

document-intake -> message

Use case: Acknowledge successful document submission.

Limitation: No confirmation can cause user uncertainty.

Setup tip: Show count of accepted documents in response.

document-intake -> api

Use case: Forward document metadata to verification services.

Limitation: Missing metadata may break verification workflow.

Setup tip: Validate and sanitize payload before API call.

document-intake -> handover

Use case: Send edge-case document reviews to human teams.

Limitation: Manual checks can delay turnaround time.

Setup tip: Include document summary in handover context.

script -> condition

Use case: Branch based on computed result flags.

Limitation: Incorrect script output breaks routing logic.

Setup tip: Define and test expected output schema.

script -> setVariable

Use case: Persist selected computed values for reporting.

Limitation: Overwriting key variables can affect later branches.

Setup tip: Use clear output variable naming conventions.

script -> api

Use case: Send transformed data to downstream systems.

Limitation: Schema mismatch can trigger API rejection.

Setup tip: Validate transformed payload before dispatch.

script -> end

Use case: Generate a value and then finish the branch cleanly.

Limitation: Ending immediately is only safe when no more action is needed.

Setup tip: Use this for simple utility scripts that only prepare data.

connector -> message

Use case: Communicate operation success/failure clearly to users.

Limitation: Silent connector failures reduce trust.

Setup tip: Include fallback messaging for failure branches.

connector -> switch

Use case: Route by connector response attributes.

Limitation: Missing mapped fields cause ambiguous routing.

Setup tip: Define default branch for unmapped outcomes.

connector -> retry

Use case: Handle transient external system failures safely.

Limitation: Excessive retries can increase latency and cost.

Setup tip: Use bounded retry with escalation path.

event-trigger -> switch

Use case: Route multiple event families to specialized flows.

Limitation: Complex routing can become hard to maintain.

Setup tip: Document event taxonomy and ownership.

event-trigger -> message

Use case: Notify customers on event-based outcomes.

Limitation: Poorly timed notifications can feel noisy.

Setup tip: Throttle or gate notifications by policy.

event-trigger -> api

Use case: Execute downstream operations when event matches.

Limitation: Wrong event mapping can trigger unintended actions.

Setup tip: Use strict validation in critical operations.

auth-consent -> api

Use case: Proceed with sensitive backend action only after consent.

Limitation: Skipping deny-path handling creates compliance risk.

Setup tip: Branch strictly on accepted/denied outcome.

auth-consent -> handover

Use case: Escalate failed OTP or denied consent cases.

Limitation: Frequent escalation may indicate UX clarity issues.

Setup tip: Track deny reasons for prompt and policy tuning.

auth-consent -> message

Use case: Confirm consent capture with audit-friendly wording.

Limitation: Missing confirmation can create customer confusion.

Setup tip: Include timestamp-aware acknowledgement message.