> ## Documentation Index
> Fetch the complete documentation index at: https://koreai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# How to create a welcome message for a new conversation

Use this pattern when a conversation should open with a clear first message before the user asks for help.

## Concept

A welcome message is the first assistant-owned turn in a session. In ABL, the most direct way to author it is `ON_START`, because `ON_START` runs when the runtime initializes the session, before the first user message is processed.

Use a welcome message to orient the user, name the service, and make the first action obvious. Keep it short. If the same agent also has a `FLOW`, the top-level `ON_START` response behaves like a startup prelude: it can be emitted and the entry flow can continue. If an `ON_START` branch is selected, that branch owns the startup turn and the runtime can pause before the flow continues.

## Minimal working example

```yaml theme={null}
AGENT: Welcome_Message_Agent
GOAL: "Welcome the user and then continue to the first support step"

ON_START:
  RESPOND: "Welcome to Acme Support. I can help with orders, returns, billing, or account questions."

FLOW:
  entry_point: listen
  steps:
    - listen

listen:
  REASONING: false
  RESPOND: "What would you like help with today?"
  THEN: COMPLETE
```

## How it works

The runtime initializes the session, executes `ON_START`, emits the authored response when the channel supports proactive startup delivery, and then enters the flow entry step. The welcome response is also written into assistant history when it is delivered, so later reasoning can see what the user has already been told.

The first flow response should not repeat the welcome. Use it to ask the first useful question or show the first menu.

## Common variations

### Add buttons or rich content

Use actions when the channel can render buttons and you want the user to choose a common path immediately.

```yaml theme={null}
AGENT: Rich_Welcome_Agent
GOAL: "Welcome users with a card and a clear first action"

ON_START:
  RESPOND: "Welcome to Acme Support."
    FORMATS:
      markdown: |
        ## Welcome to Acme Support
        Choose a topic to begin.
    ACTIONS:
      - BUTTON: "Track an order" -> track_order
        VALUE: "track_order"
      - BUTTON: "Start a return" -> start_return
        VALUE: "start_return"

FLOW:
  entry_point: wait_for_choice
  steps:
    - wait_for_choice

wait_for_choice:
  REASONING: false
  RESPOND: "Select an option or describe your question."
  THEN: COMPLETE
```

## Verification

Start a new session and confirm that the welcome appears before the first user message. In traces, look for `dsl_on_start` followed by `dsl_respond` with `source: on_start`. If the flow also runs, the flow response should appear after the welcome.

## Common mistakes

| Mistake                                                           | Why it happens                                                    | How to avoid it                                                                            |
| ----------------------------------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| Repeating the same greeting in `ON_START` and the first flow step | Both are visible during startup on proactive channels.            | Make `ON_START` orient the user and make the first flow step ask the next useful question. |
| Putting long policy text in the welcome                           | The welcome becomes a wall of text before the user asks anything. | Keep startup copy short and move details into the next guided step.                        |
| Assuming every channel shows the proactive welcome                | Some channel contracts suppress startup payloads.                 | Test each channel and keep critical initialization separate from visible copy.             |

## Troubleshooting

If the welcome does not appear, check the channel contract. Some channels suppress proactive startup payloads and allow `ON_START` only for side effects. If the flow response repeats the welcome, move the greeting into `ON_START` and make the flow step ask the next question.

## Production readiness checklist

* Keep the welcome short enough for every channel.
* Include a useful next step, not only a greeting.
* Use rich content only when the target channel supports it.
* Verify traces for `dsl_on_start` and `dsl_respond`.
* Confirm the first flow step does not duplicate the startup message.