Proactive Engagement Triggers

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:

Example with variables:

{
  "actionMessage": "Hi {visitor.name}! I see you're on {visitor.page}. Would you like {operator.name} to help?"
}

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

Trigger Evaluation

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