Proactive triggers

Overview

By default the agent waits for the visitor to start the conversation. Triggers let you flip that around: you fire a trigger from your own page code, and the agent generates a message and shows it to the visitor — proactively. Use triggers for things like:

Greeting a visitor who has been idle on the pricing page
Offering help when someone reaches the third step of a checkout
Surfacing a relevant tip after the visitor performs an action

The prompt you pass is an instruction to the agent, not text shown verbatim. The agent reads it, decides what to say, and produces a natural reply.

Quick start

<script src="https://unpkg.com/zephlo/dist/zephlo.js"></script>
<zephlo-fab></zephlo-fab>
<script>
  const zephlo = Zephlo.initialize({
    key: "flk_your_api_key",
    chatbotId: "YOUR_AGENT_ID",
  });

  // Nudge the visitor after 10 seconds on the page
  setTimeout(() => {
    zephlo.trigger("pricing_help", "Offer to answer questions about our pricing plans");
  }, 10_000);
</script>

import Zephlo from "zephlo";

const zephlo = Zephlo.initialize({
  key: "flk_your_api_key",
  chatbotId: "YOUR_AGENT_ID",
});

zephlo.trigger("pricing_help", "Offer to answer questions about our pricing plans");

API

`trigger(id, prompt, options?)`

Parameter	Type	Required	Description
`id`	`string`	Yes	A stable identifier for this trigger. Used by the cooldown system to remember whether it has fired
`prompt`	`string`	Yes	The instruction the agent uses to generate its message
`options`	`object`	No	Display mode, cooldown, and page context (see below)

Returns a promise that resolves to { fired: boolean }. fired is false when a cooldown blocked the call.

const { fired } = await zephlo.trigger(
  "cart_abandon",
  "Encourage the visitor to complete their purchase",
  { mode: "prompt", cooldown: "session" }
);

Options

Option	Type	Default	Description
`mode`	`"open" \| "prompt"`	`"prompt"`	How the message is shown (see below)
`cooldown`	`CooldownPolicy`	`null`	How often the trigger may fire (see below)
`pageContext`	`Record<string, unknown>`	`{}`	Extra page data sent alongside the trigger, just like page context

Display modes

prompt (default)

The agent’s reply appears as a small clickable bubble next to the floating button. Clicking it opens the chat. The message is saved to the conversation either way.

open

The chat panel expands automatically and the agent’s message appears in the thread.

// Subtle bubble next to the button
zephlo.trigger("idle_nudge", "Greet the visitor and offer help", { mode: "prompt" });

// Pop the chat open with the message
zephlo.trigger("vip_offer", "Tell the visitor about the launch discount", { mode: "open" });

In prompt mode the bubble auto-dismisses after about 15 seconds. The message stays in the conversation history regardless of whether the visitor clicks it.

Cooldowns

A trigger usually shouldn’t fire on every page load. The cooldown option throttles how often a given id is allowed to fire on a visitor’s device.

Policy	Behavior
`null` (default)	Always fires
`"session"`	Once per browser tab/session
`"once"`	Once forever on this device
`{ minutes: N }`	At most once every `N` minutes

// Greet once per browsing session
zephlo.trigger("welcome", "Welcome the visitor to the site", { cooldown: "session" });

// Show a one-time announcement
zephlo.trigger("new_feature", "Announce the new analytics dashboard", { cooldown: "once" });

// Re-offer help at most every 30 minutes
zephlo.trigger("need_help", "Ask if the visitor needs any help", { cooldown: { minutes: 30 } });

Cooldown state is keyed by the trigger id, so keep ids stable and unique. Changing an id resets its cooldown.

Sending page context with a trigger

The pageContext option lets the agent tailor its message to what the visitor is looking at — the same idea as page context, but bundled into the trigger call.

zephlo.trigger(
  "plan_help",
  "Offer to explain what's included in the plan the visitor is viewing",
  {
    mode: "prompt",
    cooldown: "session",
    pageContext: { plan: "Pro", price: "$49/mo", billing: "monthly" },
  }
);

Firing before initialization

Zephlo.trigger(...) is also available as a global. If you call it before Zephlo.initialize() has run, it waits for initialization and then fires — handy when your trigger logic and your init script live in different places.

<script src="https://unpkg.com/zephlo/dist/zephlo.js"></script>
<script>
  // This is safe even though initialize() runs later on the page.
  Zephlo.trigger("early_nudge", "Greet the visitor", { cooldown: "session" });
</script>

Getting started

Widget

Proactive triggers

Overview

Quick start

API

`trigger(id, prompt, options?)`

Options

Display modes

prompt (default)

open

Cooldowns

Sending page context with a trigger

Firing before initialization

Next steps

Page context

Theming

​Overview

​Quick start

​API

​trigger(id, prompt, options?)

​Options

​Display modes

prompt (default)

open

​Cooldowns

​Sending page context with a trigger

​Firing before initialization

​Next steps

Page context

Theming

Overview

Quick start

API

`trigger(id, prompt, options?)`

Options

Display modes

Cooldowns

Sending page context with a trigger

Firing before initialization

Next steps