---
title: "Migrating to knowledge base widget V2"
slug: "migrating-to-knowledge-base-widget-v2"
description: "Learn about Document360's Widget V2 updates, including security enhancements, iframe integration, and necessary actions for a smooth transition."
updated: 2026-08-23T07:33:48Z
published: 2026-08-23T07:33:48Z
canonical: "docs.document360.com/migrating-to-knowledge-base-widget-v2"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.document360.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrating to knowledge base widget V2

Document360 has rolled out an updated architecture for the Knowledge base widget, referred to as Widget V2. This article explains what's changed, what action you may need to take, and how to get support during the transition.

> [!NOTE]
> NOTE
> 
> The Widget V2 rollout is being performed in phases across environments. If your widget has not yet migrated to V2, this article will not yet apply to your implementation. Contact Document360 support if you're unsure which version your widget is currently running.

---

## What's changing in widget V2

The Knowledge base widget has been modernized from a vanilla JavaScript implementation to an Angular-based application, delivered through a secure, cross-origin iframe hosted by Document360.

Your existing embed snippet and `widget.js` URL remains unchanged; most customers will not need to update their embed code. However, the underlying way the widget renders and communicates with your page has changed:

- The widget content now loads inside a dedicated iframe (`#document360-widget-iframe`) instead of rendering directly within your host page.
- Direct access to the widget's internal DOM (for example, via `iframe.contentDocument`) is no longer supported, due to standard browser same-origin restrictions.
- Widget interactions (opening, closing, toggling) must now go through a supported `postMessage API` instead of direct script manipulation.

This change was introduced as part of our Widget V2 modernization effort to provide:

- Improved security isolation
- Better maintainability and scalability
- Alignment with modern widget embedding practices
- Reduced CSP requirements over time

---

## Do I need to make any changes?

| Your current setup | Action needed |
| --- | --- |
| Standard embed using the default Document360 script, no custom DOM manipulation | No action needed. Your widget will continue to work as-is |
| You use a custom button/trigger to open or close the widget via direct DOM access or custom JavaScript | Update to the `postMessage`` API` (see below) |
| You customized widget appearance via host-page CSS or JavaScript targeting widget internals | Move customizations to the widget's built-in **Custom CSS** / **Custom JavaScript** settings in Document360 |
| Your Content Security Policy (CSP) restricts `frame-src` | Update your CSP to allow the Document360 widget domain (see below) |

---

## Updating custom triggers to use the postMessage API

If you previously opened or closed the widget using a custom button and direct script access, update your implementation as follows:

```xml
<button type="button" id="d360-toggle">Help</button>

<!-- Document360 knowledge base widget start -->
<script>
  (function (w,d,s,o,f,js,fjs) {
    w['JS-Widget']=o;w[o] = w[o] || function () { (w[o].q = w[o].q || []).push(arguments) };
    js = d.createElement(s), fjs = d.getElementsByTagName(s)[0];
    js.id = o; js.src = f; js.async = 1; fjs.parentNode.insertBefore(js, fjs);
  }(window, document, 'script', 'mw', '<Your CDN URL>'));
  mw('init', { apiKey: '<Your API Key>' });
</script>
<!-- Document360 knowledge base widget end -->

<script>
  document.getElementById('d360-toggle').addEventListener('click', function () {
    var widgetIframe = document.getElementById('document360-widget-iframe');
    if (widgetIframe && widgetIframe.contentWindow) {
      widgetIframe.contentWindow.postMessage(
        { type: 'd360:api', method: 'show', params: {} },
        '*'
      );
    }
  });
</script>
```

Supported `method` values:

| Method | Behavior |
| --- | --- |
| `show` | Opens the widget |
| `hide` | Closes the widget |
| `toggle` | Opens if closed, closes if open |

> [!NOTE]
> NOTE
> 
> - Replace d360-toggle with the ID of your own trigger element.
> - The iframe ID document360-widget-iframe is fixed and must not be renamed — it's the supported integration point.
> - The widget automatically manages its own size and visibility. Do not attempt to manipulate the iframe directly.

Alternative: using the `mw()` command directly

