Embed API
The Embed API powers the FloatMessage embed script. It returns the messages and chat configuration that should render on a visitor's page and ingests analytics events. All embed endpoints support cross-origin requests via Access-Control-Allow-Origin: *.
Every embed call must identify which domain it's coming from. The script reads window.location.hostname and sends it as the domain parameter on every request. The server only returns assets that belong to that domain - see Domain Workspaces.
GET/api/embed/user?userId={userId}&domain={hostname}
Returns every active floating message that belongs to the requested domain. This is the primary endpoint the embed script calls on page load. If the host isn't a registered domain for the user, the response is an empty array.
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| userId | string | Required. Your FloatMessage account ID. |
| domain | string | Required. Hostname (e.g. acme.com) of the page making the call. Must be one of your registered domains. The embed script sets this automatically from window.location.hostname. |
Response 200
An array of message configuration objects (same shape as /api/embed?id=…). Empty array if the domain is not registered or has no active messages.
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
| Parameter | Type | Description |
|---|---|---|
| id | string | Required. The message ID to retrieve. |
| domain | string | Required. The hostname of the page requesting the message. The server validates that the message belongs to this domain - if it doesn't, the response is 404. Set automatically by the embed script. |
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
| Status | Body | Description |
|---|---|---|
| 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
| Parameter | Type | Description |
|---|---|---|
| id | string | Required. The message ID to record a click for. |
Response 200
{ "ok": true }CORS
Supports OPTIONS preflight requests with Access-Control-Allow-Origin: *.