Install the Widget in Mintlify

Mintlify can load custom JavaScript from your docs repository. Use that to add the Woes widget once, then let it appear across every page in your documentation site.

The widget uses a browser-safe public widget key such as trovw_..., trovw_agent_..., or woesw_.... Do not use a woesk_ REST API key, workspace secret, or widget identity secret in browser code.

Before You Start

You need:

Access to your Mintlify docs repository.
A Woes workspace or agent widget key from Settings → Keys.
The production widget loader: https://woes.dev/widget.js.

Use a workspace widget key when every docs visitor should route to the default agent. Use an agent widget key when your docs site should route visitors to a specific docs-focused agent.

AI Agent Install Prompt

If you want Codex, Cursor, Claude Code, or another coding agent to install the widget for you, copy this prompt and run it from your Mintlify docs repository.

Recommended Install

Create a JavaScript file in the root of your Mintlify docs content directory, next to docs.json or mint.json. For example, create woes-widget.js:

(function () {
  if (window.__woesDocsWidgetInstalled) return;
  window.__woesDocsWidgetInstalled = true;

  window.Woes =
    window.Woes ||
    function () {
      (window.Woes.q = window.Woes.q || []).push(
        Array.prototype.slice.call(arguments),
      );
    };

  var script = document.createElement("script");
  script.src = "https://woes.dev/widget.js";
  script.setAttribute("data-public-key", "YOUR_WIDGET_PUBLIC_KEY");

  document.head.appendChild(script);
})();

Replace YOUR_WIDGET_PUBLIC_KEY with the public widget key copied from your own Woes workspace or agent.

Public widget keys are designed to be embedded in browser pages. They identify the widget workspace or agent, but they are not REST API keys and do not prove visitor identity.

Deploy The Change

Commit and push the file to the Git repository connected to Mintlify.

git add woes-widget.js
git commit -m "Add Woes docs widget"
git push

Mintlify will rebuild the docs site from the pushed commit. After the deploy finishes, open the public docs site and confirm the Woes launcher appears.

Direct Snippet

If your Mintlify setup supports adding a raw script directly, use the same snippet Woes provides in Settings → Channels → Live chat:

<script
  src="https://woes.dev/widget.js"
  data-public-key="YOUR_WIDGET_PUBLIC_KEY">
</script>

The JavaScript-file approach is usually easier to maintain because it keeps the widget install in one reusable file.

Identify Signed-In Readers

Most public documentation sites can run anonymously. If your Mintlify docs are behind authentication and you can safely provide reader identity, call window.Woes("identify", ...) after your application receives identity from a backend endpoint. Unsigned identity can help operators recognize a reader, but it is not trusted identity proof.

window.Woes("identify", {
  email: "reader@example.com",
  name: "Ada Lovelace",
  company: "Example API Co",
  id: "user_123",
});

For account-specific history or higher-trust routing, use signed identity. In Woes, open Settings → Security, select the agent widget key installed on Mintlify, then use Copy prompt for AI install if you want a coding assistant to wire the server-side HMAC or JWT endpoint. Verified identity requires a server endpoint outside the Mintlify static docs repo unless your Mintlify site is backed by an authenticated application. That endpoint should return Cache-Control: no-store and should never expose WOES_WIDGET_IDENTITY_SECRET. Browser code should retry window.Woes("identify", ...) after login/session load, when widget.js loads, on window focus, and when the page becomes visible again. Repeating the same verified identity is safe.

Generate HMAC proofs or JWTs only on your backend. Never place widget identity secrets, REST API keys, workspace secrets, or customer-private data in the Mintlify repository.

Test The Install

After Mintlify deploys:

Open the docs site in a private browser window.
Confirm the Woes launcher appears.
Open the widget and send a test question.
In Woes, open Inbox and confirm the conversation arrives.
If you used an agent widget key, confirm the conversation is labeled with the expected agent.
If you used signed identity, confirm Woes shows the reader email/name and identity_source of widget-token.

Troubleshooting

Problem	Check
Launcher does not appear	Confirm `woes-widget.js` is in the Mintlify content root and was pushed.
Browser console shows a script error	Confirm the script URL is exactly `https://woes.dev/widget.js`.
Conversation goes to the wrong agent	Use the correct agent widget key from Agents or Settings → Keys.
Reader appears anonymous	Confirm the backend identity endpoint exists, the server-only secret is configured, and identify is retried after widget/auth lifecycle events.
Widget key is rejected	Confirm you used a public widget key, not a `woesk_` REST API key.

​Install the Widget in Mintlify

​Before You Start

​AI Agent Install Prompt

​Recommended Install

​Deploy The Change

​Direct Snippet

​Identify Signed-In Readers

​Test The Install

​Troubleshooting

​Related Pages

Install the Widget in Mintlify

Before You Start

AI Agent Install Prompt

Recommended Install

Deploy The Change

Direct Snippet

Identify Signed-In Readers

Test The Install

Troubleshooting

Related Pages