As a simpler alternative to the postMessage approach above, you can call the public `mw()` command directly. The loader handles the iframe communication internally, so you don't need to reference `document360-widget-iframe` or construct a postMessage payload yourself.

```xml
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Document360 Knowledge Base Widget V2 — Host Page Sample</title>
</head>
<body>
  <p>Control the widget with the public <code>mw()</code> API:</p>
  <p>
    <button onclick="mw('show')">Show</button>
    <button onclick="mw('hide')">Hide</button>
    <button onclick="mw('toggle')">Toggle</button>
  </p>

  <!-- Document360 knowledge base widget start -->
  <script>
    (function (w, d, s, o, f, js, fjs) {
      w['JS-Widget'] = o;
      w[o] = w[o] || function () { (w[o].q = w[o].q || []).push(arguments); };
      js = d.createElement(s); fjs = d.getElementsByTagName(s)[0];
      js.id = o; js.src = f; js.async = 1;
      fjs.parentNode.insertBefore(js, fjs);
    }(window, document, 'script', 'mw', '<Your CDN URL>'));

    mw('init', {
      apiKey: '<Your API Key>',
    });
  </script>
  <!-- Document360 knowledge base widget end -->
</body>
</html>
```

> [!NOTE]
> NOTE
> 
> If your postMessage trigger compiles correctly, uses the exact iframe ID and payload shown above, and still does not open the widget, this is usually a timing or page-origin issue rather than an incorrect payload. Switching to mw('show') resolves both without further changes to your trigger code.

Supported `mw()` commands: `mw('show')`, `mw('hide')`, `mw('toggle')` — these correspond to the same `show`/`hide`/`toggle` behavior as the postMessage method above.

> [!NOTE]
> NOTE
> 
> Use the CDN URL and API key shown in your own widget's embed code (Connections > Knowledge base widget > Edit > Configure & connect) rather than the placeholder values shown here.

---

## Content Security Policy (CSP) requirements

> [!NOTE]
> NOTE
> 
> These CSP requirements apply only if your site already enforces a Content Security Policy. If your site does not have a CSP configured, no additional configuration is needed for the widget to function.

Since the widget now loads inside an iframe, your CSP must explicitly allow the Document360 widget domain as a frame source:

`frame-src Domain in your CDN URL` eg: https://cdn.us.document360.io If your data centre is in the EU, then CDN URL is: https://cdn.document360.io If your data centre is in the US, then CDN URL is: https://cdn.us.document360.io

- Widget V1 is required `unsafe-eval` in your `script-src` directive. This is **no longer required** under Widget V2 — you can remove it if it was added solely for the widget.
- `style-src 'unsafe-inline'` is still required.

> [!WARNING]
> If your CSP does not allow this, the widget icon or content will fail to load, and you may see errors in the browser console referencing blocked frame sources or failed widget API requests.

For region-specific domains, refer to [CSP and Whitelisting guidelines for the Document360 widget](/help/docs/csp-guidelines-for-document360-widget).

---

## Migrating host-page customizations

If you previously customized the widget's appearance using CSS or JavaScript on your own webpage (targeting widget elements directly), this approach is no longer reliable under Widget V2, since widget content is isolated inside a cross-origin iframe.

Instead, configure equivalent customizations directly within Document360:

1. Navigate to **Connections > Knowledge base widget.**
2. Hover over the desired widget and click Edit.
3. Use the Custom CSS and Custom JavaScript tabs to apply your styling and behavior changes.

---

## JWT authentication and Widget V2

If your widget uses JWT authentication, the `authUrl` integration and your existing JWT configuration remain unchanged under Widget V2. No changes are required to your authentication endpoint or client secret as a result of this migration.

> [!NOTE]
> NOTE
> 
> Widget V2 migration and JWT authentication failures are separate, unrelated issues. If your widget is failing to authenticate (for example, errors at the token endpoint, or articles failing to load with 401/404 responses), this is typically caused by a JWT configuration issue, most commonly, a client secret mismatch — and not by the V2 architecture change. See [Configuring JWT for the knowledge base widget](/help/docs/configuring-jwt-for-the-knowledge-base-widget) or authentication-specific troubleshooting before assuming it's related to this migration.

