Integrations

Embeddable Widget

A floating status badge you can add to any website with a single script tag. Visitors see a compact indicator showing your current system status. Click it to expand a mini status page with component statuses and active incidents -- all without leaving your site.

How it works

The widget script loads asynchronously and renders a small floating badge in the corner of your page. The badge displays overall system status text and a colored indicator dot. Clicking the badge expands a panel showing:

Overall system status and uptime percentage
Each component with its current status
Active incidents with their latest updates

The widget is rendered inside a Shadow DOM, which means your site's CSS cannot affect the widget's appearance, and the widget's styles cannot leak into your page. It auto-refreshes every 60 seconds to keep the displayed status current.

Installation

Copy the embed code from your status page settings (Settings tab), or construct it manually. Add the following script tag before your closing </body> tag:

<script
  src="https://usebeacon.pro/widget/widget.js"
  data-beacon-widget
  data-workspace="your-workspace"
  data-page="your-page"
  data-position="bottom-right"
  defer
></script>

Script attributes

Attribute	Required	Description
`data-beacon-widget`	Yes	Identifies the script tag as a Beacon widget. No value needed.
`data-workspace`	Yes	Your workspace slug (found in your workspace settings or URL)
`data-page`	Yes	Your status page slug
`data-position`	No	`bottom-right` (default), `bottom-left`, `top-right`, or `top-left`
`data-base-url`	No	Override the API base URL. Defaults to the script's origin.
`defer`	No	Recommended. Prevents the script from blocking page rendering.

Widget API response format

The widget fetches data from the following endpoint:

GET https://usebeacon.pro/widget/{workspace}/{page}/status.json

The response is a JSON object with the following structure:

{
  "status": "operational",
  "uptime": 99.97,
  "page": {
    "name": "Acme Cloud",
    "url": "https://usebeacon.pro/status/acme/acme-cloud"
  },
  "components": [
    {
      "name": "API",
      "status": "operational",
      "uptime": 99.99
    },
    {
      "name": "Dashboard",
      "status": "operational",
      "uptime": 99.95
    }
  ],
  "active_incidents": [],
  "branding": true
}

The status field reflects the worst component status: operational, degraded_performance, partial_outage, or major_outage.

Customization

The widget badge displays:

Status text — "All Systems Operational", "Degraded Performance", "Partial Outage", or "Major Outage"
Indicator dot — Green for operational, yellow for degraded, orange for partial outage, red for major outage

Use the data-position attribute to place the badge in any corner of the viewport:

bottom-right — Default. Common for support-style widgets.
bottom-left — Useful if you already have a chat widget in the bottom-right.
top-right — Keeps status visible without scrolling.
top-left — Least common, but available if your layout requires it.

Branding

On the Free plan, the expanded widget panel includes a "Powered by Beacon" link in the footer. This helps others discover Beacon.

On the Pro plan, you can remove the branding entirely. The branding field in the API response controls this: when false, the widget hides the footer link.

CORS

Both the widget JavaScript bundle and the status JSON API serve the following header:

Access-Control-Allow-Origin: *

This means the widget works on any domain without additional configuration. You do not need to whitelist your domain or configure proxy headers.

Caching

Resource	Cache Duration	Notes
`status.json`	30 seconds	Short cache ensures near-real-time status updates
`widget.js`	1 hour	Longer cache for the static JavaScript bundle

The widget itself polls every 60 seconds regardless of cache headers, so status updates typically appear within 60-90 seconds on the embedded widget.

Troubleshooting

If the widget is not appearing on your site, check the following:

Check the browser console

Open your browser's developer tools and look for errors in the Console tab. Common issues include:

404 on widget.js — Verify the script src URL is correct.
404 on status.json — Check that the workspace and page slugs in the data attributes match your actual workspace and page.
CORS errors — Should not occur with the default configuration. If you see CORS errors, verify you are using the correct base URL.

Verify slugs

The workspace and page slugs must exactly match the values in your Beacon dashboard. You can verify by navigating to:

https://usebeacon.pro/widget/{workspace}/{page}/status.json

If this returns a JSON response, the slugs are correct. If it returns a 404, double-check the slug values.

Ensure the page is public

The widget API only serves data for public status pages. If your page is set to private, the API will return a 404 and the widget will not render. Toggle your page to public in the status page settings.