docs: complete the list of paths required for ChatWidget behind auth gateways#570
Merged
sojan-official merged 4 commits intoMay 31, 2026
Merged
Conversation
…ents 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.
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.
rf-leon
changed the title
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.
rf-leon
changed the title
sojan-official
approved these changes
May 31, 2026
sojan-official
left a comment
sojan-official
left a comment
Member
There was a problem hiding this comment.
Thanks for looking into this
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The Enabling ChatWidget for Users section in
restricted-instances.mdxlisted only three paths (/cable,/api/v1/widget/*,/packs). That is incomplete for self-hosted Chatwoot deployments behind auth gateways such as Cloudflare Access, basic auth, ZTNA, or an internal reverse proxy.This PR documents the additional public paths the widget needs to render and load its assets reliably.
Missing paths this documents
/widget/vite/assets/brand-assets/rails/active_storageWhat this change does
/widgetas a required public path./packs,/vite/assets,/brand-assets, and/rails/active_storage./api/v1/widget/*API path, while stored attachment URLs use/rails/active_storage/..../rails/active_storage/...to signed provider/CDN URLs, so visitors must also be able to reach that provider hostname.Validation
/widgetagainstconfig/routes.rbandapp/javascript/sdk/IFrameHelper.jsin the Chatwoot app.app/views/widgets/show.html.erb./brand-assetsfrom installation config and widget branding code.git diff --check.