From 3a0d8f35a82dfd6295934f47f7d5992f9c4273cf Mon Sep 17 00:00:00 2001 From: rf-leon Date: Mon, 4 May 2026 15:15:06 +0200 Subject: [PATCH 1/3] docs: add /widget iframe path to restricted-instances widget requirements The widget SDK injects an iframe pointing to /widget?website_token=... This path must be publicly reachable for the chat bubble to render, but was missing from the list of required paths in the restricted-instances guide. Self-hosters who put Chatwoot behind any auth gate (Cloudflare Access, basic auth, ZTNA) will see the SDK script load but no chat bubble appear without this bypass. --- self-hosted/restricted-instances.mdx | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/self-hosted/restricted-instances.mdx b/self-hosted/restricted-instances.mdx index 57f7fc80..b0b5486a 100644 --- a/self-hosted/restricted-instances.mdx +++ b/self-hosted/restricted-instances.mdx @@ -45,6 +45,16 @@ https://yourdomain.com/packs Ensure all paths under this directory are accessible to support the widget fully. +### Widget Page + +The Chatwoot SDK loads the chat UI by injecting an iframe whose `src` points to `/widget`. This path must also be publicly accessible for the widget to render: + +``` +https://yourdomain.com/widget +``` + +Without this, the SDK script loads correctly but the iframe fails to load, resulting in a missing chat bubble. This commonly affects deployments behind authentication gateways such as Cloudflare Access, basic auth, or other ZTNA proxies. + ## SMTP Configuration for Emails Proper SMTP setup is essential for managing email communications within restricted networks: From 2d0ef9f79f9b06f0a3e716ecdb56247e39495a2a Mon Sep 17 00:00:00 2001 From: rf-leon Date: Mon, 4 May 2026 15:31:40 +0200 Subject: [PATCH 2/3] docs: add /vite/assets path to ChatWidget required public paths Newer Chatwoot versions migrated the widget UI from Webpack to Vite. The JS and CSS bundles inside the iframe are now served from /vite/assets rather than /packs. Without bypassing this path, the iframe page (/widget) loads but its bundles fail, producing a blank widget. Updates the Widget Assets section to document both /packs (SDK loader) and /vite/assets (iframe bundles), with a note about the migration so operators of older deployments understand both paths matter. --- self-hosted/restricted-instances.mdx | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/self-hosted/restricted-instances.mdx b/self-hosted/restricted-instances.mdx index b0b5486a..87ce6e15 100644 --- a/self-hosted/restricted-instances.mdx +++ b/self-hosted/restricted-instances.mdx @@ -37,13 +37,14 @@ This wildcard approach ensures all necessary widget functionalities such as conv ### Widget Assets -Make sure that static assets required by the ChatWidget are accessible. These are typically served from: +Make sure that all static assets required by the ChatWidget are accessible. The widget uses two asset paths: ``` https://yourdomain.com/packs +https://yourdomain.com/vite/assets ``` -Ensure all paths under this directory are accessible to support the widget fully. +The `/packs` path serves the SDK loader script (`packs/js/sdk.js`) that is embedded into the parent page. The `/vite/assets` path serves the JavaScript and CSS bundles loaded inside the widget iframe (Chatwoot migrated this UI from Webpack to Vite). Both paths must be publicly accessible to support the widget fully. ### Widget Page From 94a5f2b836f750d304c09943c39aa61b83004abc Mon Sep 17 00:00:00 2001 From: rf-leon Date: Mon, 4 May 2026 16:32:43 +0200 Subject: [PATCH 3/3] docs: add /brand-assets and /rails/active_storage to ChatWidget paths MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two more paths the widget pulls from that aren't currently documented: - /brand-assets serves the installation logo shown in the widget footer. - /rails/active_storage serves image and file attachments — both visitor uploads and media the agent sends back. Without this bypassed, agent- sent images display as broken on the visitor side because their HTTP GETs are intercepted by the auth gateway. Restructures the Widget Assets section to list all four paths the widget loads from, with a one-line description of what each serves, so the next operator behind an auth gateway can configure all bypasses in one pass rather than discovering them sequentially through user reports. --- self-hosted/restricted-instances.mdx | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/self-hosted/restricted-instances.mdx b/self-hosted/restricted-instances.mdx index 87ce6e15..b79bff00 100644 --- a/self-hosted/restricted-instances.mdx +++ b/self-hosted/restricted-instances.mdx @@ -37,14 +37,21 @@ This wildcard approach ensures all necessary widget functionalities such as conv ### Widget Assets -Make sure that all static assets required by the ChatWidget are accessible. The widget uses two asset paths: +Make sure that all static and media assets the widget loads are accessible. The widget pulls from four paths: ``` https://yourdomain.com/packs https://yourdomain.com/vite/assets +https://yourdomain.com/brand-assets +https://yourdomain.com/rails/active_storage ``` -The `/packs` path serves the SDK loader script (`packs/js/sdk.js`) that is embedded into the parent page. The `/vite/assets` path serves the JavaScript and CSS bundles loaded inside the widget iframe (Chatwoot migrated this UI from Webpack to Vite). Both paths must be publicly accessible to support the widget fully. +- **`/packs`** — the SDK loader script (`packs/js/sdk.js`) embedded into the parent page. +- **`/vite/assets`** — JavaScript and CSS bundles loaded inside the widget iframe. Chatwoot migrated this UI from Webpack to Vite, so older guides referring only to `/packs` are incomplete for newer deployments. +- **`/brand-assets`** — installation-level branding (logo, favicon) shown inside the widget. +- **`/rails/active_storage`** — image and file attachments. Used for both visitor uploads and any media the agent sends back. Without this, attachments display as broken images on the visitor side. + +All four paths must be publicly accessible to support the widget fully. ### Widget Page