FloatMessage

Embed Integration

FloatMessage can be added to any website with a single <script> tag. No build tools, frameworks, or dependencies required.

Basic Embed

Paste the following snippet just before the closing </body> tag. Replace YOUR_USER_ID with your account ID from the FloatMessage dashboard.

<script
  src="https://floatmessage.com/embed/floatmessage.js"
  data-user="YOUR_USER_ID"
></script>

That single tag loads every active floating message in your account, plus the live chat widget if it's enabled. You don't need to manage individual message IDs - just create messages in the dashboard and they appear automatically.

Install via Google Tag Manager (query string)

Some tag managers (including Google Tag Manager's Custom HTML tag) strip data-* attributes from injected script elements. The embed accepts the same parameters via query string on the src URL, so the entire install is a single line:

<script src="https://floatmessage.com/embed/floatmessage.js?userId=YOUR_USER_ID" defer></script>

Both ?userId= and ?user= are accepted. You can also pass ?domain=, ?domainId=, and ?api= the same way. data-attributes still win when both are set, so existing installs are unaffected.

See Add FloatMessage via Google Tag Manager for the step-by-step container setup.

Custom API Base

If you self-host FloatMessage or want to proxy the API, use the data-api attribute to override the default endpoint.

<script
  src="https://floatmessage.com/embed/floatmessage.js"
  data-user="YOUR_USER_ID"
  data-api="https://your-domain.com"
></script>

Domain detection

FloatMessage scopes everything to a domain (see Domain Workspaces). The script auto-detects which domain it's on by reading window.location.hostname and only loads messages, chat config, and analytics that belong to it. If the host isn't one you've registered in Dashboard → Domains, the response is empty and nothing renders.

For staging environments, preview deployments, or proxied installs, you can force a specific domain with data-domain:

<script
  src="https://floatmessage.com/embed/floatmessage.js"
  data-user="YOUR_USER_ID"
  data-domain="site-a.com"
></script>

Dev Console Testing

You can quickly test your messages without editing your HTML by pasting an inline script into your browser's developer console.

const s = document.createElement("script");
s.src = "https://floatmessage.com/embed/floatmessage.js";
s.dataset.user = "YOUR_USER_ID";
document.body.appendChild(s);

How the Embed Script Works

The embed script is a lightweight, zero-dependency JavaScript file. It renders each message inside a Shadow DOM container, so FloatMessage styles never leak into your page and your page styles never affect the message.

  • Shadow DOM isolation — Each message lives in its own shadow root. No CSS conflicts, no z-index wars.
  • Zero dependencies — Pure JavaScript. No jQuery, no React, no external libraries.
  • Works on any platform — WordPress, Shopify, Webflow, Wix, static HTML, single-page apps, or any site that can include a script tag.

Initialization Flow

When the script loads, it follows this sequence:

  1. Read configuration — Parses data-user (plus optional data-domain and data-api) from the script tag.
  2. Fetch all active messages — Calls /api/embed/user to retrieve every active message in your account, including their template, content, schedule, trigger, and dismiss settings.
  3. Check schedule — Evaluates date range, days of week, and time range against the visitor's local time. If outside the schedule, the message is skipped.
  4. Check dismiss state — Looks up sessionStorage or localStorage to see if the visitor previously dismissed this message. If so, the message is skipped.
  5. Render — Creates a Shadow DOM container and injects the message HTML and styles. Applies the configured trigger (immediate, delay, scroll, or exit intent).
  6. Initialize live chat — If the chat widget is enabled in settings, the script also injects the chat bubble and panel using the same Shadow DOM isolation.