> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Notification sounds

> Add custom notification sounds to iOS, Android, Huawei, and Amazon apps — including file formats, SDK setup, and API parameters.

Custom sounds let you provide a more unique, branded experience in your app. You can add a custom sound to every notification or only to certain types. For example, a social app might play a distinct sound only for direct messages to differentiate them from system notifications.

<Warning>
  For mobile apps only. Custom sounds are not supported on web push.
</Warning>

## Setup

### Create sound files

Create sound files following the platform requirements below. If the device cannot find the specified file or the file format is unsupported, it falls back to the default system notification sound.

<Note>
  Keep sound filenames lowercase since some platforms ignore uppercase letters for sound files. Instead of `AwesomeSound.wav` use `awesomesound.wav` or `awesome_sound.wav`.
</Note>

| Platform | Extensions            | Notes                                                                                                    |
| -------- | --------------------- | -------------------------------------------------------------------------------------------------------- |
| iOS      | `.wav` `.aiff` `.caf` | Sounds must be encoded as Linear PCM, MA4 (IMA/ADPCM), µLaw, or aLaw. Must be less than 30 seconds.      |
| Android  | `.wav` `.mp3` `.ogg`  | Recommended length less than 30 seconds. Keep file size small, large files may not play on some devices. |
| Huawei   | `.wav` `.mp3` `.wma`  | Recommended length less than 30 seconds. Keep file size small, large files may not play on some devices. |
| Amazon   | `.wav` `.mp3` `.ogg`  | Recommended length less than 30 seconds. Keep file size small, large files may not play on some devices. |

### Add sound files to your app

Sound files must be included as resources within your app. External URLs are not supported.

<Tabs>
  <Tab title="iOS">
    Add sound files to the appropriate location in your Xcode project depending on your SDK.

    | SDK            | Folder                                                                                                                                                   |
    | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | iOS Native     | Add files to the Xcode project root. Make sure **Add to targets** is selected when adding files so they are automatically added to the bundle resources. |
    | Cordova, Ionic | Add files to `Resources` directory within the Xcode project in `<project-root>/platforms/ios/project-name.xcodeproj`.                                    |
    | Unity          | Add sounds anywhere in your Unity project, build your project, and then move those sounds to the Xcode project root.                                     |
  </Tab>

  <Tab title="Android, Huawei, and Amazon">
    Add sound files to the appropriate folder in your project depending on your SDK. **If the folder does not exist, create it.**

    | SDK                            | Folder                                                                                                                                                                    |
    | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | Android, Huawei, Amazon Native | `res/raw`                                                                                                                                                                 |
    | React Native                   | `<project-root>/android/app/src/main/res/raw`                                                                                                                             |
    | Cordova                        | `<project-root>/platforms/android/res/raw/`                                                                                                                               |
    | Ionic                          | `/android/app/src/main/res/raw/`                                                                                                                                          |
    | Unity                          | `Assets/Plugins/Android/OneSignalConfig/res/raw` *NOTE: Your sound and icon file names must be lowercase and can't contain anything else except underscores and numbers.* |
    | Flutter                        | `main/res/raw`                                                                                                                                                            |
    | .NET                           | `<project-root>/Platforms/Android/Resources/raw/`                                                                                                                         |
  </Tab>
</Tabs>

### Send notifications

