Build a conditional conversation flow¶
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:
onboardingwith two stages:collect-nameasks for the name and stores it inmemory.name;collect-business-typeasks for the industry and stores it inmemory.business_type. It only opens a chat whenmemory.business_typeis missing.welcome-backwith 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
setupandfallbackconversations as they are. They are outside the start order.
Step 1: Create the two conversations¶
- Open the agent, then on its Profile tab choose Conversation Editor → next to Conversations.
- Type
onboardinginto New conversation… and choose + Conversation. - Type
welcome-backand 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¶
- Select
onboarding. In its Start section, under Starts a chat when:, build the condition: Fieldmemory.business_type, operator is missing. (The editor stores it as{ "missing": ["memory.business_type"] }.) Choose Save. - Check the order. Start order should read 1 of 2 for
onboardingand 2 of 2 forwelcome-back. If not, use Move earlier ononboarding. Leavewelcome-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)¶
- Confirm
memory.business_typeis not set in your memory for this agent. - In the App's Chats tab choose + New chat. The chat opens in
onboardingand asks for your name. - Answer. The bot moves to
collect-business-typeand asks for your industry. - Answer. A notice Done: onboarding appears, and the next reply comes from
welcome-back.
A returning user (business type present)¶
- Confirm
memory.business_typeis now set in your memory for this agent (the previous run stored it). - Choose + New chat. The chat opens straight in
welcome-backand 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
detourinstead oftransitionand 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_typeequalsfounder, 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 builtinsnow()andtoday()too; the editor's field picker only offersmemory.*andagent.*fields.)
Each stays in the same model: JSONLogic, scoped variables, rules with timing and behavior. See Edge conditions.
Related¶
- Edge conditions — when to reach for deterministic conditions vs. LLM routing.
- Conversation routing — how a chat starts, moves, completes and returns.
- Building a chatbot agent — agent setup this how-to assumes is already done.