ALERT
AI-DRIVEN INTEGRATION

Integrate Alert in your app

Alert adds a hosted, live notification bell to your app. The human provides only three values (Alert URL, server key, app URL). You, the AI agent, do everything else: verify the key, read the app's real layout, place the bell, create the token route, set env, build, and confirm it is live.

Alert origin https://alertqc.compucom.com · version 2025-09 · machine-readable guide (JSON) ↗

The only three things a human provides

ALERT_URLAlert origin, e.g. https://alertqc.compucom.com (QC) or https://alert.compucom.com (prod). Locally http://localhost:3002.
ALERT_SERVER_KEYAlert-managed server key from Company → Connect an App. Server-only; never exposed to the browser.
APP_URLThe URL the integrating app runs on (must match the domain registered for the key), e.g. https://scottyqc.compucom.com or http://localhost:3000.

Success contract — done means all of these pass

verified
POST /api/embed/verify returns valid:true AND ready:true (domain matches).
Proves: The key is real and the app's domain is correctly registered.
token_route
Call the app's own /api/alert-token with a logged-in session to get a token, then POST it to /api/embed/check-token — it must return valid:true with the correct workspace.
Proves: The token route is wired to the right key + session + workspace. THIS is the step most integrations get silently wrong.
bell_live
After loading a page of the running app while logged in, POST /api/embed/verify again — alreadyLive must be true.
Proves: The bell <script> is actually on the page and loading.
notification_received
POST /api/embed/test-notification for the logged-in user, then confirm that exact notificationId appears (in the bell, or via GET /api/notifications).
Proves: The full path works end to end — not just that things connected.

Rules the AI follows

  • NEVER put the API key in the browser. It goes in server env as ALERT_SERVER_KEY (no NEXT_PUBLIC_ prefix).
  • NEVER hardcode a user id. User identity comes from the app's own session via the token route.
  • Read the app's actual layout/header file and place the bell where it belongs — do not guess with regex.
  • Only create/modify the minimum: the token route, the env vars, and one bell <script> line in the layout.
  • Be idempotent: if the token route or bell already exist, do not duplicate them.
  • After changes, run the app's build and fix any errors you introduced before declaring success.
  • DETECT the stack before writing anything: read package.json (and lockfiles / requirements.txt / pyproject.toml / go.mod / Gemfile) to identify the framework, then pick the matching template from tokenRouteTemplates. Do not assume Next.js.
  • MONOREPO / multi-app repos: the APP_URL tells you which app to integrate. Find the package/app that actually serves that domain (check each app's config, ports, or deploy manifest), and make ALL changes inside THAT app's directory — its own layout, its own /api, its own .env. Do not touch sibling apps.
  • READ THE JSON, NOT THE HTTP STATUS. verify, diagnose, and check-token return HTTP 200 even when the result is a failure — the verdict is in the body (valid/ready/healthy fields). Never treat a 200 as success without reading the JSON.
  • ROLLBACK ON FAILURE: if your changes break the build and you cannot fix it within 2 attempts, revert the files you changed and report exactly what failed. Never leave the app in a broken state.
  • DO NOT CLAIM SUCCESS until every item in successContract is satisfied (see below). 'The bell connected' is NOT success — a real test notification must be received.

Drop-in bell snippet

Keyless — the key never touches the browser. Alert identifies your app by its registered domain.

html
<script src="https://alertqc.compucom.com/embed/bell.js"
        data-token-url="/api/alert-token"
        async></script>