FloatMessage

Embed API

The Embed API powers the FloatMessage embed script. It allows you to retrieve message configuration for a given message ID and to track click events. All embed endpoints support cross-origin requests via Access-Control-Allow-Origin: *.

GET/api/embed?id={messageId}

Returns the full message configuration used by the embed script to render a floating message on the client’s site.

Query Parameters

ParameterTypeDescription
idstringRequired. The message ID to retrieve.

Headers Checked

CF-IPCountry — Used for geo targeting. If the message is restricted to specific countries, the visitor’s country (provided by Cloudflare) is checked against the allowed list.

Response 200 — Standard Template

{
  "id": "clx1abc2d0001ab12example",
  "template": "banner",
  "htmlContent": "<div class=\"fm-banner\">Welcome! Get 20% off.</div>",
  "cssContent": ".fm-banner { background: #6366f1; color: #fff; padding: 12px; }",
  "position": "BOTTOM_RIGHT",
  "trigger": "IMMEDIATE",
  "triggerValue": null,
  "dismissBehavior": "SESSION",
  "dismissDuration": null,
  "scheduleDays": [1, 2, 3, 4, 5],
  "scheduleTimeStart": "09:00",
  "scheduleTimeEnd": "17:00"
}

Response 200 — Story Template

{
  "id": "clx1abc2d0002ab12example",
  "template": "story",
  "slidesData": [
    {
      "imageUrl": "https://cdn.example.com/slide1.jpg",
      "linkUrl": "https://example.com/promo",
      "duration": 5000
    },
    {
      "imageUrl": "https://cdn.example.com/slide2.jpg",
      "linkUrl": null,
      "duration": 4000
    }
  ],
  "position": "BOTTOM_LEFT",
  "trigger": "DELAY",
  "triggerValue": "3000",
  "dismissBehavior": "DURATION",
  "dismissDuration": 86400,
  "scheduleDays": [0, 1, 2, 3, 4, 5, 6],
  "scheduleTimeStart": null,
  "scheduleTimeEnd": null
}

Error Responses

StatusBodyDescription
400{ "error": "Missing id" }The id query parameter was not provided.
403{ "error": "Blocked" }The message has expired or the visitor’s country is not in the allowed geo list.
404{ "error": "Not found" }The message does not exist or is inactive.

CORS

Access-Control-Allow-Origin: *

POST/api/embed/click?id={messageId}

Increments the click counter for the specified message. Called automatically by the embed script when a visitor interacts with the message CTA.

Query Parameters

ParameterTypeDescription
idstringRequired. The message ID to record a click for.

Response 200

{ "ok": true }

CORS

Supports OPTIONS preflight requests with Access-Control-Allow-Origin: *.