# Visitor event rules and actions

Run automatic actions when a visitor meets your event rules.

*Release 3.3 · admin, developer*

**Settings › Events › Visitor Events**

## What it is

**Visitor Events** let you respond automatically to visitor activity. An event combines a trigger, visitor filters and actions. You can use it to offer help, display information, alert operators or update visitor information.

## Who uses it and why

- Administrators with the **Settings** or **Manager** role create and maintain event rules.
- Developers connect labelled events and custom actions to website integrations.

## Where to find it

The **Settings** or **Manager** role grants access, subject to delegated permissions. Open **Settings › Events › Visitor Events**. You can search, copy, edit, enable or disable events in the list. **View Only** access prevents changes.

## How it works

1. The activity selected in **Test for this event** causes INSIDE to check the rule.
2. INSIDE checks that the event is enabled, the visitor has a session, the cooldown has elapsed and all visitor filters pass.
3. Any date and time restrictions must also pass.
4. INSIDE runs the configured actions in sequence and records the cooldown when an action reports success.

Lower **Priority** numbers run first. A successful event does not stop INSIDE checking other events for the same trigger.

Triggers include **On Page View**, **After Page View**, **On Connect**, **On New Visit**, **On Queue**, **On Form Update**, **On Order Update**, **On Sale**, **On Chat Message**, **Time On Page**, **Time On Site**, **Popup Click**, **Event Listener** and **On Watch Video**.

**Time On Site** is checked after page views. **Time On Page** waits for the page timer, then checks the current page, visitor filters, schedule and cooldown again. Navigating away prevents the old page's delayed action from running.

## Configure it

Create an event, enter a unique **Name** and a **Description**, select its **Type** and choose **Test for this event**. Add visitor filters and complete the fields for the chosen action. Add **Dates** restrictions if needed, then save and enable the event.

New events normally start with a **Cooldown** of 10 minutes. Selecting **Proactive Chat** for a new event changes that initial value to 1,440 minutes. Check the value before saving. Use **Shared Cooldown** to coordinate related rules; each rule still uses its own waiting interval.

For an **Event Listener**, enter a **Label** for your integration. Several events can share a label and are checked in priority order.

### Settings

| Setting | Where | Applies to | Default | Who can change it | What it does |
|---|---|---|---|---|---|
| Enabled | Settings › Events › Visitor Events | website | Off | Settings role, Manager role | Allows the event to run when its other checks pass. |
| Type | Settings › Events › Visitor Events | website | Not set: choose an event type before saving | Settings role, Manager role | Selects the main action, such as Proactive Chat or Visitor Popup. |
| Test for this event | Settings › Events › Visitor Events | website | On Page View | Settings role, Manager role | Selects when INSIDE checks the rule. |
| Priority | Settings › Events › Visitor Events | website | Not set: runs after events with a numbered priority | Settings role, Manager role | Lower numbers run before higher numbers; events without a priority run last. |
| Cooldown | Settings › Events › Visitor Events | website | 10 minutes; selecting Proactive Chat for a new event changes it to 1,440 minutes (24 hours) | Settings role, Manager role | Sets the minimum interval in minutes between recorded executions for this visitor's session. |
| Shared Cooldown | Settings › Events › Visitor Events | website | Not set: uses this event's own cooldown history | Settings role, Manager role | Uses another event's cooldown history to coordinate related events. |
| Minimum Time | Settings › Events › Visitor Events | website | 0 seconds | Settings role, Manager role | Sets the earliest qualifying time in seconds for time-based triggers. |

### Fields

| Field | Where | Required | What it is for |
|---|---|---|---|
| Name | Settings › Events › Visitor Events | Yes | Identifies the event in the event list. |
| Description | Settings › Events › Visitor Events | Yes | Explains the purpose of the event. |
| Label | Settings › Events › Visitor Events | Yes | Required when Event Listener is selected; identifies events to trigger through an integration. |

### Permissions

| Permission | Lets you |
|---|---|
| Settings | Access Visitor Events, subject to delegated permissions. |
| Manager | Access Visitor Events, subject to delegated permissions. |
| View Only | View permitted configuration without editing it. |

## Limits and good to know

- An event with no visitor filters does not run. Removing every filter does not mean everyone qualifies.
- A cooldown of zero removes the event's waiting interval. For a positive cooldown, elapsed time must be greater than the configured interval.
- Event cooldowns belong to the visitor's session. Proactive chat also has a separate website-wide check against the visitor's previous chat.
- Scheduling a task alone does not record an event cooldown. Use careful targeting for task-start rules.
- A recorded event execution does not establish that the visitor saw or accepted its result.

## Depends on and works with

### This feature uses

