message.comDevelopers
Developers/Tutorials/Proactive messages

Send proactive messages

A proactive message opens the chat panel with an agent-attributed greeting before the visitor asks. Used well, this lifts conversions on pricing pages and cart abandons. Used badly, it is the chat-spam your visitors hate. Pick the trigger carefully.

Do not blast every visitor. Target a real signal (time on a high-intent page, cart contents, hesitation on checkout). One proactive per session per topic is the ceiling.

The API

Call Message.sendProactive({ body, agentName?, agentAvatar? }). The panel opens with the message attributed to the agent identity you pass. The visitor sees it as if a human agent reached out.

Pattern 1: Time on a high-intent page

The classic. After 20 seconds on /pricing, offer help.

HTML
<script>
  window.MessageOnReady = function () {
    if (window.location.pathname !== "/pricing") return;

    setTimeout(() => {
      window.Message.sendProactive({
        body: "Hi! Want help picking the right plan?",
        agentName: "Sam from Sales",
        agentAvatar: "https://cdn.yourdomain.com/sam.png"
      });
    }, 20_000); // 20 seconds on /pricing
  };
</script>

Pattern 2: Cart abandon

For ecommerce. Visitor has items in cart, then sits idle for a minute. Offer help.

javascript
// Fire on Shopify cart with items but no checkout intent for 60s
let idleTimer;
function resetIdle() {
  clearTimeout(idleTimer);
  idleTimer = setTimeout(() => {
    if (cartItems.length > 0 && !checkoutClicked) {
      window.Message?.sendProactive({
        body: "Need help completing your order?",
        agentName: "Maya"
      });
    }
  }, 60_000);
}
document.addEventListener("mousemove", resetIdle);
document.addEventListener("scroll", resetIdle);
resetIdle();

Pattern 3: Returning paying customer

For SaaS. If a paying customer hits the docs (or the same error page twice), offer the engineering team.

javascript
window.MessageOnReady = function () {
  if (visitor.plan === "pro" && visitedDocsCount > 1) {
    window.Message.sendProactive({
      body: "Saw you hit the docs a couple times. Want a hand?",
      agentName: "Engineering on-call"
    });
  }
};

Throttle

Store a flag in sessionStorage (or localStorage for cross-session throttling) before firing:

javascript
function fireOnce(topic, fn) {
  const key = `message:proactive:${topic}`;
  if (sessionStorage.getItem(key)) return;
  sessionStorage.setItem(key, "1");
  fn();
}

fireOnce("pricing-help", () => {
  window.Message.sendProactive({ body: "Need help with pricing?" });
});

Measure

Use the reports API to compare conversion with and without proactives. Tag visitors who received a proactive with a proactiveFired attribute. Pull /api/v1/reports/conversations/total?range=7d and segment.

Common pitfalls

  • Firing too early. A proactive within five seconds of page load feels like ad spam. Twenty seconds is a floor.
  • Mobile. The chat panel is full-screen on mobile. A proactive there interrupts whatever the visitor was reading. Disable proactives on small viewports.
  • Anonymous agent. Always pass agentName and avatar. Unattributed proactives read as bot spam.
  • Off-hours. Do not send proactives outside business hours unless an off-hours form is the next step. Visitors expect a reply when an agent reaches out.
  • Compliance. Some jurisdictions consider unsolicited chat outreach a form of marketing. Audit before targeting EU visitors.

Next steps