How to initialize session variables before the first user turn

Back to how-to guides Use this pattern when flow steps, routing, templates, or tools need known session values before the user says anything.

Concept

ABL gives you several places to seed session values. Pick the one that matches where the value comes from.

Need	Use	When it runs
A fixed default	`MEMORY` `SESSION` with `INITIAL`	When the session is created, before `ON_START`.
A value copied or computed from session context	`ON_START` `SET`	At start, before the welcome.
A value from a tool	`ON_START` `CALL` with `AS`	At start, after `SET`, before the welcome.
A value for one branch only	`SET` in a branch `DO:` list	After the welcome, unless a language directive follows it in the same list.
The reply language	`SET_INTERACTION_LANGUAGE`	After `SET` and `CALL`, before the branches.

ON_START runs these steps in order:

SET assignments.
The top-level CALL.
Interaction language directives.
BRANCHES conditions, which select the welcome.
The matched branch DO: entries up to its last language directive.
The welcome RESPOND.
The remaining branch DO: entries.

ON_START runs once per session, for the entry agent only. A specialist reached by handoff never runs its own ON_START. ON_START also runs when the first user message starts the session, before the runtime processes that message. A reconnect to an initialized session does not run it again. Keep initialization deterministic. Use it for values that exist at start. Collect values from the user with GATHER.

Values you can read at start

Path	Value
`session.channel`	The channel type, such as `web_chat` or `voice`. `digital` when the channel sets none.
`session.sessionId`, `session.userId`, `session.tenantId`, `session.projectId`	Platform identifiers.
`session.sessionPrincipalId`	The caller principal, when the channel supplies one.
`session.customerId`, `session.identityTier`	Identity values, when the channel supplies them.
`session.<name>`	A value the channel passes as caller data. Also readable as `<name>`.
`_metadata.<name>`	Integration metadata that the channel sends at session start.
`session.interaction.current.language`	The resolved language. Also `locale` and `timezone`.

A path with no value resolves to nothing. A template then renders it as empty text. The runtime owns session.languageDetection and sets it after a user message, so it is empty at start.

Minimal working example

AGENT: Session_Init_Agent
GOAL: "Initialize session values before the first flow step"

ON_START:
  SET: retry_count = 0
  SET: channel_name = session.channel
  SET: preferred_language = session.interaction.current.language
  RESPOND: "Welcome."

FLOW:
  entry_point: ask_order
  steps:
    - ask_order
    - show_context

ask_order:
  REASONING: false
  GATHER:
    order_id:
      PROMPT: "What is your order number?"
      TYPE: string
      REQUIRED: true
  THEN: show_context

show_context:
  REASONING: false
  RESPOND: "Order {{order_id}} on channel {{channel_name}}, language {{preferred_language}}, retries {{retry_count}}."
  THEN: COMPLETE

How it works

SET assignments run before RESPOND, in the order you write them.
A numeric or boolean constant keeps its type. 0 stays a number.
A top-level RESPOND is a prelude. The entry flow step still runs at start and asks for the order number.
The flow reads the initialized values from the first step on.
SET runs on every channel. Some channels, such as Slack, WhatsApp, and API, do not deliver the welcome. The values are still set.
You can write several assignments under one SET: line, one per line.
An unresolved path leaves the variable empty.

Common variations

Initialize constants

Quote text constants. An unquoted word that matches a session variable name reads that variable. An unquoted word with no match is stored as text.

AGENT: Metadata_Init_Agent
GOAL: "Copy startup metadata into session variables and use them in the flow"

ON_START:
  SET: campaign_id = "summer-renewal"
  SET: landing_page = "member portal"
  RESPOND: "Welcome from the {{landing_page}}."

FLOW:
  entry_point: ask_topic
  steps:
    - ask_topic
    - confirm

ask_topic:
  REASONING: false
  GATHER:
    topic:
      PROMPT: "What do you need help with?"
      TYPE: string
      REQUIRED: true
  THEN: confirm

confirm:
  REASONING: false
  RESPOND: "Campaign {{campaign_id}} is active. I will help with {{topic}}."
  THEN: COMPLETE

In a real project, copy values such as a campaign marker from trusted caller data, for example SET: campaign_id = session.campaign_id.

Declare a default with INITIAL

Use INITIAL for a fixed default. The runtime writes it when it creates the session. It also fills the variable when an agent activates and the variable is still missing.

AGENT: Session_Defaults_Agent
GOAL: "Seed a retry counter with a declared default and count attempts in the flow"

MEMORY:
  SESSION:
    - retry_count
      TYPE: number
      INITIAL: 0

ON_START:
  SET: channel_name = session.channel
  RESPOND: "Welcome."

FLOW:
  entry_point: ask_order
  steps:
    - ask_order
    - show_attempt

ask_order:
  REASONING: false
  GATHER:
    order_id:
      PROMPT: "What is your order number?"
      TYPE: string
      REQUIRED: true
  THEN: show_attempt

show_attempt:
  REASONING: false
  SET: retry_count = retry_count + 1
  RESPOND: "Order {{order_id}} on channel {{channel_name}}. Attempt {{retry_count}}."
  THEN: COMPLETE

