Skip to content

Build a conditional conversation flow

Portal onlyAdvanced~25 min

Goal: an onboarding that a returning user never sees. A new user is asked for their name and business type, and when onboarding is done the chat moves on to a welcome conversation. A returning user, whose business type is already on file, opens the chat straight in the welcome conversation. You build it in the portal's Conversation Editor, from a fresh agent to a working conditional start.

It uses three things the chat engine does today: a start condition that decides where a chat opens, completion of a conversation when the model says its goal is reached, and a routing rule that sends the chat on when a conversation completes. Each has a reference section if you want the full rules: Starting a chat, Completing a conversation and What the chat engine acts on today.

What this walkthrough does not use

It does not use on_enter rules, which the engine does not build, and it does not skip a stage on entry. To keep a returning user out of a flow, decide it where the chat starts, as below.

For the design rationale of deterministic rules versus leaving the choice to the model, read Edge conditions first.

What we're building

Two ordinary conversations:

  1. onboarding with two stages: collect-name asks for the name and stores it in memory.name; collect-business-type asks for the industry and stores it in memory.business_type. It only opens a chat when memory.business_type is missing.
  2. welcome-back with one stage, greet, that greets the user. It has no start condition, so it always qualifies.

onboarding comes first in the start order, so a chat opens there for a new user and falls through to welcome-back for a returning one. When onboarding completes, a rule hands the chat to welcome-back.

Prerequisites

  • An agent with a chatbot system memory, and a usable AI configuration on the App, the agent or the organization — see Configure your LLM provider.
  • A server that carries the engine changes this page uses: start by condition (server 0.0.1978), completion by goal_reached (0.0.1984) and stage targets and detour return (live on alpha at the time of writing). Ask whoever runs your server whether it carries all three.
  • Org admin role on the agent's organization (the conversation editor saves through admin-gated mutations).
  • Setup and fallback conversations are separate: leave the wizard's setup and fallback conversations as they are. They are outside the start order.

Step 1: Create the two conversations

  1. Open the agent, then on its Profile tab choose Conversation Editor → next to Conversations.
  2. Type onboarding into New conversation… and choose + Conversation.
  3. Type welcome-back and choose + Conversation again.

Step 2: Add the stages

Select onboarding. In Edit conversation under Stages (in order), add collect-name, then collect-business-type. Select each stage and fill in:

collect-name

  • Prompt: Ask for the user's name.
  • Extraction spec: one field, memory.name (string, "the user's name").

collect-business-type

  • Prompt: Ask what kind of business the user is in. When you have the answer, thank them and set goal_reached to true.
  • Extraction spec: memory.business_type (string).

The sentence about goal_reached matters. A conversation completes only when the model sets that flag in its reply, and it does so only if the prompt tells it when. Nothing else completes a conversation.

Select welcome-back, add one stage greet with the prompt Greet the user and ask how you can help.

Step 3: Make onboarding open only when business type is missing

  1. Select onboarding. In its Start section, under Starts a chat when:, build the condition: Field memory.business_type, operator is missing. (The editor stores it as { "missing": ["memory.business_type"] }.) Choose Save.
  2. Check the order. Start order should read 1 of 2 for onboarding and 2 of 2 for welcome-back. If not, use Move earlier on onboarding. Leave welcome-back's condition empty.

A condition here may read only memory.* and agent.* fields, plus the now() and today() clock builtins; the builder offers nothing else, because nothing else has a value when a chat starts.

Step 4: Send the chat on when onboarding completes

Drag from the collect-business-type stage to welcome-back to add a routing rule, then in Edit routing rule set:

  • Label: Hand off to welcome-back when onboarding is done
  • Timing: on_complete
  • Behavior: transition
  • Condition: leave empty.

Choose Save rule. The rule is checked on the turn where the model sets goal_reached, and sends the chat to welcome-back's first stage. A target that does not exist fires nothing and the engine moves on to the next rule, so check the spelling in the rule panel.

Step 5: Publish

Choose Save revision, then Publish it under Revisions. Chats run from the published version, so none of the above reaches users until you publish again after every change. The Start section reminds you with "New chats keep using the published version until you publish again."

Step 6: Test it

Test the flow in a live chat. The agent page has no chat of its own: open an App the agent is installed in and go to its Chats tab.

A new user (business type missing)

  1. Confirm memory.business_type is not set in your memory for this agent.
  2. In the App's Chats tab choose + New chat. The chat opens in onboarding and asks for your name.
  3. Answer. The bot moves to collect-business-type and asks for your industry.
  4. Answer. A notice Done: onboarding appears, and the next reply comes from welcome-back.

A returning user (business type present)

  1. Confirm memory.business_type is now set in your memory for this agent (the previous run stored it).
  2. Choose + New chat. The chat opens straight in welcome-back and greets you. onboarding's start condition did not hold, so it was passed over.

If you close and reopen the first chat, the conversations it finished are listed under Done.

Common issues

Symptom What to check
New chats still open in the wrong conversation. The order or condition is not published yet. Save a revision and publish it.
Every chat opens in welcome-back. The condition reads exists instead of missing, or memory.business_type is set. Also check Start order: onboarding must come first.
The chat won't start and the person sees a message that it can't start right now. A start condition could not be judged and the start was refused (ENTRY_CONDITION_FAILED). The usual cause is a private memory that is locked because the person has not entered their password. The conversation is not skipped.
The condition won't save and mentions the start. It reads a variable that has no value when a chat starts (chat.*, message.data.*). Use memory.* or agent.* (INVALID_ENTRY_CONDITION).
Onboarding ends but the chat never moves to welcome-back. The model never set goal_reached: tell the last stage's prompt when to set it. Also check the rule: Timing must be on_complete, and the target must exist.
The model asked for a stage that isn't there. The chat stayed put and the turn was recorded. The chat shows a neutral notice; the name comes back as rejectedNextStage. Check the stage names.
Editor shows a "raw JSON view" instead of the condition builder. Someone hand-edited the JSONLogic and used an operator outside the curated UI subset (e.g. >, arithmetic, nested operators). Either edit the JSON directly or simplify.
A rule with on_enter does nothing. on_enter is not built; the editor shows it as "not available yet; kept as is".

What you can build from here

  • Return from a side trip. Make the rule's Behavior detour instead of transition and the chat returns to the stage it left when the detour's conversation completes. See Detours and returns.
  • Send the chat to a stage. A rule's target can be a stage of a conversation as well as a conversation. A target that doesn't resolve is skipped.
  • Branch by user type. Two ordinary conversations whose start conditions mirror each other (memory.user_type equals founder, and the opposite) open a different flow for each kind of user.
  • Time-bounded conversations. A rule condition like now() > "2026-12-31T00:00:00Z" can retire a seasonal flow without deleting it. (Start conditions may use the clock builtins now() and today() too; the editor's field picker only offers memory.* and agent.* fields.)

Each stays in the same model: JSONLogic, scoped variables, rules with timing and behavior. See Edge conditions.