Custom sounds are a way to provide a more unique, branded experience for your app.
You may add a custom sound with every notification you send, or you may add sounds to just certain types of notifications. For instance, a game like "Jewel Breaker" may wish to have a jewel-like sound always played when receiving notifications. Meanwhile, a social network may wish to only play sounds when the user receives a message from another user to differentiate those notifications from more generic system notifications.
| Quick Reference | Details |
| [Create Sound Files](🔗) | Recommended to use `.wav` files to work across all platforms. |
| [Add Sound Files to App](🔗) | Where to place the sound files within the app. |
| [Send Notifications With or Without Sounds](🔗) | How to send the Notification With our Without Sounds. |
Web Push Sound Limitation
Browsers do not currently support sounds on web push notifications. This feature is in development.
Chrome Thread: https://bugs.chromium.org/p/chromium/issues/detail?id=442131
Firefox Thread: https://bugzilla.mozilla.org/show_bug.cgi?id=1105222
## How to Add Custom Sounds
### 1. Create Sound Files
Be sure to create sound files according to the following rules. If the device cannot find the file in question, or if the file is not in a supported format, it will fall back to the default system notification sound.
Sound Filename Recommendation
Keep sound filenames lowercase since some platforms ignore upper case letters for sound files. Instead of `
AwesomeSound.wav` use `awesomesound.wav` or `awesome_sound.wav`.
| Platform | Extensions | Notes |
| iOS | `.wav` `.aiff` `.caf` | Apple is picky about file formats. Sounds must be encoded as Linear PCM, MA4 (IMA/ADPCM), µLaw, or aLaw. Must be less than 30 seconds. |
| Android | `.wav` `.mp3` `.ogg` | |
| Amazon | `.wav` `.mp3` `.ogg` | |
| Windows | `.wav` `.mp3` `.wma` | Must be less than 10 seconds |
### 2. Add Sound Files to App
To adds sounds to notifications, you must include the sound files as resources within your app. External URLs are not supported.
#### 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 that they are automatically add to the bundle resources (<a href="https://files.readme.io/9997e49-iOS_Resources.png" target="_new">see here</a>) |
| Cordova, Ionic, PhoneGap | Add files to `Resources` directory within the Xcode project in `<project-root>/platforms/ios/project-name.xcodeproj`, and (<a href="https://files.readme.io/Zn35Nuk8SAeADiXyRaTA_Cordova%20iOS%20custom%20notifiction%20sound.png" target="_new">see here</a>) |
| PhoneGap Build (PGB) | Add file to `www`. File **must** be called `beep.wav` |
| Unity | Add sounds anywhere in your Unity project, build your project, and then move those sounds to the Xcode project root. |
#### Android (and derivatives like 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 & Amazon Native | `res/raw` |
| React Native | `<project-root>/android/app/res/raw` |
| Cordova | `<project-root>/platforms/android/res/raw/` |
| Ionic | `/android/app/src/main/res/raw/` |
| PhoneGap Build (PGB) | `<project-root>/locales/android/raw/`
See [this github link](🔗) for more details on the directory structure if you're having issues. |
| 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._ |
### 3. Send Notifications With or Without Sounds
#### Android & Amazon
Android 8+ introduced [Notification Categories](🔗) which must be setup to customize notification sounds. OneSignal will use the sound set in the Notification Channel for all versions of Android.
In **Settings** > **Messaging** > **Android Categories** create the channel and set **IMPORTANCE** to "Urgent" or "High".
For **Sound** do **not** add the file extension when referencing the sound resource. For instance, `cat_meow_sound`.
For **No Sound**, set **IMPORTANCE** to "Urgent" or "High" and Sound to "OFF". Or you can set **IMPORTANCE** to "Medium" or "Low" for no sound.
**RECOMMENDED:** You can then set the category name in the [Dashboard Push Messages](🔗) or use the [API `android_channel_id` parameter](🔗). The sound set in the category will work for all android versions.
#### iOS
Add the file extension when referencing the sound resource. For instance, `explode_sound.wav`. If you're using **PhoneGap Build (PGB)**, set the sound filename to `www/beep.wav`.
For **No Sound**, on iOS, pass in `nil` to the Sound fields.
**REST API** - Instead of sending via the dashboard, you can send notifications with sounds in the REST API by using the appropriate parameter and file extension depending on your platform (see more in [Create notification REST API docs](🔗)).
| Platform | API Parameter | Details |
| iOS | `ios_sound` | Include File Extension.
Example:
`ios_sound : expload_sound.wav` |
| Android | `android_channel_id ` - Use if you created channel in the OneSignal Dashboard [Notification Categories](🔗).
`existing_android_channel_id` - Use if you created the channel elsewhere | Highly recommended to use [Android Notification Categories](🔗) |
| Amazon | `adm_sound` | Do Not Include File Extension.
Example:
`adm_sound : exploade_sound` |
New sounds take a while to propagate to all users
If you've very recently added a sound resource to your app, you may want to wait a few days before sending notifications using the sound. This is because it can take many days or even weeks for the majority of your users to update their apps to the latest version which contain your new sound resource.
If a user has an older version of your app without the sound resource and receives a notification that references it, they will hear only the default system notification sound.
## FAQ
#### Can I set a default sound?
OneSignal does not support default sounds directly. However, a workaround is to create a <a class="dash-link dash-messages" href="templates">Template</a> that references the sound, and use that that template for every message you send.
#### Why is my notification not playing the custom sound file?
There are a few reasons why a sound may not play.
Sound file has an incorrect file extension
Sound file is not encoded in a supported format
Sound file is in the incorrect location
Sound file is too long
Currently OneSignal does not log the resource incorrect issues, we're working on adding this to your logs.
<span class="label-all label-ios">iOS</span> - Read more in [Apple's documentation](🔗) for tips on how to encode files and test them.
<span class="label-all label-android">Android</span> - Make sure that it is getting built into your APK by extracting it and making sure it is located in `res/raw/`.
If shrinking resources is enabled, you can protect sound files from being removing by creating keep.xml in res/raw/ with following code
#### Why is my notification playing the default sound file?
Please make sure that you followed the setup instructions carefully and the sound file is in the correct location for the SDK.
Another reason the default sound may play is when notifications are grouped together after a total of 5 notifications sent (Android 9+). To resolve, make sure to set a [GROUPKEY](🔗) for all your notifications.