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 |
- 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
}
| Setting | Description |
|---|
| Percentage | 0-100% scroll depth threshold |
- 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 | 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 } }
}
}
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"
}
}
| 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
}
{
"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 |
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" });
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
Next Steps