> [!WARNING]
> Projects with multiple widgets
> 
> If your project has multiple widgets using JWT authentication, be aware that the client secret is shared across all of them. Regenerating it from any widget, including a test widget, affects all JWT-enabled widgets in the project immediately. See [Troubleshooting knowledge base widget issues > JWT authentication issues](/help/docs/troubleshooting-knowledge-base-widget-issues#jwt-authentication-issues) for details.

---

## Requesting a temporary rollback

If you need more time to update your implementation, you can request a temporary rollback to the previous widget version while you complete your migration.

To request a rollback:

1. Contact Document360 support through email support@document360.com with your **Project ID** and the names of the widgets you'd like reverted.
2. Confirm whether you'd like all widgets in the project rolled back, or specific ones only.
3. Once completed, your widget(s) will resume functioning on the previous version immediately, without requiring any changes on your end.

> [!NOTE]
> NOTE
> 
> If your project has multiple widgets (for example, a live widget and a separate test widget), you can choose to keep one on Widget V2 for testing while rolling back the other, these are independent per widget.

---

## Troubleshooting

| Symptom | Likely cause | What to do |
| --- | --- | --- |
| The widget icon does not appear on the page | Your Content Security Policy (CSP) is blocking the widget iframe. | Update your `frame-src` CSP directive to allow the appropriate Document360 CDN: - EU data center: `https://cdn.document360.io` - US data center: `https://cdn.us.document360.io` |
| Custom open/close button no longer works | Custom trigger uses direct DOM access instead of the postMessage API | Update your trigger to use `postMessage` as shown above |
| Widget loads, but previous CSS customizations no longer apply | Host-page CSS can no longer target widget internals | Move customizations to the widget's Custom CSS settings in Document360 |
| Console shows `SecurityError` or same-origin related errors | Code attempting to access the widget iframe's DOM directly | Remove direct DOM access; use the postMessage API instead |
| Widget fails to load articles (404 errors from widget APIs) | Typically unrelated to V2 — check JWT/authentication configuration | See [Configuring JWT for the knowledge base widget](/help/docs/configuring-jwt-for-the-knowledge-base-widget) |
| Custom script that automatically switches from the Page Help tab to the Knowledge Base tab no longer works | The script toggles CSS classes on the Page Help and Knowledge Base sections to show and hide them. In Widget V2, only the currently active tab's content is loaded into the page at all, so there is nothing for the script to find or toggle. | Update the script to click the Knowledge Base tab element directly, instead of toggling its classes. See [Keep the Knowledge Base tab active if the widget switches to Page Help](/help/docs/customizing-the-kb-widget-using-custom-css-javascript#keep-the-knowledge-base-tab-active-if-the-widget-switches-to-page-help) in Customizing the Knowledge Base widget using Custom CSS/JavaScript for a ready-to-use script. Note: Widget V2 loads only the active tab's content on demand. Scripts that rely on both the Page Help and Knowledge Base sections being present in the page at the same time, and that switch between them by adding or removing CSS classes, will not work reliably in V2. Simulating a click on the tab element is currently the supported workaround. There is currently no dedicated postMessage or mw() command for switching tabs directly; the supported commands are limited to show, hide, and toggle for opening and closing the widget. |
| Custom postMessage trigger works when tested locally but fails intermittently in production, with no console error | A direct postMessage call can be silently dropped in two situations: 1. Timing: the message is sent before the widget iframe has finished loading, so there is nothing listening yet. 2. Page origin: the trigger code lives in a nested iframe or on a different subdomain than where the widget snippet is installed, so the widget does not accept the message. Both failures happen without any error in the browser console, which can make them look like a widget or integration bug. | Switch the trigger to the supported mw('show') command instead of constructing your own postMessage payload. The mw() loader waits for the iframe to finish loading and handles the messaging internally, so it is not affected by either the timing or the page-origin issue. |

---

## Next steps

- Review your current widget implementation for any custom JavaScript that directly accesses widget internals.
- Update your CSP if required.
- Move host-page customizations into the widget's Custom CSS/JS settings.
- Contact Document360 support if you need a temporary rollback or have questions about your specific implementation.