How to design channel-specific welcome experiences

Back to how-to guides Use this pattern when web chat, voice, messaging, or API channels need different startup behavior.

Concept

Channels do not deliver startup content the same way. The runtime sends the ON_START response only on channels that support proactive delivery. On the other channels, ON_START still runs its SET, CALL, and branch DO: actions, but the welcome text is not sent. A channel-specific welcome has two layers:

Conversation welcome. The ON_START response. You write it in ABL and vary it with BRANCHES.
Channel configuration. Launcher message, input placeholder, voice Welcome Message, and voice Greeting Audio. You set these in the channel settings in Studio.

Branch on session.channel. This value holds the channel type of the current session, for example sdk_websocket or korevg. Do not use channel.name or system.channel in an ON_START condition. Those names belong to behavior profiles and escalation routing entries. They do not resolve in ON_START, so the branch never matches.

Welcome delivery	`session.channel` values
`ON_START` response sent	`web_chat`, `sdk_websocket`, `web_debug`, `voice`, `voice_pipeline`, `voice_realtime`, `voice_twilio`, `voice_livekit`, `voice_vxml`, `korevg`, `audiocodes`, `genesys_audio_connector`.
`ON_START` response not sent	`slack`, `whatsapp`, `msteams`, `a365`, `telegram`, `line`, `messenger`, `instagram`, `twilio_sms`, `zendesk`, `email`, `genesys`, `genesys_open_messaging`, `http_async`, `ai4w`, `kore_agent_assist`, `api`, `http`, `workflow`, `ag_ui`, `a2a`.

The payload that reaches each channel also differs. Voice channels keep only PLAIN_TEXT from the VOICE block and drop rich content. web_chat ignores VOICE. sdk_websocket and web_debug accept the full VOICE block and rich content.

Minimal working example

AGENT: Channel_Welcome_Agent
GOAL: "Adapt welcome copy by channel context"

ON_START:
  SET: channel_name = session.channel
  BRANCHES:
    - IF: channel_name == "voice"
      RESPOND: "Thanks for calling. Say billing, orders, or agent."
        VOICE:
          PLAIN_TEXT: "Thanks for calling. Say billing, orders, or agent."
    - ELSE:
      RESPOND: "Welcome. You can type billing, orders, or agent."
        FORMATS:
          markdown: |
            **Welcome.** Type a topic to begin.

FLOW:
  entry_point: ready
  steps:
    - ready

ready:
  REASONING: false
  RESPOND: "Ready."
  THEN: COMPLETE

The ready step stands in for your own flow. The SET line is optional. You can write IF: session.channel == "voice" and skip the variable.

How it works

At session start, the runtime runs ON_START in this order:

Top-level SET and CALL run first. Branch conditions can read the values they set.
A top-level SET_INTERACTION_LANGUAGE or CLEAR_INTERACTION_LANGUAGE runs next, before branch selection.
Branches are checked in order. The first matching branch wins. An ELSE branch has no condition and always matches.
The part of the selected branch DO: list up to its last language directive runs before the welcome renders.
The selected response is sent if the channel supports proactive delivery. Otherwise the runtime records a dsl_on_start_skipped trace.
The rest of the DO: list runs after the welcome.

With a FLOW, a branch-selected welcome is the whole startup turn. The first flow step waits for the first customer message. A top-level RESPOND that no branch replaced is different. The first flow step runs in the same turn, right after the welcome. In the example, channel_name == "voice" matches only the SDK voice channel. Telephony and bridge channels use their own channel types, such as korevg or voice_twilio. The ELSE branch serves all of them.

Common variations

Match every voice channel

Use IN with the voice channel types your project deploys.

AGENT: Voice_Family_Welcome_Agent
GOAL: "Greet callers on any voice channel and chat users in text"

ON_START:
  BRANCHES:
    - IF: session.channel IN ["voice", "voice_pipeline", "voice_realtime", "voice_twilio", "voice_livekit", "voice_vxml", "korevg", "audiocodes", "genesys_audio_connector"]
      RESPOND: "Thanks for calling. Say billing, orders, or agent."
        VOICE:
          PLAIN_TEXT: "Thanks for calling. Say billing, orders, or agent."
    - ELSE:
      RESPOND: "Welcome. You can type billing, orders, or agent."

FLOW:
  entry_point: ready
  steps:
    - ready

ready:
  REASONING: false
  RESPOND: "Ready."
  THEN: COMPLETE

Record the channel choice for later steps

Do not write SET or CALL beside RESPOND in a branch. That is a compile error (E380). Put the action in the branch DO: list. The list allows SET, CALL, HANDOFF, SET_INTERACTION_LANGUAGE, and CLEAR_INTERACTION_LANGUAGE.

AGENT: Channel_Style_Agent
GOAL: "Welcome callers and chat users and record the reply style"

ON_START:
  BRANCHES:
    - IF: session.channel == "voice"
      RESPOND: "Thanks for calling."
      DO:
        - SET: reply_style = "short"
    - ELSE:
      RESPOND: "Welcome."
      DO:
        - SET: reply_style = "detailed"

FLOW:
  entry_point: ready
  steps:
    - ready

ready:
  REASONING: false
  RESPOND: "Reply style: {{reply_style}}."
  THEN: COMPLETE