A variable that has only an INITIAL value and no other writer triggers the W801 warning. Write the variable somewhere, as the SET in show_attempt does.

Set a value for one branch

SET in a branch DO: list runs after the welcome, so the welcome cannot read it. The compiler reports ON_START_BRANCH_DO_ACTIVATED as an informational warning. A branch DO: list accepts only SET, CALL, HANDOFF, and the two language directives. The parser drops other entries with a warning.

AGENT: Branch_Init_Agent
GOAL: "Set a reply mode at session start based on the channel"
PERSONA: "Concise assistant"

ON_START:
  BRANCHES:
    - IF: session.channel == "voice"
      RESPOND: "Thanks for calling. How can I help?"
      DO:
        - SET: reply_mode = "voice"
    - ELSE:
      RESPOND: "Welcome. How can I help?"
      DO:
        - SET: reply_mode = "text"

Set the reply language at start

SET_INTERACTION_LANGUAGE accepts a language tag, a value path such as profile.language, or a template such as "{{profile.language}}". It applies in two cases:

The channel has a supported-language list, and the language is on that list.
The project turns on language detection in the Runtime Config settings. The runtime then accepts any valid tag, with no list.

In all other cases, the override is not applied, and the trace shows the reason.

AGENT: Language_Init_Agent
GOAL: "Pin the reply language at session start"
PERSONA: "Concise assistant"

ON_START:
  SET_INTERACTION_LANGUAGE: "fr-FR"
  RESPOND: "Bonjour. Comment puis-je vous aider ?"

A language directive in a branch DO: list moves the entries before it ahead of the welcome. This lets the welcome use a value that the list sets. CLEAR_INTERACTION_LANGUAGE: restores the configured default language.

AGENT: Language_Branch_Agent
GOAL: "Set the reply language before the welcome renders"
PERSONA: "Concise assistant"

ON_START:
  BRANCHES:
    - ELSE:
      DO:
        - SET: spoken_language = "fr-CA"
        - SET_INTERACTION_LANGUAGE: "{{spoken_language}}"
      RESPOND: "Bienvenue {{session.interaction.current.locale}}"

The language must be on the channel’s supported-language list, or the project must turn on language detection. A value that does not resolve to a valid language leaves the language unchanged.

Verification

Start a session. In the trace, find one dsl_set event for each top-level SET, with source: on_start.
Answer the first question. Confirm the final reply shows the initialized values.
Start a session on a second channel. Confirm channel_name changes.
For SET_INTERACTION_LANGUAGE, look for the interaction_language_override_changed event. Check applied and, when it is false, reason.
Reconnect to the same session. Confirm ON_START does not run again.

Production readiness checklist

Initialize only values available before the first user turn.
Quote text constants.
Keep names consistent with later WHEN, PASS, and template references.
Set shared values in the entry agent. Pass them to specialists with PASS.
Avoid writing sensitive values unless the flow needs them.
Trace every startup assignment during validation.
Test each target channel, including channels that do not deliver the welcome.

Common mistakes

Mistake	Why it happens	How to avoid it
Setting a value the runtime does not have yet	Startup runs before the first user turn.	Use `SET` only for constants and existing context.
Leaving a text constant unquoted	A word that matches a variable name reads that variable.	Quote text constants.
Putting initialization in a specialist’s `ON_START`	`ON_START` runs for the entry agent only.	Initialize in the entry agent, or use `INITIAL`.
Reading a branch `DO:` value in the welcome	The `DO:` list runs after the welcome, unless a language directive follows the `SET`.	Use top-level `SET` for values the welcome needs.
Putting `RESPOND` in a branch `DO:` list	The `DO:` list does not run `RESPOND`.	Put the welcome in the branch `RESPOND`.
Using different names later in the flow	Startup names are easy to rename.	Reuse the exact names in templates, `WHEN`, `PASS`, and tools.
Collecting user input with startup `SET`	Initialization and data collection get mixed.	Use `GATHER` for user-provided values.

Troubleshooting

Symptom	Likely cause	What to check
A variable renders as empty text	The path has no value at start.	The path in the table above. Whether the channel sends the caller data.
`preferred_language` is empty	No source set a language.	The agent language, the contact preference, the channel setting, and the project default.
`W801` on a `MEMORY` variable	Only `INITIAL` writes it.	Add a writer, or drop the declaration.
The value is correct in the trace but missing in a specialist	The specialist did not receive it.	The `PASS` list on the `HANDOFF` entry.
The language override is not applied	The `reason` is `VOICE_LANGUAGE_OVERRIDE_UNAVAILABLE` (no supported-language list and no language detection), `VOICE_LANGUAGE_NOT_CONFIGURED` (language not on the list), or `INVALID_INTERACTION_LANGUAGE` (value does not resolve to a tag).	The `interaction_language_override_changed` event and the Runtime Config language settings.
A branch `DO:` entry does nothing	The parser dropped it with `W380` or `W381`, for example a `CALL` with no `AS` or a `RESPOND`.	The compile warnings.
No welcome appears but `SET` ran	The channel does not deliver the `ON_START` response.	The `dsl_on_start_skipped` event.

Get started

Build

Optimize

Deploy

Analyze

References