From 3a0d8f35a82dfd6295934f47f7d5992f9c4273cf Mon Sep 17 00:00:00 2001 From: rf-leon Date: Mon, 4 May 2026 15:15:06 +0200 Subject: [PATCH 1/4] 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/4] 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/4] 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 From 8414c10c85a4510aeb6627696536a6c1d76cc171 Mon Sep 17 00:00:00 2001 From: Sojan Jose Date: Sun, 31 May 2026 16:03:54 +0530 Subject: [PATCH 4/4] docs: clarify widget attachment storage paths --- self-hosted/restricted-instances.mdx | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/self-hosted/restricted-instances.mdx b/self-hosted/restricted-instances.mdx index b79bff00..637becc2 100644 --- a/self-hosted/restricted-instances.mdx +++ b/self-hosted/restricted-instances.mdx @@ -49,10 +49,12 @@ https://yourdomain.com/rails/active_storage - **`/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. +- **`/rails/active_storage`** — stored image and file attachment URLs. Without this, attachments can display as broken images or inaccessible files in the widget. All four paths must be publicly accessible to support the widget fully. +Visitor file uploads are handled through the widget API endpoints covered above. If you use an external storage service such as S3, GCS, Azure Storage, or another S3-compatible provider, Chatwoot still generates `/rails/active_storage/...` URLs first and then redirects the browser to the storage provider's signed URL. In that setup, make sure visitors can also reach the storage provider or CDN hostname. + ### 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: @@ -93,4 +95,4 @@ Implement comprehensive monitoring and logging solutions to swiftly detect and a By following these detailed instructions, your Chatwoot deployment can effectively operate within restricted network environments, ensuring a robust and secure customer support platform. - \ No newline at end of file +