# Notification Templates

Notification templates let you save notification content that you can load and reuse when creating a push notification. Templates are optional but useful if you send similar notifications regularly.

***

### Content

The content field is the message that will appear on the user's device. You can use merge fields to personalise the message — for example, inserting the recipient's name.

If your app registrations are linked to UbiQuity database contacts, you can merge any available database fields into your notification content.

***

### iOS settings

| Field              | Description                                                                                                                                                                                                               |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Sound              | The sound that plays when the notification is received. The sound file must be saved in your iOS app bundle. Include the file extension. If not specified, or if the file is not found, the default alert sound plays.    |
| Action Button Text | The label on the action button when the notification appears as an alert. Not shown in banner format. Used as a localisation key if the app supports multiple languages. Defaults to "View".                              |
| Launch Image       | The image shown before the app opens when a user taps the action button. Must be saved in the iOS app bundle. If not specified, the system falls back to a previous snapshot, the app's launch image, or the iOS default. |

***

### Android settings

| Field        | Description                                                                                                                                                                                                                              |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Collapse Key | A key used to group similar messages when the device is offline, so only the most recent message is delivered when the device comes back online. Up to four collapse keys are allowed per app. Required if setting a Time to Live value. |

***

### Custom data

Custom data lets you pass additional key-value pairs through to your app when a notification is received. Your app can be coded to read these values and change its behaviour accordingly.

For example, you could define an `action` key with possible values such as `competitionResults` or `latestNews`. When a user taps the notification, the app reads the `action` value and navigates to the relevant screen rather than the default home screen.

Custom data is highly flexible and allows you to get more out of your push notifications by driving behaviour within your app.

***

### Character limits

Both iOS and Android have limits on the total size of a push notification payload.

| Platform | Limit            |
| -------- | ---------------- |
| iOS      | 2,048 characters |
| Android  | 4,096 characters |

The character count includes all sections of the notification — not just the message content. Changes to iOS settings, Android settings, or custom data will all increase the character count for the relevant platform.

The count may increase by more than the number of characters you type. This is because UbiQuity includes additional formatting code in the payload sent to the device. For example, adding a single character to the iOS sound field increases the character count by six.

If a notification exceeds the limit, the content will be trimmed automatically to fit within the limit for each device type.

***

### Previewing a template

Use the preview function to see how merge fields will appear for a specific registered device. Select a device type (iOS or Android) to preview only the sections relevant to that platform. Use the character count alongside the preview to check that messages are not too long once data is merged in.


---

# 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://docs.ubiquity.co.nz/documentation/channels/push/notification-templates.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.