> For the complete documentation index, see [llms.txt](https://docs.ebbot.ai/ebbot-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ebbot.ai/ebbot-docs/core-capabilities/chat/conversation-starters.md).

# Conversation Starters

Conversation starters help you proactively engage visitors in the chat widget. They can open the widget, show a message, ask a question, or start a specific scenario when a visitor does something on your website.

Use conversation starters to create timely, helpful experiences such as:

* welcoming visitors on important pages
* offering help after a visitor has been inactive
* guiding visitors who abandon a form
* routing visitors to the right scenario based on availability or page context
* showing an attention seeker without immediately opening the chat

{% hint style="info" %}
Conversation starters only run when they are **published**. Draft conversation starters are saved in Ebbot, but they are not active in the chat widget.
{% endhint %}

## How conversation starters work

A conversation starter has two main parts:

| Part       | What it controls                                                                    |
| ---------- | ----------------------------------------------------------------------------------- |
| **When**   | The visitor behavior, chat state, or availability condition that must happen first. |
| **Action** | What the chat widget should do when the conditions are met.                         |

A conversation starter can also start a scenario. The widget action and the scenario are independent, which means you can use one, the other, or both.

For example, a conversation starter can:

* show an attention seeker only
* open the chat and start a scenario
* start a scenario without showing a visible widget action
* show an attention seeker and start the scenario only after the visitor confirms

## Conditions

A conversation starter runs when all configured conditions are met.

{% hint style="warning" %}
If you add multiple conditions, they are combined with **AND** logic. This means every condition must match before the conversation starter can run.
{% endhint %}

### Visitor and page conditions

| Condition                    | When it runs                                                                          | Good to know                                                                                           |
| ---------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| **User opens chat**          | When the visitor opens the chat widget.                                               | Useful for starting a flow when the visitor chooses to open the chat.                                  |
| **User closes chat**         | When the visitor closes or minimizes the chat widget.                                 | Useful for follow-up prompts or reminders.                                                             |
| **User visits page**         | When the current page URL matches your configured URL rules.                          | Supports URL rules such as contains, equals, starts with, and excludes.                                |
| **User clicks on button**    | When the visitor clicks an element that matches one of your CSS selectors.            | If the selector is invalid, the conversation starter will not run.                                     |
| **User scrolls on page**     | When the visitor scrolls past the configured percentage of the page.                  | For example, `50` means more than halfway down the page.                                               |
| **User is inactive**         | When the visitor has not interacted with the page for the configured time.            | The timer resets when the visitor moves the mouse, touches the screen, clicks, or types. Uses seconds. |
| **User leaves a form**       | When the visitor leaves a matching form field and stays away for the configured time. | This is based on leaving a form field, not submitting the form. Uses seconds.                          |
| **User interacted with bot** | When the chat has been initialized.                                                   | Useful when a conversation starter should only be available after the chat has started.                |

### Agent availability conditions

| Condition                | When it runs                  | Good to know                                   |
| ------------------------ | ----------------------------- | ---------------------------------------------- |
| **Agent is available**   | When agents are available.    | Can be limited to one or more specific skills. |
| **Agent is unavailable** | When no agents are available. | Can be limited to one or more specific skills. |

### Conversation inactivity conditions

Conversation inactivity conditions are tied to both the current conversation status and the latest conversation activity. A new message or other conversation activity can move the timer forward.

| Condition                                     | Conversation status                                                                 | When it runs                                                                                                    | Good to know                                                           |
| --------------------------------------------- | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| **Chat is inactive while user waiting queue** | Visitor is waiting in queue                                                         | When the visitor is waiting in queue and enough time has passed since the latest conversation activity.         | Opening or closing the widget does not reset this timer. Uses seconds. |
| **Chat is inactive in agent conversation**    | Conversation is handled by an agent                                                 | When the conversation is handled by an agent and enough time has passed since the latest conversation activity. | Opening or closing the widget does not reset this timer. Uses seconds. |
| **Chat is inactive**                          | Any active, non-closed conversation except the queue and agent-handled states above | Most commonly used for ongoing bot conversations.                                                               | Opening or closing the widget does not reset this timer. Uses seconds. |

<details>

<summary>How inactivity timers behave</summary>

Inactivity timers use the latest conversation activity together with the current conversation status.

This means:

* opening or closing the widget does **not** reset conversation inactivity timers
* a new message or other conversation activity can move the timer forward
* if the conversation status changes, the timeout is recalculated
* inactivity settings use **seconds**, not minutes

The general **User is inactive** condition works differently. It responds to recent page activity signals, such as mouse movement, touch, clicks, and typing, to decide whether the conversation starter should run. These signals are not saved as an activity history. Because opening or closing the chat involves a click, it can reset the **User is inactive** timer.

</details>

## Actions

Choose what the chat widget should do when the conversation starter runs.

| Action                                       | What it does                                                        | Good to know                                                                                                           |
| -------------------------------------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| **Do nothing**                               | No visible widget action is performed.                              | If a scenario is configured, the scenario can still run.                                                               |
| **Open**                                     | Opens the chat widget if it is not already open.                    | Useful when you want the visitor to enter the chat immediately.                                                        |
| **Show attention seeker with message**       | Shows a short message outside the chat widget.                      | Can include options such as image, auto-hide timing, close button visibility, avatar visibility, and device targeting. |
| **Show attention seeker with question**      | Shows a message with confirm and ignore options.                    | The selected scenario starts only when the visitor confirms.                                                           |
| **Show attention seeker with quick replies** | Shows a message with one or more buttons.                           | Buttons can start a scenario, open a URL, or close the attention seeker.                                               |
| **Show attention seeker with rating**        | Shows a rating prompt.                                              | Ratings can be shown as stars or emoji.                                                                                |
| **Show attention seeker with input**         | Lets the visitor enter a response directly in the attention seeker. | Can include placeholder text, an input scenario, and a follow-up action after the input is completed.                  |

## Attention seeker options

Depending on the selected action, you can customize how the attention seeker looks and behaves.

| Option                           | What it does                                                                     |
| -------------------------------- | -------------------------------------------------------------------------------- |
| **Delay**                        | Waits the configured number of seconds before showing the attention seeker.      |
| **Image**                        | Shows an image together with the attention seeker.                               |
| **Hide close button**            | Removes the close button from the attention seeker.                              |
| **Display on device**            | Controls whether the attention seeker is shown on desktop, mobile, or both.      |
| **Hide attention seeker after**  | Automatically hides the attention seeker after the configured number of seconds. |
| **Hide attention seeker avatar** | Hides the avatar in the attention seeker.                                        |

## Starting scenarios

A conversation starter can start a scenario when it runs.

{% hint style="info" %}
The action and the scenario are separate settings. You can show something in the widget, start a scenario, or do both.
{% endhint %}

Important behavior to know:

* **Show attention seeker with question** does not start the scenario immediately. The scenario starts only when the visitor confirms.
* If the selected scenario is a close-chat scenario, the conversation ends instead of continuing.

## Frequency

Use frequency settings to control how often a conversation starter can run.

| Setting                  | What it means                                                                                     |
| ------------------------ | ------------------------------------------------------------------------------------------------- |
| **Once every page load** | The conversation starter can run again after the visitor reloads the page or visits another page. |
| **Once per session**     | The conversation starter only runs once during the visitor's chat session.                        |

## General settings

| Setting                                                    | What it does                                                                                           |
| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| **Disable all other conversation starters after this one** | Stops any other conversation starters from running during the same session after this one has run.     |
| **Do not run if conversation is active**                   | Prevents the conversation starter from running when there is already an active conversation.           |
| **Do not run if conversation is handled by agent**         | Prevents the conversation starter from running when the conversation is currently handled by an agent. |
| **Publish conversation starter**                           | Makes the conversation starter active in the chat widget.                                              |

## Best practices

{% hint style="success" %}
Start with a small number of conversation starters on your most important pages. This makes it easier to understand which prompts help visitors and which ones may feel interruptive.
{% endhint %}

* Keep messages short and helpful.
* Use delays to avoid interrupting visitors too quickly.
* Use device targeting when a prompt is better suited for desktop or mobile.
* Use **Do not run if conversation is active** for prompts that should only appear before a conversation starts.
* Use **Disable all other conversation starters after this one** for high-priority prompts that should take over the session.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.ebbot.ai/ebbot-docs/core-capabilities/chat/conversation-starters.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.