Screens

Screens are nodes from the Screens category in the components panel. They display messages to the user and can include images, buttons, or a wait for the next user input.

1. Screen

Screen displays one or more messages, optional images, and a keyboard with buttons. It is a pause point: after the screen is shown, the current scenario execution ends, and the user's next action starts a new execution.

Use Screen when you need to:

show one or more text messages;
add an image to a message;
offer buttons that route the user to different scenario branches;
accept arbitrary user text through a fallback transition.

Settings

Field	Meaning
`Name`	Screen name in the editor
`Order`	Screen order at the model level
`IsOrderingEnabled`	Whether item order is applied; the API default is `false`
`IsKeyboardScreen`	Shows a reply keyboard instead of inline buttons where the channel supports it
`HideKeyboard`	Hides the keyboard; takes priority over `IsKeyboardScreen`
`HideInput`	Hides the input field where the channel supports it
`Messages`	Message list with title, text, image URL, order, delay, and style
`IsQuickReply`	Whether message buttons are sent as quick replies where the channel supports it; the API default is `false`
`Buttons`	Screen buttons edited separately from the main `Screen` form
`ScreenButtonsCols`	Number of button columns when the value is greater than zero
`TargetKey`	Key for the next user input; defaults to `userInput`
`NextAction`	Fallback transition for arbitrary text that does not match a button

DelayAfterMs pauses before this message is sent, in milliseconds. 0 (default) sends immediately. It applies to every message, including the first or the only one, and can be used to imitate typing.

A button has text, order, action, optional URL, Silent mode, ColumnSpan, and visual options. ColumnSpan sets button width in columns, from 1 to 3; null means 1. It takes effect only when ScreenButtonsCols is greater than 1; on one-column screens it is ignored. Values outside 1-3 are normalized by the backend and additionally clamped to the screen column count.

A button with an action creates a separate output to another node. A URL button opens a link instead of continuing through the scenario.

Connections

Input: one standard connector.
Outputs: one output for each button with an action.
Additional output: NextAction as a fallback for arbitrary input.

Showing a Screen does not continue the scenario through NextAction immediately. NextAction is used only after the user's next message, when that message does not match any button.

After the user responds, the backend first checks buttons on the last screen, then global button matches, then pending UserInput, and only then uses Screen.NextAction.

Variables and Templates

Message.Title, Message.Text, and Message.PhotoUrl support #var variables and {{ JS }} expressions. Regular button text and URLs are not processed by the runtime renderer.

When the screen is shown, the backend declares an empty variable:

#node.{screenId}.{TargetKey}

After the user's next message, the actual value is written to that variable. If TargetKey is city, the following values can be used after input:

#node.{screenId}.city
#city
#userInput

Example

Event -> Screen "Choose a plan"
              | Button "Basic" -> Set memory
              | Button "Pro"   -> Set memory
              | NextAction      -> Input

Important Notes

Empty messages without visible text, title, or image are not shown.
If JS in a message fails, Screen is not shown and the scenario execution moves to a failed state.
Screen is not used in a synchronous AI tool because the tool cannot wait for a new human message.
Viber, Viber Business, Widget, and Telegram can render keyboards, styles, and flags differently.

2. Keyboard Screen

Keyboard Screen follows the same rules as Screen: it displays messages, can have buttons, pauses the scenario, and handles the user's next action through buttons or NextAction.

The main difference is that buttons are shown as a reply keyboard where the channel supports it. In the components panel, this node is exposed separately so users can quickly create keyboard screens without manually switching IsKeyboardScreen.

Field	Meaning
`IsKeyboardScreen`	Enables reply keyboard mode
`HideKeyboard`	Hides the keyboard when enabled and takes priority over `IsKeyboardScreen`
`ScreenButtonsCols`	Controls the number of button columns when the value is greater than zero

All other rules for messages, buttons, connections, TargetKey, NextAction, #node.{screenId}.{TargetKey} variables, and #var / {{ JS }} templates are the same as for Screen.

Example:

Event -> Keyboard Screen "Main menu"
              | Button "Catalog" -> Screen
              | Button "Support" -> Agent trigger

The actual keyboard appearance depends on the channel: Viber, Viber Business, Widget, and Telegram can render it differently.

Share phone screen (SharePhoneScreen) is a specialized screen with a native "share contact" button. Use it when the bot needs not just a typed phone number, but a confirmed contact-share event from Telegram or Viber Bot.

Settings

The node inherits the main Screen settings: messages, Name, order, TargetKey, HideInput, and NextAction. One share button is configured separately:

Field	Meaning
`Text`	Main button text
`SubText`	Additional button text, where the channel supports it
`Silent`	Whether to perform the action without a visible message
Visual options	Channel-specific visual button options

Additional regular buttons are not supported: the backend keeps exactly one share button.

