OneSignal Help & Documentation

Welcome to the OneSignal New IA developer hub. You'll find comprehensive guides and documentation to help you start working with OneSignal New IA as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    Discussions

Notification Sounds

Adding custom sounds to mobile notifications.

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.

🚧

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.

PlatformExtensionsNotes
iOS.wav .aiff .cafApple 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 .wmaMust 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.

SDKFolder
iOS NativeAdd 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 (see here)
PhoneGap, Cordova, IonicAdd files to Resources directory within the Xcode project in <project-root>/platforms/ios/project-name.xcodeproj, and (see here)
PhoneGap Build (PGB)Add file to www. File must be called beep.wav
UnityAdd sounds anywhere in your Unity project, build your project, and then move those sounds to the Xcode project root.
Corona, Corona EnterpriseAdd to root of Corona project folder
MarmaladeAdd to project folder

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.

SDKFolder
Android & Amazon Nativeres/raw
React Native<project-root>/android/app/res/raw
PhoneGap, Cordova, Ionic<project-root>/platforms/android/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.
Intel XDKNot supported, however there is a workaround here.
UnityAssets/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.
CoronaNot supported
Corona EnterpriseAdd to root of Corona project folder
Marmaladeandroid/res/raw

Windows Phone

If custom sound files are not found, the notification will not display at all. Custom sounds only work on Windows Phone 8.0 Update 3 or later.

SDKFolder
NativeAdd a sound file to the root of your project. Then, right click on your sound file and select Properties. Under Advanced>Copy to Output Directory select "Copy always" (see here)
MarmaladeAdd to project folder

3. Send Notifications With Sounds

Using the OneSignal Dashboard > Messages > New Push > Platform Settings

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 > 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.

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.

NOT RECOMMENDED: If you are specifically not targeting Android 8.0+ and/or targeting Amazon, do not add the file extension when referencing the sound resource. For instance, cat_meow_sound.

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.

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).

Androidandroid_channel_id - Use if you created channel in the OneSignal Dashboard Notification Categories.


existing_android_channel_id - Use if you created the channel elsewhere

android_sound - For android 7 and older targeting only (does not work on Android 8+)
--------
Amazonadm_sound
--------
iOSios_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.

4. Send Notifications Without Sounds and Without Vibration

For Android 8.0+ you can customize sound and vibration separately using Android Notification Categories. Setting this will work on all versions of Android.

If you are targeting Android Versions under 8.0 or only Amazon, you can disable vibration with each SDKs enableVibrate method setting it to false and put nil in the Sound field.

You can send notifications with no sound by passing in nil to the same Sound fields within New Message open Options.


FAQ

Can I set a default sound?

OneSignal does not support default sounds directly. However, a workaround is to create a Template 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.

iOS - Read more in Apple's documentation for tips on how to encode files and test them.

Android - 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

<resources xmlns:tools="http://schemas.android.com/tools"
tools:keep="@raw/sound_file"/>

Updated 4 months ago


What's Next

Learn about setting up more features, or start using the OneSignal Dashboard

Features Setup
Dashboard

Notification Sounds


Adding custom sounds to mobile notifications.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.