# Offline push notification extension (/en/api-reference/api-ref/im/offline-push/offline-push-extension)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

Agora Chat supports APNs and FCM push integration. When using offline push, you can configure push functions using message extension fields. For example, you can set the push title and content in a push template or configure personalized push notifications for specific users in a group.

## Push extension fields [#push-extension-fields]

`payload.ext` contains the following fields:

| Field                    | Type      | Description                                                                                                                                                         |
| ------------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `em_push_filter`         | `Object`  | The push filter.                                                                                                                                                    |
| `em_push_template`       | `Object`  | The push template.                                                                                                                                                  |
| `em_ignore_notification` | `Boolean` | Whether to send a silent message.  - `true`: No notification is sent to offline users.  - `false`: A notification is sent to offline users.                         |
| `em_force_notification`  | `Boolean` | Whether to push notifications even if the recipient is in Do Not Disturb (DND) mode.  - `true`: Notifications are pushed.  - `false`: Notifications are not pushed. |
| `em_apns_ext`            | `Object`  | APNs push extension settings.                                                                                                                                       |
| `em_android_push_ext`    | `Object`  | Android push extension settings.                                                                                                                                    |
| `em_push_ext`            | `Object`  | Common push extension settings.                                                                                                                                     |

### `em_push_filter` fields [#em_push_filter-fields]

| Field                  | Type   | Description                                                               |
| ---------------------- | ------ | ------------------------------------------------------------------------- |
| `accept_device_id`     | `List` | List of device IDs that receive push notifications.                       |
| `ignore_device_id`     | `List` | List of device IDs that do not receive push notifications.                |
| `accept_notifier_name` | `List` | List of push certificates of users who receive push notifications.        |
| `ignore_notifier_name` | `List` | List of push certificates of users who do not receive push notifications. |

### `em_push_template` fields [#em_push_template-fields]

| Field               | Type     | Description                                                                                                                                                                                                    |
| ------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`              | `String` | The push template name.                                                                                                                                                                                        |
| `title_args`        | `List`   | The push template title, which can include embedded parameters such as `{$fromNickname}` (sender's nickname).                                                                                                  |
| `content_args`      | `List`   | The push template content, which can include embedded parameters such as `{$msg}` (message content). If translation is enabled, both the original message and the translation appear in the push notification. |
| `directed_template` | `Object` | A targeted push template. This applies to group messages where different push notifications are sent to different users.                                                                                       |

### `directed_template` fields [#directed_template-fields]

| Field          | Type     | Description                                                     |
| -------------- | -------- | --------------------------------------------------------------- |
| `target`       | `Array`  | List of user IDs. User IDs must contain only lowercase letters. |
| `name`         | `String` | The push template name.                                         |
| `title_args`   | `Array`  | The push template title.                                        |
| `content_args` | `Array`  | The push template content.                                      |

### `em_push_ext` fields [#em_push_ext-fields]

| Field                 | Type     | Description                                                                                                                                |
| --------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `title`               | `String` | Custom push title.                                                                                                                         |
| `content`             | `String` | Custom push content.                                                                                                                       |
| `custom`              | `Object` | User-defined extension field. Matches the `e` field among other parsed fields (`t`, `f`, `m`, and `g`) when receiving a push notification. |
| `group_user_nickname` | `String` | Nickname of the sender's group.                                                                                                            |
| `type`                | `String` | VoIP push notification (only applicable when APNs supports VoIP notifications).                                                            |

### `em_apns_ext` fields (APNs) [#em_apns_ext-fields-apns]

| Field                       | Type      | Description                                                                                                                                                                                    |
| --------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `em_push_category`          | `String`  | Push notification category.                                                                                                                                                                    |
| `em_push_mutable_content`   | `Boolean` | Whether the notification supports rich text.  - `true`: Rich text notification.  - `false`: Standard notification.                                                                             |
| `em_push_sound`             | `String`  | Custom ringtone file in `Library/Sounds/`, such as `appsound.caf`.                                                                                                                             |
| `em_push_badge`             | `Integer` | Custom badge number.                                                                                                                                                                           |
| `em_push_content_available` | `Integer` | Background notification indicator. For details, see [Apple's documentation](https://developer.apple.com/documentation/usernotifications/pushing-background-updates-to-your-app?language=objc). |

### `em_android_push_ext` fields (Android) [#em_android_push_ext-fields-android]

| Field            | Type   | Description                                 |
| ---------------- | ------ | ------------------------------------------- |
| `fcm_options`    | Object | FCM SDK options.                            |
| `fcm_channel_id` | String | FCM channel ID (with the highest priority). |

## Example [#example]

### Push extension fields structure [#push-extension-fields-structure]

```json
{
    "ext": {
        "em_push_filter": {
            "accept_device_id": [],
            "ignore_device_id": [],
            "accept_notifier_name": [],
            "ignore_notifier_name": []
        },
        "em_at_list": ["abc"],
        "em_push_template": {
            "name": "test6",
            "title_args": ["test1"],
            "content_args": ["{$fromNickname}", "{$msg}"]
        },
        "em_push_ext": {
            "custom": {"test": 1},
            "group_user_nickname": "happy"
        },
        "em_ignore_notification": false,
        "em_force_notification": true,
        "em_apns_ext": {
            "em_push_title": "You've got a new message",
            "em_push_content": "Please click to view",
            "em_push_category": "",
            "em_push_mutable_content": true,
            "em_push_sound": "appsound.mp3",
            "em_push_badge": 1,
            "em_push_content_available": 1
        },
        "em_android_push_ext": {
            "fcm_options": {"key": "value"},
            "fcm_channel_id": ""
        }
    }
}
```

### Targeted push template [#targeted-push-template]

Use targeting templates to send different notifications to a specific user in a group than to other group members.

#### Step 1: Create a Push Template [#step-1-create-a-push-template]

```json
{
    "name": "at_push_template",
    "title_pattern": "{0}",
    "content_pattern": "{0}:{1}"
}
```

#### Step 2: Apply the template for group messages [#step-2-apply-the-template-for-group-messages]

User `hxtest` receives the push notification **"Tom mentions you in the group"**, while other offline users receive **"Tom sends a message"**.

```json
{
    "em_push_template": {
        "name": "push_template",
        "title_args": ["group name"],
        "content_args": ["Tom", "sends a message"],
        "directed_template": {
            "target": ["hxtest"],
            "name": "at_push_template",
            "title_args": ["group name"],
            "content_args": ["Tom", "mentions you in the group"]
        }
    }
}
```

### Additional push configuration [#additional-push-configuration]

For users other than the mentioned user, you don’t need to use a template for push content. Instead, you can customize the title and content using push extension fields:

* **Title**: The name of the group.
* **Content**: A brief message indicating an action, such as "sends a message."

```json
{
    "em_push_template": {
        "directed_template": {
            "target": ["hxtest"],
            "name": "at_push_template",
            "title_args": ["group name"],
            "content_args": ["Tom", "mentions you in the group"]
        }
    },
    "em_push_ext": {
        "title": "group name",
        "content": "sends a message",
        "type": "call"
    }
}
```