# Customizing notifications

Batch allows you to customize your notifications adding specific keys to the payload.

Since we allow the overriding of Apple's keys, you can use and override anything Apple accepts in the `aps` key. Apple's full documentation about the payload is [located here](https://developer.apple.com/documentation/usernotifications/setting_up_a_remote_notification_server/generating_a_remote_notification?language=objc)

All of the following JSON examples go into the `custom_payload` field of both Transactional and Campaigns APIs.

### Adding a badge

You can add a badge to your iOS notifications by adding a `badge` key to the payload of your push. Here is how it looks:

```js
{"aps":{"badge":2}}
```

{% hint style="info" %}
You should reset the badge count when the app is opened.
{% endhint %}

### Adding actions buttons

You can add action buttons to your notification by adding a category key to the payload of your push. Here is how it looks:

```js
{"aps":{"category":"CATEGORY_NAME"}}
```

{% hint style="info" %}
We recommend you follow [that guide](/developer/sdk/ios/advanced/adding-notification-actions.md) to register categories.
{% endhint %}

### Choosing a notification sound

You can set a custom sound for your notification by adding the `sound` key to your payload. All you need to do is to add your custom sound to your app bundle before choosing it. Here is how it looks:

```js
{"aps":{"sound":"mysound.caf"}}
```

{% hint style="info" %}
You can't remotely push new sounds to your app. The filename *(or "default")* must be a sound file already present in your app bundle. If it is missing, iOS will play the default sound.
{% endhint %}

### Triggering a background refresh

iOS *(7+)* supports sending pushes that will wake up your app in the background. It works like background fetching, except that you control when your app will wake up.

This allows you to fetch new content *(news feed, conversation list, etc)* so your users won't have to wait for your app to sync when then open it.

First, you'll need to go in Xcode and enable "Remote notifications" as a Background Mode in your app's Capabilities:

<figure><img src="/files/hQJ5hwJiCJQqAHI5bc52" alt=""><figcaption></figcaption></figure>

Then, add `"content-available":1` in your `aps` object:

```js
{"aps":{"content-available":1}}
```

{% hint style="warning" %}
Users can disable background refresh for your application, or the system might not deliver it in some cases *(like battery saving mode)*.You shouldn't rely on this to work at all times: always fetch data that you can fetch in a more reliable way when your app starts.
{% endhint %}

### Sending silent notifications

Batch supports background notifications, which allow you to run actions for a limited amount of time without notifying the user.

Please keep in mind that the same restrictions apply as the ones described higher up for Background Refresh.

When calling our Campaign/Transactional APIs, add `'push_type': 'background'` to the request's JSON body, and remove the `message`/`messages`/`media` keys.

Silent notifications are not supported from the dashboard yet. Using the legacy way to do silent notifications using only the custom payload will **NOT** work on iOS 13 and later.

{% hint style="warning" %}
As said earlier for background refresh, we advise against triggering local notifications in response to a silent notification. While they are handy, the delivery rate will suffer heavily due to the unreliableness of background refresh.
{% endhint %}

### Disabling foreground notifications

Since Batch 2.0 the SDK always display notification while the App is in foreground. You can change this behaviour as following:

If you registered `BatchUNUserNotificationCenterDelegate` as your delegate, use the `showForegroundNotifications` property.

{% tabs %}
{% tab title="Swift" %}

```swift
// If you did not use BatchUNUserNotificationCenterDelegateregisterAsDelegate() but instanciated your own instance, use it instead of `sharedInstance`.
BatchUNUserNotificationCenterDelegate.sharedInstance.showForegroundNotifications = false
```

{% endtab %}

{% tab title="Objective-C" %}

```objectivec
// If you did not use [BatchUNUserNotificationCenterDelegate registerAsDelegate] but instanciated your own instance, use it instead of `sharedInstance`.
[BatchUNUserNotificationCenterDelegate sharedInstance].showForegroundNotifications = false;
```

{% endtab %}
{% endtabs %}

You can also do so with your own `UNUserNotificationCenterDelegate`:

* Create a class that implements `UNUserNotificationCenterDelegate`
* Override userNotificationCenter(center:willPresentNotification:withCompletionHandler) with `willShowSystemForegroundAlert` to false and call `completionHandler([])`.
* Call Batch's appropriate methods so you don't break any features
* Set it as the default `UNUserNotificationCenter`'s delegate

### Additional notification settings

iOS allows your app to show a button to configure notifications when the user long presses a notification.

You can enable this by calling this API:

```
 [BatchPush setSupportsAppNotificationSettings:true]
```

Note that this still requires you to implement a *UNUserNotificationCenterDelegate*, and the appropriate method to open the settings.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://doc.batch.com/developer/sdk/ios/advanced/customizing-notifications.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.