> For the complete documentation index, see [llms.txt](https://docs.webtonative.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.webtonative.com/javascript-apis/os-notification-sound.md).
# Custom Sound Feature
Play your own uploaded sounds on demand from JavaScript, pair them with haptic feedback, and reuse them for push notifications across Android and iOS.
Lets your app play a **custom sound** — uploaded once via the **WebToNative Dashboard** — instead of relying only on the device's default sound. This page covers the shared prerequisite (uploading the file) and how the feature fits together; each way of actually playing the sound has its own dedicated page:
| Page | What it covers |
| ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Sound.play](broken://pages/aef35d04cc88cca740f664b6e5e4943c32bbd1c1) | Play the uploaded sound immediately, triggered directly from your JavaScript. |
| [Haptics.trigger](broken://pages/89f43d502aa7e1fe7c9de6cd1403e6abd450b543) | Play the uploaded sound alongside a haptic vibration effect, in one call. |
| [Notification Sound](broken://pages/ffd7c158fb69bb714964306c45c5d0bcc8fa05b7) | Have a **remote push notification** play the uploaded sound automatically when it arrives (via [OneSignal](broken://pages/8edb3d376c88b810fb53d342c2b09f573456b9f0) or [FCM](broken://pages/0f00cc955f4330b7803163fd1c6625444c06e04e)). |
> You'll need to import the javascript file in your website before starting from this [link](https://docs.webtonative.com/javascript-apis/getting-started).
> **Platform support:** Android and iOS.
***
## How It Works
One uploaded sound file can be used in all three places above, and all three reference it **by the same name**:
1. **`Sound.play(soundName)`** — plays it immediately from JavaScript (e.g. a chat "message sent" ping, a game effect). See [Sound.play](broken://pages/aef35d04cc88cca740f664b6e5e4943c32bbd1c1).
2. **`Haptics.trigger({ effect, soundName })`** — plays it alongside a haptic vibration effect, in one call. See [Haptic Feedback](broken://pages/89f43d502aa7e1fe7c9de6cd1403e6abd450b543).
3. **A remote push notification** — OneSignal or FCM tells the OS to play it automatically when a push arrives. See [Notification Sound](broken://pages/ffd7c158fb69bb714964306c45c5d0bcc8fa05b7).
The sound file itself is never sent from your JavaScript or from a push payload — only its **name** is. It must already be uploaded to your app via the Dashboard (below) before you reference it from any of the three places above.
***
## Uploading the Sound File (Dashboard)
Go to your **WebToNative Dashboard → Add-ons → Notification → OS Notification Sound** and upload the sound file under the platform's sound setting. Android and iOS each have their **own separate upload field** — uploading for one platform does not make the file available on the other, so upload the same audio to both fields if you want consistent behavior across platforms.
* **Reference name:** the name you pass to `Sound.play` / `soundName` is derived from the uploaded file's name, minus its extension.
* **Format:** only `.mp3` and `.wav` files can be uploaded — these are the only supported formats on both platforms.
* **Extension:** `.mp3` is the default — if you call `Sound.play("your_sound_name")` **without an extension**, `.mp3` is assumed automatically, so you don't need to pass anything if you uploaded an `.mp3` file. If you uploaded a `.wav` file, you must pass the extension explicitly — `Sound.play("your_sound_name.wav")` — or the lookup will assume `.mp3` and fail to find it.
> Changes take effect on your app's next build — if you're testing on a device already running an older build, rebuild/reinstall after uploading a new or changed sound file.
***
## Frequently Asked Questions
Do I need to enable an add-on on the WebToNative Dashboard to use this?
Yes — you need to add the **OS Notification Sound** add-on from WebToNative. Once it's added, you can upload your sound file under **OS Notification Sound**, in the **Notification** section of **Add-ons**, for each platform you want it on. The JavaScript bridge works as soon as it's imported as usual.
Can I use the same sound file for `Sound.play`, `Haptics.trigger`, and a push notification?
Yes — upload it once per platform via the Dashboard, and reference it by the same name from all three. For the push notification side, the platform-specific dashboard/API fields have their own naming conventions (extension required on iOS, omitted on Android) — see [Notification Sound](broken://pages/ffd7c158fb69bb714964306c45c5d0bcc8fa05b7).
What audio formats are supported?
Only `.mp3` and `.wav` — these are the only formats you can upload, on either platform. `.mp3` is assumed by default if you don't pass an extension in `Sound.play`; for `.wav`, pass the extension explicitly.
Why did I get `PERMANENTLY_BLOCKED` or no sound after asking for notification permission?
That's unrelated to this page — `Sound.play`/`Haptics.trigger` play immediately from JavaScript and don't require notification permission at all. Notification permission only affects whether the OS shows/plays a *remote push* automatically; see [Permission](broken://pages/dc06f6a344d650fd8c86c6907f98a575f7e8862b) for permission handling, and [Notification Sound](broken://pages/ffd7c158fb69bb714964306c45c5d0bcc8fa05b7) for push-specific sound setup.