Quickstart: Sending a Toast notification with custom audio

Toast notifications can use custom audio, which lets your app express your brand's unique sound effects. For example, a messaging app can use their own messaging sound on their Toast notifications, so that the user can instantly know that they received a notification from the app, rather than hearing the generic notification sound.

1. Install UWP Community Toolkit NuGet package

In order to create notifications via code, we strongly recommend using the UWP Community Toolkit Notifications library, which provides an object model for the notification XML content. You could manually construct the notification XML, but that is error-prone and messy. The Notifications library inside UWP Community Toolkit is built and maintained by the team that owns notifications at Microsoft.

Install Microsoft.Toolkit.Uwp.Notifications from NuGet (we're using version 1.0.0 in this documentation).

2. Add namespace declarations

Windows.UI.Notifications includes the Tile and Toast API's.

using Microsoft.Toolkit.Uwp.Notifications;
using Windows.UI.Notifications;

3. Construct the notification

The Toast notification content includes text and images, and also buttons and inputs. Please see Quickstart: Sending a local toast notification and handling activations to see a full code snippet.

ToastContent toastContent = new ToastContent()
    Visual = new ToastVisual()
        ... (omitted)

4. Add the custom audio

Windows Mobile has always supported custom audio in Toast notifications. However, Desktop only added support for custom audio in Version 1511 (build 10586). If you send a Toast that contains custom audio to a Desktop device before Version 1511, the toast will be silent. Therefore, for Desktop pre-Version 1511, you should NOT include the custom audio in your Toast notification, so that the notification will at least use the default notification sound.

Known Issue: If you're using Desktop Version 1511, the custom toast audio will only work if your app is installed via the Store. That means you cannot locally test your custom audio on Desktop before submitting to the Store - but the audio will work fine once installed from the Store. We fixed this in the Anniversary Update, so that custom audio from your locally deployed app will work correctly.

bool supportsCustomAudio = true;

// If we're running on Desktop before Version 1511, do NOT include custom audio
// since it was not supported until Version 1511, and would result in a silent toast.
if (AnalyticsInfo.VersionInfo.DeviceFamily.Equals("Windows.Desktop")
    && !ApiInformation.IsApiContractPresent("Windows.Foundation.UniversalApiContract", 2))
    supportsCustomAudio = false;

if (supportsCustomAudio)
    toastContent.Audio = new ToastAudio()
        Src = new Uri("ms-appx:///Assets/Audio/CustomToastAudio.m4a")

Supported audio file types include...

  • .aac
  • .flac
  • .m4a
  • .mp3
  • .wav
  • .wma

5. Send the notification

Now that your Toast content is complete, sending the notification is quite simple.

// Create the Toast notification from the previous Toast content
ToastNotification notification = new ToastNotification(toastContent.GetXml());
// And then send the Toast


Comments (6)

  1. Abdussamad says:

    Thanks for sharing this! Still gotta test it myself, haven’t had the time yet to publish an app update.
    Btw, wouldn’t you wanna check if the UniversalApiContract version 1 is present (instead of if version 2 is not present)? Because if version 3 is out, which is the one that’ll come with the Anniversary Update I think, it’ll also be false.
    Or do the UniversalApiContracts “stack” with each Windows version (until Microsoft decides to remove one)? As in, you have Windows 10 version 1511, so you have UniversalApiContract version 1 and 2, instead of just 2. And with the Anniversary Update, Windows will support UniversalApiContract version 1, 2 and 3 etc.. Is that how it works?

    1. andrewbares7 says:

      The contracts stack! Version 3 includes everything in version 2. I tested that line of code on the Anniversary Update and it worked. For full transparency, I did not test this sample on Version 1511 or RTM, but theoretically it should work correctly.

      I’m glad you’ll be able to take advantage of custom audio! By the way, custom audio (when the app is deployed via Visual Studio) just started working recently in our internal builds, so that issue should be fixed soon-ish, making it much easier to test!

      1. Abdussamad says:

        Yeah I’ve seen that noted in your post, about being able to test without store deployment on Redstone/Anniversary Update builds, that’s great! I’ll be testing on a version 1511 machine (and a machine running the latest Slow Ring build, currently 14366) and I’ll let you know how it went. Thanks!

      2. Abdussamad says:

        I’ve tested custom audio on both the 1511 and the Redstone machine and I can confirm it both works!

  2. Oh, finally! Will custom sounds be also available on all other families, Xbox, HoloLens? I have quite robust framework in my app to handle mobile/dektop situation in terms of custom sounds. Not sure if it’s safe to delete it all.

    1. andrewbares7 says:

      Frankly, I’m not sure about Xbox. HoloLens currently doesn’t even support toast, so this is irrelevant there right now 😛

      We’ll talk with the Xbox folks and hopefully write up a document stating what is and isn’t supported on Xbox.

Skip to main content