- **Requires** [Visits and returning visitors](VIS-002.md): Visitor events need an active visit session and use its cooldown history.
- **Requires** [Visitor event targeting conditions](ENG-002.md): A visitor event needs at least one visitor condition before it can run.
- **Configured in** [Visitor event and bot schedules](ENG-003.md): Date and time filters restrict when an event can run.
- **Configured in** [Video Feed for visitors](VX-025.md): Video Feed settings determine when playback qualifies for video-watched triggers.
- **Works better with** [Visitor actions and events](VIS-010.md): Captured actions and labelled integration events provide optional triggers for visitor rules.
- **Works better with** [Time-based visitor event triggers](VIS-026.md): Timed page signals support Time On Page events.
- **Works better with** [Proactive chat invitations](ENG-004.md): A matching event can offer a proactive chat.
- **Works better with** [Visitor popup event setup](ENG-006.md): A matching event can display a visitor popup or survey.
- **Works better with** [Visitor event updates to customer context](ENG-007.md): Additional actions can change visitor or conversation state.
- **Works better with** [Visitor event alerts for operators](ENG-008.md): Events can alert operators and bring visitors to their attention.
- **Works better with** [Integration script selection for automated actions](EXT-016.md): Integration scripts can trigger labelled events or provide custom actions.

### Used by

- **Required by** [Time-based visitor event triggers](VIS-026.md): Timed triggers are configured as visitor-event rules.
- **Required by** [Visitor popups and embedded content](VX-016.md): A visitor event delivers the popup action.
- **Required by** [Visitor event targeting conditions](ENG-002.md): Visitor events use these filters when their trigger occurs.
- **Required by** [Proactive chat invitations](ENG-004.md): A matching visitor event starts the invitation.
- **Required by** [Visitor popup event setup](ENG-006.md): Visitor event rules control when offers are sent.
- **Required by** [Visitor event updates to customer context](ENG-007.md): A matching visitor event runs the actions.
- **Required by** [Visitor event alerts for operators](ENG-008.md): Visitor events run alerts and floor actions.
- **Required by** [Click to Call callback form](RTC-036.md): An enabled visitor event selects the Click to Call action and callback integration.
- **Configures** [Visitor actions and events](VIS-010.md): Visitor-event configuration determines the rules associated with action and named-event triggers.
- **Configures** [Monitor mode](CON-025.md): Visitor-event rules can select interesting conversations for monitor alerts.
- **Configures** [Visitor chat themes and branding](VX-003.md): Visitor events can select an alternative theme.
- **Configures** [Pre-chat survey for visitors](VX-008.md): Visitor events can select a different pre-chat survey or task.
- **Configures** [Appointment booking for visitors](VX-023.md): Visitor events can select the scheduling theme used for appointment intake.
- **Configures** [Joining calls and approving Co-Browse](VX-026.md): Visitor events offer Join the Call and Click to Call entries to qualifying visitors.
- **Configures** [Legacy chat pane settings](VX-032.md): Visitor events can select an alternate legacy chat configuration.
- **Configures** [Autonomous agents for proactive chat](AI-005.md): Visitor events define when proactive engagement is attempted.
- **Configures** [Live show setup and scheduling](RTC-022.md): Visitor event rules determine which visitors receive notifications for ad hoc shows.
- **Configures** [Event, link and Virtual Assistant reports](REP-013.md): Visitor event definitions determine the events and actions grouped in event reporting.
- **Configures** [Integration script selection for automated actions](EXT-016.md): Visitor Events selects custom script actions and defines when they run.
- **Enhances** [Visitor page and product tracking](VIS-003.md): Visitor events can respond to page views.
- **Enhances** [Virtual Assistant usage](ENG-025.md): Visitor events add cooldown timing evidence separately from task and step activity.
- **Enhances** [Basket tracking](COM-019.md): Visitor events can act on observed basket state.
- **Enhances** [Team comparison reports](REP-005.md): Visitor events provide an engagement breakdown.
- **Enhances** [Customer survey and NPS reports](REP-010.md): Visitor survey events supply Event Surveys activity.
- **Related** [Video Feed for visitors](VX-025.md): Visitor events can respond to video viewing using the configured watch thresholds.
- **Related** [Visitor event and bot schedules](ENG-003.md): Event schedules permit or prevent a matching trigger without creating a trigger themselves.

## FAQ and troubleshooting

### Why does my enabled event do nothing?

Check the trigger, visitor filters, **Dates**, cooldown and action-specific requirements. At least one visitor filter is needed.

### Why do two matching events run?

**Priority** controls order. It does not select a single winning event. Use filters and **Shared Cooldown** where related events need coordination.

### Why does Time On Site not fire as soon as the threshold passes?

INSIDE checks it after a page view. Use **Time On Page** when the action should follow a wait on the current page.

### Why did changing pages cancel the delayed popup?

The page timer checks that the visitor is still on the qualifying page before running the action.