Widget configuration

Most of what you'd want to configure lives in the dashboard, where it applies to every site embedding the project without a redeploy. The script tag handles the rest.

Script attributesCopy Anchor Link

<script
  src="https://www.annot8.app/widget.js"
  data-project-id="pj_xxxxxxxxxxxx"
  data-convex-url="https://your-deployment.convex.cloud"
  data-theme="auto"
  data-label="Feedback"
  async
></script>

Every value is validated. A project key in the wrong shape, a backend URL that isn't HTTPS (except localhost and 127.0.0.1), a URL carrying credentials, or an unrecognised theme is discarded rather than passed through.

The JSON form is equivalent, and useful when a template makes long attribute lists awkward:

<script
  src="https://www.annot8.app/widget.js"
  data-project-id="pj_xxxxxxxxxxxx"
  data-config='{"convexUrl":"https://your-deployment.convex.cloud","theme":"dark","label":"Report issue"}'
  async
></script>

What's configured in the dashboard insteadCopy Anchor Link

data-label is the one place the script tag wins: when present it overrides the dashboard label, which is handy when one project serves several surfaces.

Keyboard shortcutsCopy Anchor Link

Single-letter shortcuts are off by default, because keys pressed on your page belong to your site. To turn them on, add data-shortcuts="true" to the script tag, or pass shortcuts: true in data-config or to init:

<script
  src="https://www.annot8.app/widget.js"
  data-project-id="pj_xxxxxxxxxxxx"
  data-convex-url="https://your-deployment.convex.cloud"
  data-shortcuts="true"
  async
></script>

Esc works whether or not shortcuts are on. The letter keys are ignored while someone is typing in a field, and when Ctrl, Cmd, Alt, or Shift is held.

Runtime APICopy Anchor Link

The loader exposes an Intercom-style command function. Calls made before the script finishes loading are queued and replayed.

// Re-initialise, e.g. once your consent manager grants analytics consent.
window.Annot8("init", {
  projectId: "pj_xxxxxxxxxxxx",
  convexUrl: "https://your-deployment.convex.cloud",
  dashboardUrl: "https://www.annot8.app",
  theme: "dark",
  analyticsConsent: true,
});

// Record a custom analytics event (requires Analytics enabled and consented).
window.Annot8("track", "signup_clicked", { plan: "pro" });

// Record a conversion, with an optional value.
window.Annot8("trackConversion", "purchase", 49.99);

The same methods are available directly as Annot8.init(...), Annot8.track(...), and Annot8.trackConversion(...).

Calling track or trackConversion before Analytics is enabled and consented is a no-op — nothing is transmitted and nothing throws, so you can leave the calls in place unconditionally.

Withdrawing analytics consentCopy Anchor Link

Re-initialise with consent off to stop the tracker:

window.Annot8("init", {
  projectId: "pj_xxxxxxxxxxxx",
  convexUrl: "https://your-deployment.convex.cloud",
  analyticsConsent: false,
});

Your consent manager should also clear the host-page keys, each suffixed with the project id: ca_visitor_id:<projectId> in localStorage, and ca_session_id:<projectId>, ca_session_start:<projectId>, and ca_session_activity:<projectId> in sessionStorage.

Keeping sensitive content out of screenshotsCopy Anchor Link

Annot8 already masks every input, textarea, select, content-editable region, iframe, video, and anything marked [data-private] in generated screenshots. For anything else, mark it:

<!-- Obscured in the screenshot, but the layout is preserved -->
<section data-annot8-redact>Private account details</section>

<!-- Omitted from the screenshot render entirely -->
<div data-annot8-ignore>...</div>

You can also declare up to 25 selectors before the widget loads:

<script>
  window.annot8RedactSelectors = [
    ".customer-profile",
    "[data-sensitive]",
    "#payment-summary",
  ];
</script>

Annot8's screen recording never requests microphone audio. A voice note is always a separate, deliberate action.

Live chatCopy Anchor Link

When Live chat is enabled in Settings → Features, the panel gains a Messages tab. Welcome message, email requirement, availability hours, and AI auto-replies are all configured in the dashboard — see Live chat.

Remember that on a production host the whole panel is hidden unless Show widget in production is on.

NextCopy Anchor Link