Blue Machines Chat Preview

How the product works

Blue Machines Chat Preview lets sales and customer-success teams see how the BlueMachines chat widget looks on a client's website before it is embedded in production.

A user provides three inputs on the home page:

1. Client URL — the website to preview (e.g. https://bluemachines.ai)
2. Chat widget code — the <script> embed snippet from BlueMachines
3. Backdrop mode — how to render the site behind the widget: auto, iframe, or thumbnail

The app opens a full-screen preview. The client site appears as a live iframe or a screenshot, and the chat widget is overlaid on top in a separate layer. The widget always renders — even when the site backdrop fails to load.

User journeys

Home form processing

When the user submits, the app:

1. Normalizes the URL (adds https:// if missing)
2. Validates URL format and non-empty widget code
3. Extracts widget attributes: data-widget-token, data-agent-id, data-agent-profile-id, data-base-url, src
4. Builds query params (includes backdrop only when not auto)
5. Stores preview:url and preview:widget in sessionStorage as a same-tab fallback

The Additional params section lets you attach arbitrary key/value pairs (e.g. utm_source, ref) that are carried through to the preview URL and persisted on the short link. Reserved keys (url, backdrop, src, and the data-* widget attributes) are blocked.

Preview page

The preview page (/preview) is the core of the product. It stacks three layers inside a device frame:

Backdrop modes

Auto mode resolution

In auto mode the app shows a loading logo while checking headers — the site iframe is not mounted until iframe embedding is likely allowed. This avoids stuck states and long waits.

Timeouts

Thumbnail retries

The screenshot API retries Microlink with escalating wait strategies and can fall back to Firecrawl when FIRECRAWL_API_KEY is configured. The preview page retries up to 3 times (attempts 0–2) with fresh=1 before showing the static logo. Cookie consent banners are suppressed via Microlink adblock, injected CSS, and an accept-button click script.

Logo states

Device frames & settings

Users can switch between desktop (full viewport), tablet (820×1180), and mobile (390×844) frames via the settings gear in the bottom-left corner. On real mobile browsers, the preview renders full-viewport without a simulated bezel.

The settings panel also lets users manually toggle between iframe and thumbnail backdrop modes.

Short links

Short links persist a preview configuration so it can be shared without re-entering the form. Each link is a 7-character ID stored in the short_links database table.

Stored parameters

Each short link stores a JSON object with these keys:

• url — normalized client site URL
• data-widget-token, data-agent-id, data-agent-profile-id
• data-base-url, src — widget script configuration
• backdrop — only when not auto

Deduplication: Identical URL + widget + backdrop always returns the same short ID. No duplicate rows are created.

Redirect flow

1. User visits /s/{id}
2. App loads stored params from the database
3. On miss → redirect to home page
4. On hit → redirect to /preview?{params}

History search

The history page supports client URL search via /history?q=salesforce. Matching is case-insensitive substring (ILIKE) on the stored params.url field. Search is debounced in the UI and resets pagination to page 1.

System architecture

App routes

Tech stack

Public API reference

Three HTTP endpoints are exposed under /api/public/. All support CORS (Access-Control-Allow-Origin: *) for cross-origin use.

{
  "iframeable": true,
  "status": 200,
  "xFrameOptions": null,
  "csp": null
}

GET /api/public/screenshot?url=https%3A%2F%2Fexample.com&width=1440&height=900

Authorization: Bearer <your-token>

{
  "url": "https://example.com",
  "widget": "<script src=\"...\" data-widget-token=\"...\" ...></script>",
  "backdrop": "auto",
  "params": { "utm_source": "newsletter", "ref": "abc" }
}

{
  "id": "abc1234",
  "shortUrl": "https://preview.example.com/s/abc1234",
  "previewUrl": "https://preview.example.com/preview?url=...",
  "deduped": false
}

curl -X POST https://preview.example.com/api/public/shorten \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-token>" \
  -d '{
    "url": "https://bluemachines.ai",
    "widget": "<script src=\"...\" data-widget-token=\"...\" data-agent-id=\"...\" data-agent-profile-id=\"...\"></script>",
    "backdrop": "auto"
  }'

GET  /api/public/widget-proxy/v2/agents/<id>
POST /api/public/widget-proxy/v2/chat/messages

API summary

All endpoints support OPTIONS for CORS preflight. Error responses return JSON: { "error": "description" } with appropriate HTTP status codes (400, 401, 502, etc.). Every request is recorded in the api_logs table — see API logs.

API logs

All public API endpoints write a row to the api_logs Supabase table on every request. View them at /api-logs (linked from the home page header).

Logged fields

UI features

• Paginated table (20 per page) sorted newest first
• Client URL column extracted from request.url
• Success / failed badge and HTTP status code
• View JSON dialog with full request and response objects

Apply the api_logs migration in supabase/migrations/ before using this feature. Logging is fire-and-forget — a logging failure never blocks the API response.

Error handling & edge cases