Connections

Input: one standard connector.
Output: one NextAction, used as fallback for the next input.

SharePhoneScreen itself does not verify that the number came from native contact share. To enforce this, place Input after it with InputType=Phone and RequireContactShare=true.

Recommended flow:

Share phone screen
  -> Input(InputType=Phone, RequireContactShare=true)
  -> next node

Variables and Templates

Messages, photo URL, and share-button text support #var and {{ JS }}.

After the contact callback, these values are available:

#node.{shareScreenId}.{TargetKey}
#userInput

If TargetKey differs from userInput, the backend also adds #{TargetKey}. The downstream Input creates its own normalized variable, so later logic should prefer the Input result.

Important Notes

Telegram and Viber Bot pass Source=ContactShare.
For Viber Business, the checked callback does not set an equivalent source.
The node is not used in synchronous AI tools because it waits for a new user action.

4. Input

Input (UserInput) receives the latest user input, validates the type, normalizes the value, and routes execution to the success, prompt, or invalid branch.

Settings

Field	Meaning
`InputType`	`Text`, `Integer`, `Decimal`, `Date`, `Boolean`, or `Phone`
`TrimInput`	Trims leading and trailing spaces; defaults to `true`
`RequireContactShare`	For `Phone`, accepts only a native contact-share event
`TargetKey`	Output variable name; defaults to `userInput`
`NextAction`	Valid-input branch
`PromptScreenAction`	Prompt screen when input is missing
`InvalidInputScreenAction`	Error screen when value fails validation

InputKey exists in the library, but the current API always uses userInput and does not expose a way to change it.

Connections

Input: one standard connector.
Next: can lead to any regular node.
Prompt and Invalid: must lead to Screen or Share phone screen.

When input is missing or empty, the node uses PromptScreenAction; if it is missing, it falls back to InvalidInputScreenAction. For non-empty but invalid input, the order is reversed: InvalidInputScreenAction, then fallback to PromptScreenAction.

If no action leads to Screen or Share phone screen, execution ends with an invalid chain state.

Normalization

Type	Rule and result
`Text`	Any non-empty string
`Integer`	`long`, stored in invariant format
`Decimal`	Invariant or server current culture, result stored as invariant
`Date`	Parsed date, result stored as ISO 8601 (`O`)
`Boolean`	`true` / `false`, `1` / `0`, `yes` / `no`, `y` / `n`, `так` / `ні`; result is `True` or `False`
`Phone`	Only `+` and digits after cleanup, 7 to 15 digits

Valid input is stored as:

#node.{id}.{TargetKey}

Example

Input(age)
  ├─ Prompt  -> Screen "Enter your age"
  ├─ Invalid -> Screen "Enter an integer"
  └─ Next    -> Condition "#node.12.age >= 18"

Important Notes

The node reads only input with the exact userInput key, not an arbitrary output from the previous node.
RequireContactShare only has an effect together with InputType=Phone.
Valid input without NextAction produces an invalid chain state.
The node is not used in synchronous AI tools because it can enter a waiting state.

5. Carousel screen

Carousel screen (CarouselScreen) shows a carousel of cards: each card has a title, optional subtitle, image, default action URL, and card buttons. It is supported only for Instagram.

Like Screen, it is a pause point: after the carousel is shown, the scenario waits for the next user action. The user can click a card button or send arbitrary input that goes through the fallback transition.

Settings

Field	Meaning
`Name`	Screen name in the editor
`Order`	Screen order at the model level
`IsOrderingEnabled`	Whether item order is applied
`TargetKey`	Key for the next user input; defaults to `userInput`
`NextAction`	Fallback transition for arbitrary input
`Cards[]`	Carousel cards: `Title`, `Subtitle`, `ImageUrl`, `DefaultActionUrl`, and `Buttons[]`

Each card must have a Title up to 80 characters. A card can have up to 3 buttons. Each card button must have Text and exactly one of:

Action, to route the scenario to another branch;
Url, to open a link.

Connections

Input: one standard connector.
Outputs: one output for each card button with an Action.
Additional output: NextAction as a fallback for arbitrary input.

Regular non-carousel screen buttons are not supported for Carousel screen; use card buttons instead.

Variables and Templates

After the user selects a value or sends fallback input, it is available as:

#node.{screenId}.{TargetKey}

Important Notes

The carousel must contain from 1 to 10 cards.
Each card button with Action creates a separate node output.
Carousel screen is not used in a synchronous AI tool because it waits for a user action.

Screens

1. Screen

Settings

Connections

Variables and Templates

Example

Important Notes

2. Keyboard Screen

3. Share phone screen

Settings

Connections

Variables and Templates

Important Notes

4. Input

Settings

Connections

Normalization

Example

Important Notes

5. Carousel screen

Settings

Connections

Variables and Templates

Important Notes