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.

For mobile apps only. Not supported on web push.

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.

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.

Android and Amazon

Add sound files to the appropriate folder in your project depending on your SDK. If the folder does not exist, create it.

3. Send notifications

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 Notification Categories create the group and channel.

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

You can then set the category name in the dashboard when sending push messages or use the Create Notification API android_channel_id property. 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.
Set in the dashboard when sending push messages or use the Create Notification API ios_sound property.

For no sound, pass in nil to the Sound field.

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

🚧

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 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 removed by creating keep.xml in res/raw/ with following code

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

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.

Why is the wrong sound playing?

On Android, notifications will get grouped together after a certain amount are received by the device without opening them. Grouped notifications play a default sound. You can set the sound with the GROUPKEY for all your notifications.