<Tabs>
  <Tab title="iOS">
    Include the file extension when referencing the sound resource (e.g., `explode_sound.wav`). Set the sound in the dashboard when sending push messages or use the [Create Notification](/reference/create-message) API `ios_sound` property.

    For no sound, pass `nil` to the **Sound** field.

    <Frame caption="Setting a custom sound for iOS in the OneSignal dashboard.">
      <img src="https://mintcdn.com/onesignal/6tscVAtiSqz353kV/images/docs/a05af7e-Screenshot_2023-02-28_at_3.16.55_PM.png?fit=max&auto=format&n=6tscVAtiSqz353kV&q=85&s=9d33c9837ac9f67b0d6c6a7a87d03212" alt="OneSignal dashboard push composer showing the iOS Sound field" width="423" height="606" data-path="images/docs/a05af7e-Screenshot_2023-02-28_at_3.16.55_PM.png" />
    </Frame>
  </Tab>

  <Tab title="Android, Huawei, and Amazon">
    Android 8+ introduced [Notification Categories](./android-notification-categories) which must be set up to customize notification sounds. OneSignal uses the sound configured in the Notification Channel for all versions of Android.

    In **Settings > Push & In-App > Android Notification Channels**, create the group and channel.

    <Frame caption="Create a notification channel.">
      <img src="https://mintcdn.com/onesignal/tc0EvmtSSX56SX0c/images/docs/8f39237-Screenshot_2023-02-28_at_3.11.52_PM.png?fit=max&auto=format&n=tc0EvmtSSX56SX0c&q=85&s=b18a97c1706dde194bd4e5c13cd9f593" alt="OneSignal dashboard showing the notification channel creation form" width="877" height="487" data-path="images/docs/8f39237-Screenshot_2023-02-28_at_3.11.52_PM.png" />
    </Frame>

    * Set **Importance** to "Urgent" or "High" to play sound.
    * Set **Sound** to "Default" or "Custom" based on your needs. **Do not** add the file extension when referencing the sound resource (e.g., `cat_meow_sound`).
    * For no sound, set **Importance** to "Urgent" or "High" and **Sound** to "Off". Or set **Importance** to "Medium" or "Low" for no sound.

    <Frame caption="Setting the sound for a notification channel.">
      <img src="https://mintcdn.com/onesignal/KSCNwSpBCNSQ8xdF/images/docs/f7950b6-Screenshot_2023-02-28_at_3.11.03_PM.png?fit=max&auto=format&n=KSCNwSpBCNSQ8xdF&q=85&s=88d88df41d360b190b4c083709e8119c" alt="OneSignal notification channel settings showing sound configuration options" width="429" height="498" data-path="images/docs/f7950b6-Screenshot_2023-02-28_at_3.11.03_PM.png" />
    </Frame>

    You can then set the category name in the dashboard when sending push messages or use the [Create Notification](/reference/create-message) API `android_channel_id` and `huawei_channel_id` properties. The sound set in the category works for all Android versions.

    <Frame caption="Selecting the notification category in the push composer.">
      <img src="https://mintcdn.com/onesignal/jFWn5xzleD8du3j6/images/docs/5e8625c-Screenshot_2023-02-28_at_3.15.19_PM.png?fit=max&auto=format&n=jFWn5xzleD8du3j6&q=85&s=c02f9a68fcb73b913a1de93e01d0f4aa" alt="OneSignal push composer showing the notification category dropdown" width="423" height="517" data-path="images/docs/5e8625c-Screenshot_2023-02-28_at_3.15.19_PM.png" />
    </Frame>
  </Tab>

  <Tab title="REST API">
    You can send notifications with sounds via the REST API using the appropriate parameter for each platform. See the [Create Notification API reference](/reference/push-notification) for full details.

    | Platform | API Parameter                                                                                                                                                                                                                | Details                                                                                        |
    | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
    | iOS      | `ios_sound`                                                                                                                                                                                                                  | Include file extension. Example: `"ios_sound": "explode_sound.wav"`. For no sound, pass `nil`. |
    | Android  | `android_channel_id` — Use if you created the channel in the OneSignal dashboard via [Notification Categories](./android-notification-categories). `existing_android_channel_id` — Use if you created the channel elsewhere. | Using [Notification Categories](./android-notification-categories) is recommended.             |
    | Huawei   | `huawei_channel_id` — Use if you created the channel in the OneSignal dashboard via [Notification Categories](./android-notification-categories). `huawei_existing_channel_id` — Use if you created the channel elsewhere.   | Using [Notification Categories](./android-notification-categories) is recommended.             |
    | Amazon   | `adm_sound`                                                                                                                                                                                                                  | Do not include file extension. Example: `"adm_sound": "explode_sound"`.                        |
  </Tab>
