Sub-scenarios (child scenarios)

Sub-scenarios allow you to break a complex bot down into separate logical modules. The main scenario calls the sub-scenario; the user completes it and then returns to the main scenario.

When to use

Reusable blocks: contact collection forms, surveys, or payment flows that are called from multiple locations.
Long scenarios that are easier to edit in sections.
Modular bot architecture.

Creating a sub-scenario

Open the scenario switcher (the name of the current scenario in the editor header).
Hover your cursor over the desired main scenario — a + icon (Create sub-scenario) will appear.
Click +. The new sub-scenario will appear in the list, indented beneath the parent scenario.
Click on the sub-scenario to open and configure it in the editor.

Important: A sub-scenario must be published separately by clicking "Publish" within it. Publishing the main scenario does not automatically publish its sub-scenarios.

Quickly copying commands to a sub-scenario

You can select the "Copy to child scenario" action from the canvas context menu. This creates a new child scenario and moves the selected nodes into it.

Only nodes suitable for a sub-scenario are copied: for example, standard commands and frames containing commands.
"Trigger" and "Auto-message" nodes are automatically skipped during this transfer.
The start node in the new sub-scenario is preserved automatically. If one did not exist for some reason, the editor will create it itself.
After copying, the start of the new sub-scenario is automatically linked to the first transferred command, provided a link has not already been set up. - If a frame is selected along with the commands, it is also moved to the sub-scenario together with the commands contained within it.

Calling a sub-scenario from the main scenario

In any command within the main scenario, add a button (inline or standard) with the action 🔀 Call sub-scenario:

Field	Description
Sub-scenario	Select the desired sub-scenario from the list.
Return command	(Optional) The command in this (main) scenario that the bot returns to after exiting the sub-scenario. If not specified, the bot will remain at the start of the sub-scenario.

When the button is pressed, the bot:

Saves the current state.
Loads the sub-scenario and proceeds to its starting command.

Additional options for the "Call Sub-scenario" button

Option	Description
Pass variables	Writes the specified key-value pairs to user variables before entering the sub-scenario. Allows passing context from the main scenario to the sub-scenario (e.g., the ID of a selected product).
Update current message	After starting the sub-scenario, the bot edits the message where the button was pressed instead of sending a new message.

Returning to the main scenario

Add a button with the ↩️ Return to main scenario action within the sub-scenario.

The Return command field is filled in automatically—it is derived from the "Call Sub-scenario" button in the main scenario. In most cases, manual editing is not required.

If a user is inside a sub-scenario and manually sends a command to the bot, the builder automatically exits the sub-scenario, returns the user to the parent scenario, and processes the command there.

When the button is pressed, the bot:

Exits the sub-scenario.
Loads the main scenario and navigates to the specified return command.

Additional options for the "Return to main scenario" button

Option	Description
Pass variables	Writes the specified key-value pairs to user variables before returning. Useful for passing the sub-scenario's result back to the main scenario.
Update current message	After returning, the bot edits the message where the return button was pressed instead of sending a new message.

Important limitations

Nesting depth: 1 level only (a sub-scenario within a sub-scenario is not supported).
Variables: User variables are shared between the main scenario and the child scenario.
Telegram menu commands: The "Show in menu" option is unavailable in a sub-scenario; menu commands belong exclusively to the main scenario. - Publishing: Each sub-scenario is published separately. If a sub-scenario is not published, the trigger button will not work.
Telegram menu upon publishing: Publishing a sub-scenario does not alter or clear the bot's menu commands. The menu is rebuilt only when the main scenario is published.

Example structure

📋 Main scenario
└ 📋 Contact collection    ← sub-scenario
└ 📋 Payment               ← sub-scenario

In the main scenario, the "Leave contact" button triggers the "Contact collection" sub-scenario. After the user fills out the form, the "Done" button in the sub-scenario returns them to the "Thank you" command in the main scenario.

Deleting a Scenario

You can delete a scenario directly from the scenario switcher in the editor header.

Open the scenario switcher.
At the bottom of the drop-down menu (below the "Create new" option), click 🗑 Delete scenario.
Confirm the deletion in the dialog box that appears.

What gets deleted

The scenario itself, including all its nodes, blocks, and connections.
All sub-scenarios of that scenario (if the main scenario is being deleted).
The version history (snapshots) of the scenario and its sub-scenarios.
The states of users who were inside the scenario at the time of deletion.

Published data is deleted along with the draft — this operation is irreversible.

Limitations

If the bot has only one scenario left, the "Delete scenario" button is not displayed; the last remaining scenario cannot be deleted.
When deleting the current scenario, the editor automatically switches:
to the next main scenario in the list — if a main scenario was deleted;
to the parent main scenario — if a sub-scenario was deleted.