> 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/sound-through-javascript-function.md).

# Sound through Javascript Function

Plays a custom sound — uploaded once via the WebToNative Dashboard — immediately, triggered directly from your JavaScript. Use it for anything that should feel like a native alert sound: a chat "message sent" ping, a game effect, an order confirmation.

> Before calling this, upload the sound file via the Dashboard — see [Uploading the Sound File](broken://pages/a79c4542382c36e04c0f4f96d71228e854c27913#uploading-the-sound-file-dashboard) on the [OS Notification Sound](broken://pages/a79c4542382c36e04c0f4f96d71228e854c27913) page. `Sound.play` only plays a sound that's already been uploaded; it does not accept a file directly.

> **Platform support:** Android and iOS.

> Looking to have a **remote push notification** play this sound automatically instead? See [Notification Sound](broken://pages/8a9aac3abd127b5cf76c02602b3c8580ead563dd).

***

## JavaScript API Reference

{% tabs %}
{% tab title="Plain Javascript" %}

```javascript
window.WTN.Sound.play("your_sound_name");
```

{% endtab %}

{% tab title="npm" %}

```javascript
import { play } from "webtonative/Sound";

play("your_sound_name");
```

{% endtab %}
{% endtabs %}

**Parameters:**

| Key         | Type     | Required | Description                                                                                                                                                                                                                           |
| ----------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `soundName` | `String` | Yes      | Name of the uploaded sound file, with or without extension (see [Uploading the Sound File](broken://pages/a79c4542382c36e04c0f4f96d71228e854c27913#uploading-the-sound-file-dashboard)). If no extension is given, `.mp3` is assumed. |

This function does not take a `callback` — it is fire-and-forget, with no response to read. If the named sound isn't found or fails to play, it fails **silently** on both platforms — see [Troubleshooting](#troubleshooting) below.

***

## Common Patterns

### Playing a Sound Only on Notification-Relevant Actions

Reserve `Sound.play` for actions that should feel like a native alert — a message received in an open chat, an item added to cart — rather than every UI tap:

```javascript
import { play } from "webtonative/Sound";

function onChatMessageReceived() {
  play("chat_ping");
}

function onOrderConfirmed() {
  play("order_confirmed");
}
```

***

## Troubleshooting

* **Nothing plays, no error in the console:** this is expected if the sound isn't found — both platforms fail silently with no callback to JavaScript. Double-check that the file was uploaded to the correct platform's field on the Dashboard, that you've rebuilt/reinstalled since uploading, and that the name (and extension, if you passed one) matches exactly — see [Uploading the Sound File](broken://pages/a79c4542382c36e04c0f4f96d71228e854c27913#uploading-the-sound-file-dashboard).