</Tabs>

<Warning>
  If you recently added a sound resource to your app, consider waiting a few days before sending notifications that use it. It can take days or weeks for most users to update to the latest app version containing the new sound file.

  If a user has an older version without the sound resource and receives a notification referencing it, they hear only the default system notification sound.
</Warning>

***

## FAQ

### Can I set a default sound?

Use a [Template](./templates) that references the sound and/or Android Notification Channel. Every notification sent with that template uses the configured sound automatically.

### Can I send different notification sounds to different users?

The `ios_sound` and `android_channel_id` parameters are request-level — they apply to **all** recipients of that API call. You cannot specify different sounds for different users in a single request.

To deliver different sounds to different users, use a **fan-out pattern**: make separate API calls for each sound variant, targeting users by tag or segment. For example, store each user's preferred sound in a [tag](./add-user-data-tags) like `preferred_sound`, then send one request per sound value.

<CodeGroup>
  ```json Request 1 — "chime" users theme={null}
  {
    "app_id": "YOUR_APP_ID",
    "contents": {"en": "You have a new message!"},
    "ios_sound": "chime.wav",
    "android_channel_id": "CHIME_CHANNEL_ID",
    "include_filters": [
      {"field": "tag", "key": "preferred_sound", "relation": "=", "value": "chime"}
    ]
  }
  ```

  ```json Request 2 — "bell" users theme={null}
  {
    "app_id": "YOUR_APP_ID",
    "contents": {"en": "You have a new message!"},
    "ios_sound": "bell.wav",
    "android_channel_id": "BELL_CHANNEL_ID",
    "include_filters": [
      {"field": "tag", "key": "preferred_sound", "relation": "=", "value": "bell"}
    ]
  }
  ```
</CodeGroup>

Each request targets only the users whose `preferred_sound` tag matches, so each group hears its own sound. Add as many variants as you need — one API call per sound.

### Why is my notification not playing the custom sound file?

There are a few common causes:

* Sound file has an incorrect file extension
* Sound file is not encoded in a supported format
* Sound file is in the wrong location in the project
* Sound file is longer than 30 seconds

**iOS** — Read more in [Apple's documentation](https://developer.apple.com/documentation/usernotifications/unnotificationsound?language=objc) for encoding and testing guidance.

**Android** — Verify the sound file is included in your APK by extracting it and confirming it exists in `res/raw/`.

If resource shrinking is enabled, protect sound files from being removed by creating `keep.xml` in `res/raw/`:

```xml theme={null}
<resources xmlns:tools="http://schemas.android.com/tools"
  tools:keep="@raw/sound_file"/>
```

### Why is my notification playing the default sound file?

Make sure you followed the setup instructions and the sound file is in the correct location for your SDK. Double-check the filename casing — some platforms ignore uppercase letters.

### Why is the wrong sound playing?

On Android, notifications are grouped together after a certain number are received without being opened. Grouped notifications play a default sound. You can set the sound with the [group key](https://developer.android.com/training/notify-user/group) for all your notifications.

***

## Related pages

<Columns cols={2}>
  <Card title="Notification categories" icon="layer-group" href="./android-notification-categories">
    Set up Android notification channels to control sound, vibration, and importance.
  </Card>

  <Card title="Templates" icon="file-lines" href="./templates">
    Create reusable notification templates with predefined sounds.
  </Card>

  <Card title="Create Notification API" icon="code" href="/reference/push-notification">
    API reference for the ios\_sound, android\_channel\_id, and adm\_sound parameters.
  </Card>

  <Card title="Notification icons" icon="image" href="./notification-icons">
    Customize notification icons for your mobile app.
  </Card>
</Columns>