chatwoot / chatwoot/docs

docs: include widget notification audio in restricted-instance asset guidance

Open
#581 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
MDX
Stars
89
Forks
178
PR merge metrics
No merged PRs in 30d

Description

The [restricted-instance guide](https://developers.chatwoot.com/self-hosted/restricted-instances#widget-assets) lists four widget asset paths but omits the notification sound, `/audio/widget/ding.mp3`.

With Chatwoot v4.17.0 behind an authentication gateway, the widget loaded normally but Firefox could not download its sound. The gateway returned a 302 login redirect instead of the MP3, producing a CORS error. Being signed in to the embedding application did not solve this.

The [audio helper](https://github.com/chatwoot/chatwoot/blob/v4.17.0/app/javascript/shared/helpers/AudioNotificationHelper.js) uses `fetch(new Request(resourceUrl))`, whose default credentials mode does not send cross-origin gateway cookies. The [CORS initializer](https://github.com/chatwoot/chatwoot/blob/v4.17.0/config/initializers/cors.rb) already permits `/audio/*` GET/OPTIONS from any origin.

Suggested documentation improvement:

- Include the default widget sound `/audio/widget/ding.mp3` in the asset guidance and update the four-path wording.
- Explain that this static sound must be reachable without an authentication redirect, with its audio content type and CORS response headers preserved. An exact-file exception is sufficient for the default widget tone; exposing arbitrary audio or help-content paths is unnecessary.
- Add a troubleshooting distinction: a sound request redirected to login is a gateway/network failure; browser autoplay restrictions can still apply after a successful download.

Verified on our deployment after adding that exact-file exception: a cookie-free cross-origin request returned 200 `audio/mpeg`, `Access-Control-Allow-Origin: *`, 2,667 bytes, with no redirect. Firefox successfully decoded it through `AudioContext.decodeAudioData`. Neighboring audio paths and protected help content continued to require authentication. No Chatwoot code change or additional origin CORS configuration was needed.

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.