Offline push notification extension

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

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

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

`em_push_template` fields

Field	Type	Description
`name`	`String`	The push template name.
`title_args`	`List<String>`	The push template title, which can include embedded parameters such as `{$fromNickname}` (sender's nickname).
`content_args`	`List<String>`	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

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

`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)

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.

`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

Push extension fields structure

{
    "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

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

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

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".

{
    "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

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."

{
    "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"
    }
}