The DO: list runs after the welcome, unless it sets the interaction language. Language directives and the actions before them run before the welcome, so the welcome can use the new language. A failed CALL stops the rest of the list. The welcome still plays. The compiler reports an ON_START_BRANCH_DO_ACTIVATED warning for each DO: list. The warning confirms that the list runs at session start. A branch DO: list cannot change which branch is selected, because the runtime selects the branch first. To hand off by channel at start, see “How to route users from the welcome experience to the right agent”.

Keep channel configuration separate

AGENT: Launcher_Copy_Agent
GOAL: "Keep channel launcher copy separate from the ABL startup message"

ON_START:
  RESPOND: "Welcome inside the conversation."

FLOW:
  entry_point: ready
  steps:
    - ready

ready:
  REASONING: false
  RESPOND: "Ask a question to continue."
  THEN: COMPLETE

These settings live in the channel configuration, not in ABL:

Web SDK. The theme settings hold the launcher message and the input placeholder.
Voice Welcome Message. The Welcome Message field holds a channel-level greeting. On pipeline voice channels, a non-empty value replaces the ON_START greeting. Clear it to use ON_START. On realtime voice channels, the ON_START greeting wins and the Welcome Message is the last fallback.
Voice Greeting Audio. On pipeline voice channels, the Connect greeting setting binds an audio clip to the channel. On inbound calls, the clip plays instead of the ON_START greeting. Studio shows a notice on the agent when a clip is bound. The runtime keeps the text greeting as a fallback if the clip cannot play.
Pipeline voice interruption. Pipeline voice channels have an Allow caller to interrupt the welcome setting. New channels protect the welcome by default. Channels created earlier stay interruptible until you change the setting. The setting applies only while barge-in is active for the call. A BARGE_IN value written under the RESPOND VOICE block takes priority over the setting.
Realtime voice interruption. OpenAI and Azure OpenAI realtime channels have the same setting in the Welcome interruption section. It is off by default, so the welcome plays to the end. Turn it on only when your voice gateway supports interruptible welcomes. A gateway that does not support them rejects the call. A greeting authored with BARGE_IN: disallow stays protected. Other realtime providers do not have this setting.

Verification

Start a session on each target channel.
Check the transcript against the delivery table. Channels in the “not sent” row show no ON_START welcome.
Open the trace. The dsl_set event for channel_name shows the channel value the runtime read.
Find the dsl_on_start_branch event. It shows the matched branch index.
Find the dsl_respond event with source on_start. It shows the text sent.
On a channel in the “not sent” row, confirm the dsl_on_start_skipped event and that SET and DO: side effects still ran.
On a pipeline voice channel, find the voice_welcome_policy_resolved event. It shows whether the welcome was protected or interruptible, and why.

Production readiness checklist

Test each deployed channel separately, including the voice channel types you use.
Keep launcher copy and conversation copy distinct.
Add an ELSE branch so every other channel gets a valid welcome.
Use PLAIN_TEXT for voice wording. Use short voice greetings.
Provide plain text with every rich content variant.
Check that no voice channel has a Welcome Message or Greeting Audio clip that hides your ON_START greeting.
Confirm async and API channels do not depend on a proactive welcome.

Common mistakes

Mistake	Why it happens	How to avoid it
Treating launcher text as the ABL welcome	Both appear near session start in web chat.	Keep launcher copy in channel configuration and conversation copy in `ON_START`.
Comparing `session.channel` to `"voice"` only	Telephony channels use other channel types.	Use `IN` with every voice channel type you deploy.
Using `channel.name` or `system.channel` in a branch `IF:`	Behavior profiles and routing entries use those names.	Use `session.channel` in `ON_START`.
Writing a plain-language `IF:` condition	The condition looks like routing guidance.	Write an expression such as `session.channel == "voice"`. Plain text never matches.
Writing `SET` or `CALL` beside `RESPOND` in a branch	Branches carry responses.	Use a branch `DO:` list, or run the action at top-level `ON_START`.
Writing one welcome for every channel	Text chat, voice, and async channels have different constraints.	Branch on `session.channel` and test each deployed channel.

Troubleshooting

Symptom	Likely cause	What to check
Welcome appears twice in web chat	The launcher message and the `ON_START` response say the same thing.	Compare the launcher message with the `ON_START` text.
No welcome on Slack, WhatsApp, email, or API	The channel does not receive the `ON_START` response.	Look for `dsl_on_start_skipped` in the trace.
Callers hear a different greeting	A pipeline voice channel has a Welcome Message or a Greeting Audio clip.	Clear the Welcome Message. Turn off or unbind the Connect greeting.
Callers cannot interrupt the welcome	The welcome is protected by the channel setting or by `BARGE_IN: disallow`.	Check the Allow caller to interrupt the welcome setting and the `VOICE` block.
The `ELSE` branch always runs	The channel value does not match the condition.	Check the `dsl_set` trace for the real `session.channel` value.
Markdown or cards do not show on voice	Voice channels keep only `PLAIN_TEXT`.	Add a `VOICE` block with `PLAIN_TEXT`.
Voice greeting is too long	The welcome carries details meant for the next turn.	Shorten the greeting and move details into the first flow step.

Get started

Build

Optimize

Deploy

Analyze

References