Proactive Messages

New

Proactive messages let you start conversations with visitors before they reach out. A small bubble appears next to the chat launcher with a targeted CTA. When the visitor clicks it, the chat window opens with the assistant’s first message — no fake “user said this” messages, just a natural conversation starter.

How it works

1. Create a proactive message in the dashboard — write the CTA text, configure triggers, set frequency
2. Widget evaluates triggers client-side — time on page, URL match, scroll depth, exit intent, custom events
3. Bubble appears next to the chat launcher with your CTA text and optional sender identity
4. Visitor clicks — chat opens, assistant’s engagement message is shown, visitor replies naturally
5. Analytics tracked — impressions, hovers, clicks, dismissals, and conversions with full page context

Triggers

Triggers control when a proactive message appears. Multiple triggers on the same message use AND logic — all must match.

Time on page

Show after the visitor has been on the page for a specified duration.

{ "type": "time_on_page", "seconds": 15 }

URL match

Show only on specific pages. Multiple patterns use OR logic (any match triggers).

{ "type": "url_match", "patterns": ["/pricing", "/plans"], "match": "starts_with" }

Match modes: exact, starts_with, contains, regex.

Exit intent

Show when the cursor leaves the top of the browser viewport (desktop only, ignored on touch devices). Requires a minimum 5 seconds on page to prevent false positives.

{ "type": "exit_intent" }

Scroll depth

Show when the visitor scrolls past a percentage of the page.

{ "type": "scroll_depth", "percent": 50 }

Custom JS event

Show when your website code fires a specific event via the SDK.

{ "type": "custom_event", "event": "viewed-pricing-table" }

Trigger the event from your code:

receiveo.api.track('viewed-pricing-table');

Tip

Events are filtered at the loader level. Only event names that match a configured trigger are forwarded to the widget — you can call track() liberally without performance overhead.

UTM / Referrer match

Show different messages based on traffic source.

{ "type": "utm_match", "field": "utm_source", "values": ["google", "facebook"], "match": "exact" }

Fields: utm_source, utm_medium, utm_campaign, utm_term, utm_content, referrer. Match modes: exact, contains.

Visitor type

Target new or returning visitors.

{ "type": "visitor_type", "is_returning": true }

Device type

Target specific device types.

{ "type": "device_type", "devices": ["desktop", "mobile"] }

Values: desktop, mobile, tablet.

Frequency controls

Control how often a message is shown to the same visitor.

Frequency	Behavior
once_ever	Show once, never again (persisted in localStorage)
once_per_session	Show once per browser session (sessionStorage)
once_per_visit	Show once per page load
every_time	Show every time all triggers match

Global cooldown: After any proactive message is dismissed, no other message shows for N minutes (default 30, configurable in workspace settings).

Priority: When multiple messages match the same page simultaneously, the highest priority wins. Only one message is shown at a time.

Personalization

Message text supports {{variable}} templates with optional fallbacks:

Hi {{first_name | "there"}}! Need help choosing a plan?

Available variables

Contact fields (populated when visitor is identified via identify()):

{{first_name}}, {{last_name}}, {{name}}, {{email}}, {{phone}}, {{city}}, {{country}}, {{job_title}}, {{company}}, {{lifecycle_stage}}

Custom fields (any custom field defined on your workspace):

{{custom.plan}}, {{custom.signup_date}}, etc.

Page context (always available):

{{page_url}}, {{page_path}}, {{page_title}}, {{referrer}}

Note

If a variable has no value and no fallback, the template tag is removed silently (renders as empty string).

Scheduling

Messages can be restricted to specific times, days, and date ranges:

• Days of week — e.g., Monday through Friday only
• Time of day — e.g., 9:00 AM to 5:00 PM in a specific timezone
• Date range — e.g., run a campaign from April 1 to April 30

SDK methods

track(eventName, metadata?)

Fire a custom event for custom_event triggers.

receiveo.api.track('viewed-pricing-table');
receiveo.api.track('added-to-cart', { product: 'pro-plan' });

getProactiveMessages()

Get the list of proactive message configs loaded from your workspace.

const messages = receiveo.api.getProactiveMessages();
// [{ id: "pm-abc", content: "Need help?", engagementMessage: "...", priority: 10 }, ...]

showProactiveMessage(id)

Manually trigger a specific proactive message by ID, bypassing all trigger and frequency rules.

const messages = receiveo.api.getProactiveMessages();
if (messages.length > 0) {
    receiveo.api.showProactiveMessage(messages[0].id);
}

Caution

showProactiveMessage() bypasses trigger evaluation, scheduling, and frequency rules. The message will show immediately regardless of cooldowns. Use for custom integrations where you need full control.

Analytics

Every proactive message interaction is tracked:

Event	When
Impression	Message bubble is shown to the visitor
Hovered	Visitor hovers over the bubble (once per impression)
Engaged	Visitor clicks the CTA (opens chat)
Dismissed	Visitor clicks the X button
Converted	Visitor sends their first reply in the CTA-originated conversation

The dashboard provides per-message analytics (funnel, time series, page/referrer breakdowns, contact list) and a comparison view across all messages.

Conversation flow

When a visitor clicks a proactive message:

1. The bubble disappears
2. The chat window opens
3. The assistant’s engagement message is shown as the first message (not a fake user message)
4. The visitor replies naturally — the conversation proceeds as normal

This is the industry-standard pattern used by Intercom, Drift, HubSpot, Zendesk, and others. No wasted LLM round trips.