Proactive Engagement Triggers
Engage visitors automatically with time-on-page, exit-intent, and page-visit triggers that send personalized messages.
Proactive engagement triggers automatically initiate conversations based on visitor behavior. Unlike the widget's built-in triggers that only open the chat window, these triggers can send personalized messages with variable substitution and are delivered to the visitor in real time.
Overview
Triggers are stored per-organization and evaluated when visitor events occur. Each trigger defines:
- Type: the event that activates the trigger
- Conditions: additional criteria (page URLs, time thresholds)
- Message: the personalized message sent to the visitor
- Active flag: enable or disable without deleting
When a trigger fires, the widget displays the configured message as a proactive invitation.
Trigger Types
Time on Page
Fires after the visitor has spent a specified amount of time on a page. Use this to engage visitors who are actively browsing but haven't started a conversation.
{
"name": "Pricing Page Engagement",
"type": "time_on_page",
"conditions": {
"timeOnPage": 30
},
"actionMessage": "Hi {visitor.name}! I see you're checking out our pricing. Need any help choosing the right plan?"
}Exit Intent
Fires when the visitor's mouse moves toward the browser chrome, indicating they may be about to leave the page. Desktop only.
{
"name": "Exit Intent Offer",
"type": "exit_intent",
"conditions": {
"pages": ["/pricing", "/signup"]
},
"actionMessage": "Wait! Before you go, would you like to see a quick demo?"
}Page Visit
Fires when the visitor navigates to a specific page or URL pattern. Use this for targeted engagement on high-value pages like checkout or pricing.
{
"name": "Checkout Help",
"type": "visited_page",
"conditions": {
"currentPage": "https://example.com/checkout"
},
"actionMessage": "Need help with checkout? We're here to assist."
}First Visit
Fires when a visitor is identified as a first-time visitor. Use this for welcome messages or onboarding guidance.
{
"name": "Welcome New Visitor",
"type": "first_visit",
"conditions": {},
"actionMessage": "Welcome! First time here? Let us know if you have any questions."
}Proactive Invitation
A special trigger type that sends a proactive invitation rather than a direct message. The widget displays it as a distinct invitation UI.
{
"name": "Support Invitation",
"type": "proactive_invitation",
"conditions": {
"timeOnPage": 15
},
"actionMessage": "Would you like to chat with our support team?"
}Configuration
Create a Trigger
POST /api/triggers{
"name": "Pricing Page Engagement",
"type": "time_on_page",
"conditions": {
"timeOnPage": 30
},
"actionMessage": "Hi there! Need help choosing the right plan?",
"isActive": true
}Variable Substitution
Trigger messages support template variables that are replaced with actual values when the trigger fires:
| Variable | Replaced With |
|---|---|
{visitor.name} | Visitor's name, or "there" if unknown |
{visitor.page} | Current page URL |
{operator.name} | Assigned operator's name |
Example with variables:
{
"actionMessage": "Hi {visitor.name}! I see you're on {visitor.page}. Would you like {operator.name} to help?"
}Plan Limits
Trigger count is limited by plan. Free plans have 0 triggers, Growth plans allow 5 active triggers, and Pro plans have unlimited triggers.
Widget Integration
Triggers can be evaluated in two modes:
Direct Message
Sends a message directly into the conversation as a system message:
POST /api/triggers/evaluate{
"convId": "conversation-uuid",
"eventType": {
"type": "time_on_page"
},
"context": {
"currentPage": "https://example.com/pricing",
"timeOnPage": 35,
"visitorName": "Alice"
}
}The message appears in the conversation thread and is visible in the conversation history.
Proactive Invitation
Sends a proactive invitation that appears as a distinct UI element in the widget:
POST /api/triggers/proactive{
"convId": "conversation-uuid",
"context": {
"currentPage": "https://example.com/pricing",
"timeOnPage": 35,
"isExiting": true
}
}The invitation includes the trigger name, message, and action message for the widget to render appropriately.
API Reference
Trigger Management
| Method | Endpoint | Description |
|---|---|---|
GET | /api/triggers | List all triggers |
POST | /api/triggers | Create a trigger |
PATCH | /api/triggers/:id | Update a trigger |
DELETE | /api/triggers/:id | Delete a trigger |
Trigger Evaluation
| Method | Endpoint | Description |
|---|---|---|
POST | /api/triggers/evaluate | Evaluate and send direct message |
POST | /api/triggers/proactive | Evaluate and send invitation |
All endpoints require authentication. Trigger creation and plan limits are enforced automatically.
Related
- Widget Triggers: widget-level auto-open configuration
- Chatbot Rules Engine: automated response rules
- Triggers: embedding and widget customization
Was this page helpful?