Widget Triggers

Triggers let you automatically engage users based on their behavior — like opening the chat after they’ve been on the page for a while, showing a form when they scroll down, or displaying a message when they’re about to leave.

Creating Triggers

In the Dashboard

Go to Agents → select your agent
Click Triggers in the sidebar
Click Add Trigger
Configure the trigger type, conditions, and action

Via API

See the Triggers API for programmatic trigger management.

Trigger Types

Time on Page

Fire after the user has been on the page for a specified duration.

Setting	Description
Seconds	Time to wait before triggering

Use cases:

Show help message after 30 seconds
Offer assistance to browsing users
Prompt for newsletter signup

// Configuration
{
  triggerType: "time_on_page",
  conditions: { timeOnPage: 30 }  // 30 seconds
}

Scroll Depth

Fire when the user scrolls past a certain percentage of the page.

Setting	Description
Percentage	0-100% scroll depth threshold

Use cases:

Show CTA after reading content
Capture leads who engage with content
Offer demos on product pages

// Configuration
{
  triggerType: "scroll_depth",
  conditions: { scrollDepth: 50 }  // 50% scroll
}

Exit Intent

Fire when the user moves their mouse toward the browser’s close/back button (desktop only). Use cases:

Prevent cart abandonment
Offer discounts before leaving
Capture feedback

// Configuration
{
  triggerType: "exit_intent",
  conditions: {}
}

Exit intent only works on desktop browsers. Mobile users won’t trigger this.

Page View

Fire when the user visits a specific page or pages matching a pattern.

Setting	Description
Page	URL path or glob pattern

Pattern examples:

Pattern	Matches
`/pricing`	Exact `/pricing` path
`/pricing/*`	`/pricing/starter`, `/pricing/pro`
`/blog/**`	Any path under `/blog/`
`/docs/**/api`	`/docs/v1/api`, `/docs/guides/api`

// Configuration
{
  triggerType: "page_view",
  conditions: { page: "/pricing/*" }
}

Custom Event

Fire when your code triggers a custom event.

Setting	Description
Event	Event name to listen for
Event Data	Optional: conditions on event payload

// Configuration
{
  triggerType: "custom_event",
  conditions: {
    event: "cart_abandoned",
    eventData: { cartValue: { "$gt": 100 } }
  }
}

Fire from your code:

ansa.trigger("cart_abandoned", { cartValue: 150 });

Actions

When a trigger fires, it performs one of these actions:

Open Chat

Opens the chat widget, optionally with a pre-filled message.

Setting	Description
Message	Optional message to pre-fill in input

{
  actionType: "open_chat",
  actionConfig: {
    message: "I have a question about pricing"
  }
}

Show Form

Displays a form tool in the chat widget.

Setting	Description
Tool ID	The form tool to display

{
  actionType: "show_form",
  actionConfig: {
    toolId: "tool_abc123"
  }
}

Show Bubble

Shows a floating notification bubble near the chat button.

Setting	Description
Message	Text to display in bubble
Duration	Seconds before auto-hide (optional)

{
  actionType: "show_bubble",
  actionConfig: {
    message: "👋 Need help finding something?",
    duration: 10
  }
}

Trigger Options

Trigger Once

When enabled, the trigger only fires once per session (stored in localStorage).

Value	Behavior
`true`	Fire once, remember in browser
`false`	Fire every time conditions match

Priority

Controls execution order when multiple triggers could fire simultaneously. Lower numbers execute first.

Priority	Use Case
0-10	High priority (welcome messages)
10-50	Normal priority
50+	Low priority (exit intent)

Enabled

Toggle triggers on/off without deleting them.

Example Configurations

Welcome Message (30 seconds)

{
  "name": "Welcome Message",
  "triggerType": "time_on_page",
  "conditions": { "timeOnPage": 30 },
  "actionType": "show_bubble",
  "actionConfig": {
    "message": "👋 Hi! I'm here if you have any questions.",
    "duration": 15
  },
  "triggerOnce": true,
  "priority": 0
}

Pricing Page Help

