> For the complete documentation index, see [llms.txt](https://alhena.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://alhena.gitbook.io/docs/features/chat-widget/nudges.md).

# AI Nudges

Nudge visitors at the right moment to start more conversations and drive conversions.

Nudges proactively engage website visitors and encourage them to start a conversation with the chat widget.

They are short prompts that you can configure to appear on any page of your website (home, product, content etc.) based on conditions you set - encouraging timely, relevant interactions with your chat widget.

### How Nudges Work

Nudges are contextual prompts that appear on your webpage to **encourage user interaction**.

**Benefits of Using Nudges**

* **Increased Engagement:** By prompting users at the right time, nudges significantly boost user interaction.
* **Targeted Communication:** Deliver personalized FAQs or context-aware prompts based on user behavior and page context.
* **Enhanced Experience:** With controlled and timely prompts, nudges improve the journey without being intrusive.

***

### Types of Nudges

#### 1. Standard Nudges

* Configured manually for any **page title** or **URL**.
* Triggered based on **urls, time delay**, **scroll depth**, or **custom SDK events**.
* Example: *“*Have any questions? We are here to help!*”*

<figure><img src="https://2864633804-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKZ3bWFAIdLAqpW2uafZ4%2Fuploads%2Ff2kDn7ZWH8R18qLQMJFC%2Fimage.png?alt=media&amp;token=42f2a27e-8827-4070-bed7-5fb6f4c83e3e" alt="" width="563"><figcaption><p>[Standard Nudge]</p></figcaption></figure>

***

#### 2. Product FAQs Nudges as notifications *(New* ✨*)*

Special nudges designed **for product pages**:

* 🔍 **Context-Aware**: Automatically generates FAQs like *“How do I choose the right size?”*.
* 🔔 **Notification Style**: Shown as lightweight chat notifications.
* 🏷️ **Exclusive**: Only available for companies with **products enabled**.
* 📈 **Boost Conversions**: Helps customers resolve doubts instantly, reducing drop-offs.

<figure><img src="https://2864633804-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKZ3bWFAIdLAqpW2uafZ4%2Fuploads%2FQKsDGTbyVBdCNxLPx5Gu%2Fimage.png?alt=media&amp;token=be7ac53e-4a6d-491a-a664-dd55d2e7ed70" alt="" width="563"><figcaption><p>[Product FAQs Nudge as a Notification]</p></figcaption></figure>

***

#### 3. Follow-up Nudge

* Brings back a visitor who chatted and then closed the widget, picking up where they left off.
* See [Follow-up Nudge](#follow-up-nudge) below.

***

### Getting Started 🚀

#### Step 1: Navigate to AI Nudges Settings

Go to:\
`Settings → Integrations → AI Nudges`

You can set up nudges before Website Chat is enabled; they show once the widget is live.

<figure><img src="https://2864633804-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKZ3bWFAIdLAqpW2uafZ4%2Fuploads%2FHrtSZapXtORjek6oSvBO%2Fimage.png?alt=media&amp;token=805c999f-987c-452f-9162-5409db4268bf" alt=""><figcaption><p>[AI Nudges - Configure settings in Alhena Dashboard]</p></figcaption></figure>

***

#### Step 2: Configure Nudge Settings

When creating or editing a nudge, you can define:

* **Nudge Conditions**
  * Match by page title or URL.
  * For *Product FAQs Nudges*, these auto-apply to **all product pages** unless another specific nudge overrides with higher order.
* **Triggers**
  * `Timer`: Display after the visitor has spent a set time on the page (5 seconds to 5 minutes).
  * `Scroll`: Trigger after user scrolls X pixels.
  * `Custom`: Control visibility programmatically with the [Website SDK JavaScript APIs](https://alhena.ai/docs/reference/website-sdk-javascript-apis):
    * `showNudge()`
    * `hideNudge()`
* **Show nudge on**
  * `All devices` (default), `Desktop only`, or `Mobile only`.
* **Nudge Text**
  * `Fixed text`: write the nudge yourself, up to 90 characters.
  * `AI generated nudges`: let AI write it.
* **Nudge Animation Timing**
  * Define how long until the **next nudge** appears (e.g., 5s).
* **When a visitor clicks the nudge**
  * `Get an AI response` (default): the chat opens and the AI answers the nudge right away, so the visitor gets help with one click.
  * `Open the chat only`: the chat opens without sending anything, and the visitor types their own question. Use this when the nudge is an invitation (e.g., *"Need help finding the right size?"*) rather than a question the AI should answer.
* **Preview Your Nudge**
  * Select a **Product URL** to test and preview FAQ nudges directly in the dashboard.

<figure><img src="https://2864633804-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKZ3bWFAIdLAqpW2uafZ4%2Fuploads%2Fgit-blob-ac0a87e96fb5d7bebe76d915bc79a9ffc5c08ed8%2Fnudges-click-action.png?alt=media" alt="Set nudge trigger card with the When a visitor clicks the nudge options: Get an AI response and Open the chat only" width="375"><figcaption><p><em>The click action sits at the bottom of <strong>Set nudge trigger</strong>.</em></p></figcaption></figure>

<figure><img src="https://2864633804-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKZ3bWFAIdLAqpW2uafZ4%2Fuploads%2FRnocg32lv2txuAPRB4Wv%2Fimage.png?alt=media&amp;token=83ec7057-4e20-4671-9646-0c164854d2d8" alt=""><figcaption><p>[When nudge is not created yet - Create nudge button]</p></figcaption></figure>

<figure><img src="https://2864633804-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKZ3bWFAIdLAqpW2uafZ4%2Fuploads%2FPrI7ggrUBenRgq9bv6QG%2Fimage.png?alt=media&amp;token=9932ec59-5d06-4e85-a77b-2a56a168b1d7" alt=""><figcaption><p>[Create nudge configuration settings]</p></figcaption></figure>

<figure><img src="https://2864633804-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKZ3bWFAIdLAqpW2uafZ4%2Fuploads%2FwyqAvXUy0dfyC9dkpg52%2Fimage.png?alt=media&amp;token=8b08441f-8e20-4f00-9745-7bbac2852688" alt=""><figcaption><p>[If company have products - we show Product FAQs as nudges]</p></figcaption></figure>

<figure><img src="https://2864633804-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKZ3bWFAIdLAqpW2uafZ4%2Fuploads%2Fw4AHA8SE0Itqi3nwfsnP%2Fimage.png?alt=media&amp;token=54b4800e-3d52-41eb-9d26-3f74030d2359" alt=""><figcaption><p>[Product FAQs as nudges settings]</p></figcaption></figure>

***

### Nudge Button 🆕

All nudges now include a **Nudge Button** inside the chat widget.

* ✅ Provides a **clear CTA** (e.g., *“Ask us”*).
* 🎯 Makes nudges instantly actionable for the visitor.
* 🛒 For **Product FAQs Nudges**, the button directly connects to product-related support.

<figure><img src="https://2864633804-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKZ3bWFAIdLAqpW2uafZ4%2Fuploads%2FclfCtZd0OUytAsHDWNUK%2Fimage.png?alt=media&amp;token=256ba502-928d-4e9a-90f7-6e618f4e21bf" alt=""><figcaption><p>[Nudge button text]</p></figcaption></figure>

***

### Handling Multiple Nudges

* **First Match Order:** If multiple nudges match, only the first one (based on order) will display.
* **Reordering:** Drag & drop nudges in the dashboard to set priority.

<figure><img src="https://2864633804-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKZ3bWFAIdLAqpW2uafZ4%2Fuploads%2FkuHAruFuFed2Tqv3n5gw%2Fimage.png?alt=media&amp;token=b582b178-d52b-47ab-97f9-c69be0eb8ac8" alt=""><figcaption><p>[Ordering of nudges]</p></figcaption></figure>

***

### Follow-up Nudge

When a visitor chats, closes the widget, and keeps browsing, the follow-up nudge invites them back with a short AI-written line that continues the conversation (for example, *"Still torn between the two sofas?"*).

It shows at most once per close, after the delay you choose, and replaces any page nudge. The AI skips it when a follow-up wouldn't help, such as after a complaint or a resolved question.

#### Set it up

1. Go to `Settings → Integrations → AI Nudges`.
2. Under **Pre-configured nudges**, open the **Follow-up nudge** card:
   * **Show follow-up nudge to website visitors**: turns it on or off.
   * **Nudge the website visitor after**: 30 seconds to 10 minutes after the chat closes (default 2 minutes).
   * **Guidelines for the follow-up message**: what the follow-up should say (e.g., *"Offer help with sizing."*).
3. Click **Save changes**.

***

### Dismissal & Persistence

* Nudges never appear while the chat widget is open.
* After a visitor opens the chat or dismisses a nudge, page nudges stay hidden for 30 minutes. Follow-up nudges aren't affected.
* With the Website SDK, `hideNudge({ dismiss: true })` counts as a dismissal; plain `hideNudge()` only hides the nudge.

***

### Custom Nudge UI (Developer) 🛠️

Prefer to render nudges with your own design instead of Alhena's built-in UI? The [Website SDK](/docs/developer-reference/website-sdk.md) exposes the standard nudge logic so you can build a fully custom launcher and nudge:

* Set `hideDefaultUI: true` to hide the built-in launcher button and nudge.
* Listen for the [`nudge:loaded`](/docs/developer-reference/website-sdk/events.md#nudge-loaded) and [`nudge:triggered`](/docs/developer-reference/website-sdk/events.md#nudge-triggered) events to populate and reveal your own UI.
* Call [`clickNudge()`](/docs/developer-reference/website-sdk/javascript-api.md#clicknudge) to run the same click behavior as the built-in nudge.

Targeting, triggers, and dismissal are still managed here in the dashboard. See the [Custom Launcher & Nudge UI example](/docs/developer-reference/website-sdk/examples/custom-launcher-nudge.md) for complete code.

***

### AI-Generated Nudges 🪄

Instead of static text, enable **AI Nudges** to auto-generate prompts dynamically:

* Provide **guidelines** (tone, style, call-to-action).
* AI will generate unique nudge text based on the **page title and content**.
* You can preview generated nudges by selecting **sample product URLs**.

<figure><img src="https://2864633804-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKZ3bWFAIdLAqpW2uafZ4%2Fuploads%2FoiSndpR31WAOtJCsxDXn%2Fimage.png?alt=media&amp;token=ce1c1bbf-4bec-473c-8f6d-b92a755d1ea5" alt=""><figcaption><p>[AI generated nudges]</p></figcaption></figure>