Something BIG is happening to our documentation! Check back in early October!

Creating a Push Message

Push notifications are wonderful for time-sensitive calls to action, as well as re-engaging users who haven’t come into the app in a while.

Successful Push Campaigns are going to drive the user directly to content or demonstrate the value of your app.

Please note that your push messages must fall within the guidelines of the Apple App Store and Google’s Play Store policies, specifically regarding using push messages as advertisements, spam, promotions, and more.

Apple App Store Policies
4.5.4 Push Notifications must not be required for the app to function, and should not be used for advertising, promotions, or direct marketing purposes or to send sensitive personal or confidential information.
3.2.2 (i) Creating an interface for displaying third party apps, extensions, or plug-ins similar to the App Store or as a general-interest collection. (ii) Monetizing built-in capabilities provided by the hardware or operating system, such as Push Notifications, the camera, or the gyroscope; or Apple services, such as Apple Music access or iCloud storage.
Google Play Store Policy
We don’t allow apps or ads that mimic or interfere with system functionality, such as notifications or warnings. System level notifications may only be used for an app’s integral features, such as an airline app that notifies users of special deals, or a game that notifies users of in-game promotions.

To see examples of push notifications, check out our Client Integration Gallery.

Step 1: Create a New Campaign

From the Messaging Page, click “Create Campaign.”


Step 2: Name Your Campaign, Choose Messaging Types, and Compose your Message

Next, you need to name your campaign and select the messaging types that will be included in the campaign. You select the platform(s) you’re sending a Push message to by clicking on the toggle buttons on the right hand side.


Time to write your push message! Type it into the box and watch a preview appear on the device in the box.

iOS Notification Options

With the release of Apple’s iOS 12, Braze will offer support for several of its features, including Notification Groups, Quiet Notifications/Provisional Authorization, and Critical Alerts.

Notification Groups

If you want to categorize your messages and group them in your user’s notification tray, you can utilize iOS’s Notification Groups feature through Braze.

Create your iOS Push Campaign, then look to the top of the composer. There, you’ll see a dropdown labeled Notification Groups.


From there, you can select any Notification Groups. If your notification group settings malfunction or you select None from the dropdown, the message will automatically send as normal to all defined users in the app group.

If you don’t have any Notification Groups listed here, you can add one using the iOS Thread ID. You will need one iOS Thread ID for every Notification Group you want to add. Then, add it to your Notification Groups by clicking Manage Notification Groups in the dropdown and filling out the required fields in the Manage iOS Push Notification Groups window that appears.


Summary Arguments and Categories

Summary Arguments

In addition to grouping notifications by Thread IDs, Apple allows you to edit the summaries that appear when notifications are grouped. Braze Users can specify the summary category, summary count, and summary argument when composing a push campaign using our tool.

Check the Alert Options box in the Push Composer.

Then, select summary-arg and summary-arg-count as keys and input those values in the corresponding column. If you do not set a value for summary-arg, it will default to 1.

Summary Categories

Summary Categories allow you to customize the entire summary that appears when notifications are grouped. You can create and apply multiple categories.

To use a category in your message, work with your developers to implement using the following example:

