JavaScript API

Control the chat widget programmatically from your website's JavaScript. Open the chat from a custom button, hide it based on conditions, or toggle it in response to user actions.

Enable the API

Go to Dashboard → Chat Settings → JavaScript API
Toggle the JavaScript API on
Save settings

Once enabled, the embed script exposes a global window.FloatMessage object with the methods below.

Available Methods

Method	Description
FloatMessage.showChat()	Shows the chat bubble (if previously hidden)
FloatMessage.hideChat()	Hides the chat bubble and closes the panel
FloatMessage.openChat()	Shows the bubble and opens the chat panel
FloatMessage.closeChat()	Closes the chat panel (bubble stays visible)
FloatMessage.toggleChat()	Toggles the chat panel open or closed
FloatMessage.setCustomData(data)	Send custom key-value data for the visitor. Available as `${key}` template variables in AI instructions and in webhook payload as `visitor.customData`

Examples

Open Chat from a Custom Button

<button onclick="FloatMessage.openChat()">
  Need help? Chat with us
</button>

Toggle Chat from a Navigation Link

<a href="#" onclick="event.preventDefault(); FloatMessage.toggleChat()">
  Support
</a>

Show Chat After a Delay

<script>
  // Hide chat initially, then show after 10 seconds
  setTimeout(function() {
    if (window.FloatMessage) {
      FloatMessage.showChat();
    }
  }, 10000);
</script>

Open Chat Based on User Action

// Open chat when a visitor scrolls to the pricing section
const observer = new IntersectionObserver((entries) => {
  if (entries[0].isIntersecting && window.FloatMessage) {
    FloatMessage.openChat();
    observer.disconnect();
  }
});
observer.observe(document.getElementById("pricing"));

Pass Custom Data for AI Personalization

<script>
  // Pass visitor context to the AI agent and webhook
  FloatMessage.setCustomData({
    userPlan: "enterprise",
    cartTotal: "249.99",
    accountAge: "2 years"
  });

  // These become ${userPlan}, ${cartTotal}, ${accountAge}
  // in your AI instructions
</script>

Set Custom Data After User Login

// After your auth flow completes
function onUserLogin(user) {
  if (window.FloatMessage) {
    FloatMessage.setCustomData({
      userId: user.id,
      plan: user.subscription,
      company: user.companyName
    });
  }
}

Hide Chat on Specific Pages

<script>
  // Hide chat on checkout pages
  if (window.location.pathname.startsWith("/checkout")) {
    document.addEventListener("DOMContentLoaded", function() {
      if (window.FloatMessage) {
        FloatMessage.hideChat();
      }
    });
  }
</script>

Notes

The FloatMessage object is available after the embed script loads. If calling early, check window.FloatMessage exists first.
The API must be enabled in Chat Settings. When disabled, window.FloatMessage will not be set.
All methods are safe to call at any time — they handle edge cases like the panel already being open or the bubble already being hidden.
The API works on both desktop and mobile. On mobile, openChat() opens the full-screen chat panel.