docs: complete the list of paths required for ChatWidget behind auth gateways#570
Open
rf-leon wants to merge 3 commits intochatwoot:mainfrom
Open
docs: complete the list of paths required for ChatWidget behind auth gateways#570rf-leon wants to merge 3 commits intochatwoot:mainfrom
rf-leon wants to merge 3 commits intochatwoot:mainfrom
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
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
1 participant
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.mdxis incomplete. Today it lists three paths (/cable,/api/v1/widget/*,/packs), but a self-hoster following the guide and putting Chatwoot behind any auth gateway (Cloudflare Access, basic auth, ZTNA, internal reverse proxy) hits at least four additional issues before the widget actually works end to end. This PR adds them all.Missing paths this PR documents
/widget/vite/assets/packsalone is no longer enough)/brand-assets/rails/active_storageReference
The Chatwoot SDK builds the iframe URL as
${baseUrl}/widget?website_token=${websiteToken}inIFrameHelper.js. The iframe HTML at/widgetthen references its bundles from/vite/assets/..., the footer logo from/brand-assets/logo_thumbnail.svg, and visitor/agent attachments through/rails/active_storage/....Changes
/widgetas a required public path./packs,/vite/assets,/brand-assets,/rails/active_storage) with a one-line description of each.Context
I hit each of these failures in sequence while migrating a production app from Crisp to self-hosted Chatwoot behind Cloudflare Access. Followed the existing three-path guidance, widget didn't load — found
/widgetin the SDK source. Bypassed it, widget rendered blank — found/vite/assets/*in the iframe HTML. Tested an agent-sent image, visitors saw broken attachments — found/rails/active_storage/*. Eventually noticed the broken logo in the footer — found/brand-assets/*.Documenting them all so the next person can configure every bypass in one pass instead of debugging four distinct symptom reports from users.