Messages API
The Messages API lets you manage floating messages programmatically. All endpoints require an authenticated session cookie — they are intended for use from the FloatMessage dashboard or server-side integrations that share the same session.
GET/api/messages
Returns all messages belonging to the authenticated user.
Authentication
Requires a valid session cookie. Returns 401 if unauthenticated.
Response 200
[
{
"id": "clx1abc2d0001ab12example",
"name": "Welcome Discount",
"template": "banner",
"position": "BOTTOM_RIGHT",
"active": true,
"clicks": 142,
"impressions": 3891,
"createdAt": "2026-03-01T10:00:00.000Z",
"updatedAt": "2026-03-20T14:30:00.000Z"
}
]POST/api/messages
Creates a new floating message. Requires an authenticated session and an active plan or trial.
Authentication
Requires a valid session cookie and an active subscription or trial. Returns 401 if unauthenticated, or 403 if the plan/trial has expired.
Request Body
{
"name": "Welcome Discount",
"template": "banner",
"htmlContent": "<div>...</div>",
"cssContent": ".class { ... }",
"slidesData": null,
"position": "BOTTOM_RIGHT",
"trigger": "IMMEDIATE",
"triggerValue": null,
"domains": [],
"geoCountries": ["US", "GB"],
"scheduleDays": [1, 2, 3, 4, 5],
"scheduleTimeStart": "09:00",
"scheduleTimeEnd": "17:00",
"scheduleDateStart": "2026-03-01",
"scheduleDateEnd": "2026-03-31",
"dismissBehavior": "SESSION",
"dismissDuration": null
}Body Fields
| Field | Type | Description |
|---|---|---|
| name | string | Display name for the message. |
| template | string | Template type, e.g. banner, story, popup. |
| htmlContent | string | null | HTML content for non-story templates. |
| cssContent | string | null | Custom CSS scoped to the message. |
| slidesData | array | null | Slide objects for story templates. Each slide has imageUrl, linkUrl, and duration. |
| position | string | Screen position: BOTTOM_RIGHT, BOTTOM_LEFT, TOP_RIGHT, TOP_LEFT. |
| trigger | string | When to show: IMMEDIATE, DELAY, SCROLL. |
| triggerValue | string | null | Delay in ms or scroll percentage, depending on trigger type. |
| domains | string[] | Allowed domains. Empty array means all domains. |
| geoCountries | string[] | ISO 3166-1 alpha-2 country codes. Empty means all countries. |
| scheduleDays | number[] | Days of week (0 = Sunday, 6 = Saturday). |
| scheduleTimeStart / scheduleTimeEnd | string | null | Time range in HH:mm format, or null for all day. |
| scheduleDateStart / scheduleDateEnd | string | null | Date range in YYYY-MM-DD format, or null for no date restriction. |
| dismissBehavior | string | SESSION, DURATION, or NONE. |
| dismissDuration | number | null | Seconds before the message can reappear (for DURATION behavior). |
Response 201
Returns the created message object with all fields including id, createdAt, and updatedAt.
Error Responses
| Status | Description |
|---|---|
| 401 | Unauthenticated. No valid session. |
| 403 | Plan or trial expired. |
PUT/api/messages
Updates an existing message. The request body must include the id field, and the authenticated user must own the message.
Authentication
Requires a valid session cookie and message ownership.
Request Body
{
"id": "clx1abc2d0001ab12example",
"name": "Updated Discount Banner",
"htmlContent": "<div>New content</div>",
...all other fields from POST
}Response 200
Returns the updated message object.
Error Responses
| Status | Description |
|---|---|
| 401 | Unauthenticated. |
| 403 | Not the owner of this message. |
| 404 | Message not found. |
DELETE/api/messages?id={messageId}
Deletes a message. The authenticated user must own the message.
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| id | string | Required. The message ID to delete. |
Response 200
{ "ok": true }Error Responses
| Status | Description |
|---|---|
| 401 | Unauthenticated. |
| 403 | Not the owner of this message. |
| 404 | Message not found. |