UNNotificationCategory *newsCategory = [UNNotificationCategory categoryWithIdentifier:@"news"
                                                      actions:@[likeAction, unlikeAction]
                                                      categorySummaryFormat:@"%u more news articles from %@"

This will not require an SDK update. Please note that %u and %@ are formatting strings for the summary count and summary argument, respectively. When the summary is shown, these placeholders will be replaced with the values for summary-count and summary-arg.

Once this is set up on your app, use the summary category by checking the Notification Buttons box, and selecting Enter Pre-registered iOS Category.

Then, input the summary category identifier that you set in your app.

Provisional Authentication/Quiet Notifications

Apple allows brands the option to send quiet pushes to their users’ Notification Centers before they officially opt in, giving you a chance to demonstrate the value of your messages early.

Braze allows you to register for Provisional Authentication by updating your code in your token registration snippet within your Braze iOS SDK implementation using the snippets below as an example (send these to your developers):


let notificationCenter = UNUserNotificationCenter.current() notificationCenter.requestAuthorization(options: [.alert, .badge, .sound, .provisional]) { ... }


	UNUserNotificationCenter *center = [UNUserNotificationCenter currentNotificationCenter];
 	UNAuthorizationOptions options = UNAuthorizationOptionAlert | UNAuthorizationOptionSound | UNAuthorizationOptionBadge | UNAuthorizationOptionProvisional;

You will also be able to segment your users based on whether they are provisionally authorized or not.

If you utilize additional push prompts, please reach out to your account manager for additional guidance.

Critical Alerts

Apple will allow some brands to send notification that are considered extremely important, will ignore Do Not Disturb settings, and will always play a sound no matter the setting on a user’s device.

Brands must be approved by Apple to use Critical Alerts. Good candidates for this feature could be apps with medical and other health-related information, home security, and public safety features. You must do this before using the feature in Braze.

Users will still be able to turn off Critical Alerts on a per-app basis, separately from other notifications.

Braze will give you the ability to select Send Critical Alert under Alert Options in the iOS Push Composer, which will then allow you to specify the notification as a Critical Alert.

Please note that this feature is still in beta. Additionally, if you attempt to use this feature without pre-approval by Apple, your message will not be allowed to send. Contact your account manager before attempting to use this feature.

Android Notification Options

If you want to categorize your messages and group them in your user’s notification tray, you can utilize Androids’s Notification Channels feature through Braze.

Create your Android Push Campaign, then look to the top of the composer. There, you’ll see a dropdown labeled Notification Channels.


From there, you can select any Notification Channels. You must select a Fallback channel in the event that your notification channel settings malfunction.

If you don’t have any Notification Channels listed here, you can add one using the Notification Channel ID. Contact your developers to identify what your Notification Channel IDs are or to create new IDs as needed. Then, add it to your Notification Channels by clicking Manage Notification Channel in the dropdown and filling out the required fields in the Manage Android Push Notification Channels window that appears. Notification Channels must be defined on the app before they may be used in the Braze platform.


Step 3: Schedule Your Messaging Campaign


Message scheduling features include:

  • Schedule messages to send immediately, at a specific time, using “Intelligent Delivery”.
  • Intelligent Delivery: Braze allows you to define a window during which you would like a user to receive a notification and Braze will send it to each individual user at the time we determine they are most likely to engage. We make this calculation based upon a statistical analysis of the user’s past interactions with the app.

Optimized Push Scheduling

  • Automatically schedule campaigns to send at a certain time with respect to the local time of each of your users.
  • Messages can also be configured to recur on a daily, weekly (optionally on specific days), or monthly basis.

Unless you check the box titled “Allow users to become re-eligible to receive campaign” under the Schedule portion of the campaign wizard, each user will only receive the contents of a campaign once, and only new users that meet the criteria will receive the campaign on subsequent deliveries.

Step 4: Target Users

On the “Target Users” step of campaign setup, you can choose the target audience for your campaign. Braze now provides all the detailed audience statistics on the footer. The footer will provide only the channels that are targeted by the campaign. Additionally you will be able to see a breakdown of the ‘Push’ messages as Braze will provide details on how many will receive a Web Push versus an Android Push. In order to see what percentage of your userbase is being targeted or the LTV for this segment, simply click the “Show Additional Stats” located below the stats footer.

Keep in mind that exact segment membership is always calculated just before the message is sent.

Multi-Channel Footer

Under the Targeting Options section, you’ll find a few options for who you can send your campaign to:

  1. Members of a previously created segment. To do this, simply select one segment from the dropdown under “Target Users By Segment.”

  2. Users that fall into multiple previously created segments. To do this, add multiple segments from the dropdown under “Target Users By Segment.” The resulting target audience will be users that are in the first segment and the second segment and the third segment, etc.

  3. Users of one or more previously created segments that also fall under additional filters. After first selecting your segment(s), you can further refine your audience under the “Additional Filters” section. This is demonstrated in the screenshot below, which targets users that are in the 10 Unread Messages segment and are in the Active Users segment and have made a purchase less than 30 days ago.

  4. Users that fall under a series of filters (and are not defined by pre-existing segments). This means you do not need to target a campaign at a pre-existing segment - you can make an ad hoc audience during campaign creation by just using the additional filters, and not selecting any segments under “Target Users By Segment. This will allow you to skip segment creation when sending campaigns to one-off audiences.


Above the Audience Statistics chart, there will be an Audience Summary that spells out which users you’re targeting.

Step 5: Choose Conversion Events

Braze allows you to track whether users perform specific actions (Conversion Events) after receiving a campaign. You can specify any of the following actions as a “Conversion Event”:

  • Opens App
  • Makes Purchase
    • This can be a generic purchase or a specific item
  • Performs specific custom event

You have the option of allowing a conversion event within a time frame that is relevant for your campaign. The conversion window for a conversion event can range from 5 minutes to 30 days. The event will count as a conversion if it takes place during the specified time.

Conversion Event

Step 6: Review and Deploy

The final page will give you a summary of the campaign you’ve just designed. Clicking “Launch Campaign” will enable it to send. Confirm all the relevant details and watch the data roll in!

Confirmation Page

Results Data

Braze will show you the number of messages sent and opened over time for each push campaign you deploy as shown below:


For push notifications, you’ll be able to view statistics for the number of messages sent, delivered, bounced, opened and directly opened.

Notification Channels

Notification Channels are a way to organize push notifications that were added with Android O. Starting with O, all push notifications must have a Notification Channel that indicates the type of message (e.g. “chat notifications,” or “follow notifications”). End users can then control aspects of their notification (e.g. snoozing, noise/vibration settings, or opting-out etc) based upon individual Channels.

Transitioning to Android O

Notification channels can only be created in the code of your application, and cannot be created programmatically in the Braze Dashboard. We recommend your engineering team work with your marketers to ensure the desired notification channels are properly added to the dashboard.

Starting with Android O, push notifications require a valid channel to display. If your app targets Android O or above, you must use Braze SDK version 2.1.0 or higher. Your development team should define the channels that you want to use as well as suggested notification settings (e.g importance, sound, lights) for each channel in your application code. You can find Android’s developer documentation here and Braze’s developer documentation here.

Note that Android supports localization for channel names, so in the code of your application you can associate one channel ID with multiple translations of a channel name.

Once these channels are created, your engineers will need to pass on the associated channel IDs to your marketing team. Your team should enter your channel names and channel IDs into the Braze dashboard for use in your Campaigns and Canvases.

To add a channel to the Braze dashboard, navigate to the Android push composer, select the notification channels field and then select “manage channels.” Note that only users with permissions that include “manage apps” will be able to manage channels.

SDK Default Channel

Android requires a valid channel to display push notifications on API level 26 (Android O) or above. Braze’s Android SDK 2.1.0 includes a default channel called “General,” which will be created and used if you do not specify additional channels in the dashboard or if you attempt to send to an invalid channel. You can rename this label in the SDK and provide a description for the channel. We recommend that you consider this in order to provide a better user experience.

Once a channel is added to your application, you can opt to remove it. However, consumers will always be able see the number of channels that you’ve removed. Braze’s dashboard does not include support for programmatically creating channels - channels must be created and defined in the code of your application in order to provide a seamless experience.

Again, we recommend that you coordinate with your engineering team to ensure a seamless transition to targeting Android O.

Dashboard Fallback Channel

Braze allows you to specify a dashboard fallback channel. The purpose of the dashboard fallback channel is to provide a channel ID for legacy push messages with no explicit channel selection. We define a channel selection as choosing a channel in our Android push composer.

Messages that do not have a channel selected will be sent with the dashboard fallback Channel ID. When you change your dashboard fallback channel, any message that does not have a channel explicitly selected will send with the ID of the new fallback channel.

Here’s an example of the dashboard fallback channel expected behavior:

Your dashboard fallback channel is called “Marketing” and you have 10 Android push messages that you have never selected a channel for. These Campaigns are sending through the “Marketing” channel because the “Marketing” Channel is the dashboard fallback channel.

Additionally, you have 15 messages that you’ve selected to send through the “Social Notifications” channel and 5 messages that you’ve selected to send through the “Marketing” channel.

You then decide to change your dashboard default channel from “Marketing” to “Updates”.

In this situation, all 10 Campaigns with no channel selection that were previously sending through the “Marketing” Channel will now send through the “Updates” channel because these messages send through the fallback channel. The 15 messages that were sending through the “Social Notifications” channel will continue to send through the “Social Notifications” channel. The 5 messages that were sending through the “Marketing” channel will continue to send through the “Marketing” channel.

In the event an invalid channel ID is supplied to Braze (ie. if you provide a channel ID that your developers did not create in the SDK), we will deliver the notification through your SDK default channel. Therefore, we highly encourage you to test your notification channels via Braze’s dashboard during development.

To better understand the expected behavior for channels, please refer to the following table:

Scenario Outcome
Company ABC updates to an SDK that supports Android O
Company ABC does not add any channels to the Braze dashboard
Company ABC does not rename their SDK default channel
Push notifications sent to Android O devices will create a channel called “General” and notifications will be sent through the “General” channel
Company XYZ updates to an SDK that supports Android O
Company XYZ does not add any channels to the Braze dashboard
Company XYZ renames their SDK default channel to “Marketing”
Push notifications sent to Android O devices will create a channel called “Marketing” and notifications will be sent through the “Marketing” channel
Company LMN updates to an SDK that supports Android O
Company LMN defines 2 channels in their application code, “Promotions” and “Order Updates”
Company LMN adds the channel IDs for “Promotions” and “Order Updates” to the Braze dashboard
Company LMN designates “Promotions” as the dashboard fallback channel
Company LMN renames their SDK default channel to “Marketing”
Push notifications sent to Android O devices will not create a channel

Unless the marketer explicitly specifies that notifications should send through the “Order Updates” or “Marketing” channel, all notifications created before the channels were added to the dashboard will send through the “Promotions” channel

The SDK default channel, “Marketing” is only created and used if the company attempts to send a notification through an invalid channel ID or if explicitly selected
Company HIJ updates to Android O but does not update to Braze Android SDK to 2.1.0 or higher Notifications sent to users running Android O or above do not appear

Adding Channels to Braze’s Dashboard

  • Open any Campaign or Canvas that includes an Android push and click “edit Campaign”.
  • Navigate to the Android Push message composer
  • Click “Manage Notification Channels”. Note that any channels added here will be available globally for all Campaigns and Canvases and that you must have “manage apps” permissions for your app group in order to manage channels.


  • Click “Add Notification Channel”

  • Enter the name and ID of the notification channel you want to add

Enter Channel

  • Repeat the two steps above for each notification channel that you’d like to add

  • Press “save” to save your changes

Specifying your Fallback Channel

Your fallback channel is the channel that Braze will attempt to send your android message with if you have not selected a channel for the message. The only Campaigns/Canvases that will have android messages without a channel selection are Campaigns/Canvases that were created before your team added channels to the Braze dashboard. If you change your fallback channel, the change will be applied globally to all Campaigns and Canvases without an explicit channel selection.

  • Open any existing Campaign or Canvas

  • Navigate to the android push composer

  • Select “Manage Notification Channels”

  • Add the channel to the dashboard (if it has not already been added)

  • Select the radio dial next to the channel that you’d like to designate as the fallback channel


  • Save your changes. Your changes will be applied globally

Adding Channels to your Android Push Messages

  • Navigate to the Android Push composer on any Campaign or Canvas


  • Select the channel you’d like to use from the dropdown. If you do not have a dropdown, but rather have the below view, you’ll need to add channels before selecting them for Campaigns


Rich Notifications

Rich Notifications allow for more customization in your push notifications by adding additional content beyond just copy. Android notifications have included images in push notifications for some time now, messaged as an ‘Expanded Notification Image’. Starting with iOS 10, your customers will be able to receive iOS push notifications that include gifs, images, videos, or audio.

Rich Not Blog

Android Rich Notifications


  • Note that expanded notification view is only available on devices using Jelly Bean (Android 4.1) or higher. If a user’s device is not running on these systems, they will not see the notification image.
  • Currently, Android rich notifications only allow for static images including jpg and png file formats.

Setting Up Your Android Rich Notification

  1. Follow the campaign steps you normally do to compose a push notification for Android. You will be using the same composer that you use for setting up push notifications that do not contain rich content.

  2. Add your Summary Text/ Image Caption that you’d like to display above the image in the notification.

    Add Android Summary Text

  3. Add your image in the ‘Expanded Notification Image’ field in the composer of the message. Images can be uploaded directly through the dashboard or by specifying a content URL that is hosted elsewhere.

    Add Android Image

  4. Once your rich notification content is uploaded to the dashboard, you can simply continue scheduling your campaign the way you always do.

iOS 10 Rich Notifications


  • To ensure your app is able to send rich notifications, please follow these instructions here, as your developer will need to add a service extension to your app.
  • You should also reference Apple’s documentation for media limitations and specs. We recommend using as small of a file size as possible. In practice, sending large files can cause both unnecessary network stress and make download timeouts more common.
  • File types that we currently support for direct uploading within our dashboard include jpg, png, or gif. These files can also be entered into the templatable URL field along with these additional file types: aif, m4a, mp3, mp4, or wav.

Setting Up Your iOS Rich Notification

  1. Follow the campaign steps you normally do to compose a push notification for iOS. You will be using the same composer that you use for setting up push notifications that do not contain rich content.

  2. Add your image, gif, audio, or video file in the ‘Rich Notification Asset’ field in the composer of the message. Please reference the above requirements on how to add your content files.

    Add Image

    You can also limit this message to only send to users who have a device that runs on iOS 10. For users who have not upgraded to iOS 10 it will appear as a text only notifications without the rich content if you leave the below box unchecked.

    iOS 10 Checkbox

  3. Once your rich notification content is uploaded to the dashboard, you can simply continue scheduling your campaign the way you always do.

Notification IDs

A notification ID can be assigned to a push notification when you want the option to group or replace it with an updated version once it’s been issued.

To do this, navigate to the composition page of the push you’d like to add the ID to and enter an integer in the Notification ID section. To update this notification once you’ve issued it, send another notification with the same ID that you used previously.


iOS Push Message Titles

To add a headline to an iOS push notification, use the Title field in the Braze message composer. The headline will appear in bold once the message is sent.


iOS 10.3 Customizable App Icon Feature

With iOS 10.3 Apple introduced the ability to change an app’s home screen icon without having to update the application from the Apple App Store. The developer can now allow the user to change the home screen icon inside of their app. Apple requires all of the app icon images that the developer wants to make available to the user to be included in the binary that is submitted to Apple for review during the publishing of the app on the Apple App Store.

To notify your users of this feature it is possible to send an In-App Message or push notification through Braze to the user explaining this functionality or asking the user if they would like to change their icon. The developer would only need to create a deep link into the application where the the native iOS prompt can be shown to make the icon change. This is similar to the same guidance we provide around setting up a Push Notification Primer for APNS today.

In additon, this messaging can take full advantage of Braze’s segmentation ability to make the message copy highly contextual to a user. You can also leverage Braze’s A/B testing of messages to see which messaging makes the most impact to your desired result.

Push Action Buttons

Push Action Buttons enable you to set content and actions for buttons when utilizing Braze’s iOS and Android push notifications. Your users will now be able to interact directly with your app from a notification without needing to click into an app experience to take action.

Push Action Buttons

How To Use Action Buttons

Each interactive button can link to a webpage, a deep link, open the app, or dismiss the notification. You can specify your Push Action Buttons in the ‘On Click Behavior’ section of the push message composer in the Dashboard.

iOS Push Action Buttons

iOS Push Action Buttons

Due to iOS’s handling of buttons, you will need to perform additional integration steps when setting up push action buttons, which are outlined in our Documentation. In particular, you will need to either configure iOS Categories or will need to select from certain default button options. For Android integrations, these buttons will work out of the box.

Android Push Action Buttons

Android Push Action Buttons

Push Stories

Push Stories is a new type of Push Notification introduced by Braze (formerly known as Appboy). It allows customers to send down multiple ‘pages’, which consists of an image, click action, title, and description to a device. The users can iterate through these pages and go though the ‘story’ as told by each marketer.

Android Example (Expanded) IOS Example (Expanded)
AndroidPreview IOSPreview

How it works

Pre-req: Clients must update to the latest version of Android(version:2.2.0+) and IOS (version: 3.2.0+)

Dashboard Changes


New Composer


The Push Story composer is controlled by a drop down at the top. You can choose to send a Standard Push Notification as you would today or send a Push Story Notification instead.

To create a page:

  • Click “Manage Pages” from the main composer.
  • Insert an image for each page, along with the click behavior for that image.
  • Title/Description for each page can also be inserted (if inserted for one page, they must be inserted for all pages).
  • The previews will be reflected and are interactive.

Push Stories Analytics


The analytics will look very similar to the current analytics section for Push Notification. The only difference is when you open the “Direct Opens” section, you can now see clicks per page.


Can I target users who clicked a particular page in the Push Story?

Push Story Segmentation is now available! When you create a Campaign or Canvas, you can filter which users you want to target based on whether they have clicked on a Push Story Page. Then, select the Campaign and the page you want to use to target your users.

I sent myself a Push Story on iOS but did not receive the notification - what happened?

Apple has specific rules in place that will prevent certain types of notifications from being sent to a device based on a number of different factors - this includes evaluating the customers data plan, whether the app was forced-closed, notification size and/or the customers storage capacity. As a result, sometimes no notification will be sent to your customers. These are limitations imposed by Apple that should be considered when designing your Push Story.

I sent myself a Push Story on iOS but saw the condensed view instead - what happened?

In certain situations where all the pages do not load, for example due to a loss of data connection, the Push Story will only show the condensed notification.