{
  "name": "Pricing Assistance",
  "triggerType": "page_view",
  "conditions": { "page": "/pricing" },
  "actionType": "show_bubble",
  "actionConfig": {
    "message": "Questions about our plans? I can help you choose!"
  },
  "triggerOnce": true,
  "priority": 5
}

Lead Capture on Scroll

{
  "name": "Scroll Lead Capture",
  "triggerType": "scroll_depth",
  "conditions": { "scrollDepth": 60 },
  "actionType": "show_form",
  "actionConfig": { "toolId": "tool_lead_form" },
  "triggerOnce": true,
  "priority": 20
}

Exit Intent Offer

{
  "name": "Exit Intent Discount",
  "triggerType": "exit_intent",
  "conditions": {},
  "actionType": "open_chat",
  "actionConfig": {
    "message": "Wait! Get 10% off before you go"
  },
  "triggerOnce": true,
  "priority": 100
}

Cart Abandonment

{
  "name": "Cart Recovery",
  "triggerType": "custom_event",
  "conditions": {
    "event": "cart_idle",
    "eventData": { "itemCount": { "$gt": 0 } }
  },
  "actionType": "open_chat",
  "actionConfig": {
    "message": "Need help completing your order?"
  },
  "triggerOnce": true,
  "priority": 30
}

Trigger Analytics

View trigger performance in the dashboard:

Metric	Description
Fired	Times trigger activated
Converted	Times user engaged after trigger
Conversion Rate	Percentage of fires that converted

Access via Agents → Triggers → Analytics.

Programmatic Triggers

You can also trigger actions programmatically from your code:

// Show a bubble
ansa.showBubbles("Need help?", 10);

// Open chat with message
ansa.open("I have a question");

// Show a form
ansa.showForm("contact_form");

// Fire custom event (for custom_event triggers)
ansa.trigger("pricing_viewed", { plan: "enterprise" });

See Widget API for all available methods.

Best Practices

Less is more. Too many triggers can overwhelm users. Start with 1-2 triggers and measure their effectiveness before adding more.

Start subtle — Use bubbles before auto-opening chat
Respect user intent — Don’t fire on every page load
Use trigger once — Avoid annoying repeat prompts
Set priorities — Ensure the most important triggers fire first
Test on mobile — Exit intent doesn’t work on mobile
Monitor analytics — Disable triggers with low conversion

Getting Started

User Guides

Use Cases

Developer Guides

Tools & Forms

Integrations

API Reference

Support

Widget Triggers

Creating Triggers

In the Dashboard

Via API

Trigger Types

Time on Page

Scroll Depth

Exit Intent

Page View

Custom Event

Actions

Open Chat

Show Form

Show Bubble

Trigger Options

Trigger Once

Priority

Enabled

Example Configurations

Welcome Message (30 seconds)

Pricing Page Help

Lead Capture on Scroll

Exit Intent Offer

Cart Abandonment

Trigger Analytics

Programmatic Triggers

Best Practices

Next Steps

Trigger Templates

Custom Events

​Creating Triggers

​In the Dashboard

​Via API

​Trigger Types

​Time on Page

​Scroll Depth

​Exit Intent

​Page View

​Custom Event

​Actions

​Open Chat

​Show Form

​Show Bubble

​Trigger Options

​Trigger Once

​Priority

​Enabled

​Example Configurations

​Welcome Message (30 seconds)

​Pricing Page Help

​Lead Capture on Scroll

​Exit Intent Offer

​Cart Abandonment

​Trigger Analytics

​Programmatic Triggers

​Best Practices

​Next Steps

Trigger Templates

Custom Events

Creating Triggers

In the Dashboard

Via API

Trigger Types

Time on Page

Scroll Depth

Exit Intent

Page View

Custom Event

Actions

Open Chat

Show Form

Show Bubble

Trigger Options

Trigger Once

Priority

Enabled

Example Configurations

Welcome Message (30 seconds)

Pricing Page Help

Lead Capture on Scroll

Exit Intent Offer

Cart Abandonment

Trigger Analytics

Programmatic Triggers

Best Practices

Next Steps