Configure push notifications

You can use extension fields to implement customized push settings. This page uses force push and sending silent messages as examples to explain how to implement push extensions. For more information, see Offline push notification extension.

Set custom push fields

When creating a push message, you can add custom fields to the message to meet personalized business needs:

// This example takes text messages as an example. The setting methods for message types such as pictures and files are the same.
ChatMessage message = ChatMessage.createSendMessage(ChatMessage.Type.TXT);
// Set custom push extension.
JSONObject emPushExt = new JSONObject() {
   {
        put("custom", new JSONObject() {
            {
                put("key1", "value1");
                put("key2", "value2");
            }
        });
    }
};
// Set the push extension to the message.
message.setAttribute("em_push_ext", emPushExt);

The data structure of the custom field is as follows:

{
    "em_push_ext": {
        "custom": {
            "key1": "value1",
            "key2": "value2"
        }
    }
}

Parameters	Description
`em_push_ext`	The extension fixed value, cannot be modified.
`custom`	The message extension. Use the extension method to add custom fields to the push, the value is fixed.
`key1`/`key2`	Customize the specific content of the message push extension.

Force push

The user can set force push to ignore the recipient's DND setting when sending messages:

// This example takes text messages as an example. The setting methods for message types such as pictures and files are the same.
ChatMessage message = ChatMessage.createSendMessage(ChatMessage.Type.TXT);
// Set whether to force push. This field is a built-in extension field with the following values: `true`: force push; (default) `false`: non-force push.
message.setAttribute("em_force_notification", true);

Send a silent message

Sending silent messages means that the sender sets the message not to be pushed when sending it. That is, when the user is offline, Chat will not push message notifications to the user's device through the FCM push service. When the user is online again, they will receive all the messages received during the offline period.

Both silent message sending and do not disturb mode pause push messages. The difference is that silent message sending is set by the sender when sending the message, while the DND mode is set by the receiver.

// This example takes text messages as an example. The setting methods for message types such as pictures and files are the same.
ChatMessage message = ChatMessage.createSendMessage(ChatMessage.Type.TXT);
// Set whether to send silent messages. This field is a built-in extension field with the following values: `true`: send silent messages; (default) `false`: push the message.
message.setAttribute("em_ignore_notification", true);

You can use extension fields to implement customized push settings. This page uses force push, sending silent messages, and rich text push as examples to explain how to implement push extensions. For more information, see Offline push notification extension.

Set custom push fields

When creating a push message, you can add custom fields to the message to meet personalized business needs:

AgoraChatTextMessageBody *body = [[AgoraChatTextMessageBody alloc] initWithText:@"test"];
    NSString* currentUsername = AgoraChatClient.sharedClient.currentUsername;
    NSString* conversationId = @"remoteId";
    AgoraChatMessage *message = [[AgoraChatMessage alloc] initWithConversationID:conversationId from:currentUsername to:conversationId body:body ext:nil];
    message.ext = @{@"em_apns_ext":@{@"extern":@{@"test":123}}};
    message.chatType = AgoraChatTypeChat;
    [AgoraChatClient.sharedClient.chatManager sendMessage:message progress:nil completion:nil];

The data structure of the custom field is as follows:

{
    "em_apns_ext": {
      "extern": {"test": 123}
    }
}

Parameters	Description
`em_apns_ext`	The built-in message extension fields.
`extern`	The user-added custom key; multiple keys can be added.

Custom ringtones

When creating a push message, you can customize the notification tone when the recipient receives the message. Add the audio file to the app and configure its name used in the push. For details, see Apple documentation.

AgoraChatTextMessageBody *body = [[AgoraChatTextMessageBody alloc] initWithText:@"test"];
    AgoraChatMessage *message = [[AgoraChatMessage alloc] initWithConversationID:conversationId from:AgoraChatClient.sharedClient.currentUsername to:conversationId body:body ext:nil];
    message.ext = @{@"em_apns_ext":@{@"em_push_sound":@"custom.caf"}};
    message.chatType = AgoraChatTypeChat;
    [AgoraChatClient.sharedClient.chatManager sendMessage:message progress:nil completion:nil];

The data structure of the custom ringtone field is as follows:

{
  "ext": {
    "em_apns_ext": {
      "em_push_sound":"custom.caf"
    }
  }
}

Parameters	Description
`em_apns_ext`	The built-in message extension fields.
`em_push_sound`	The key of the custom reminder ringtone field. This field is a built-in field and cannot be modified.
`custom.caf`	The name of the audio file for the ringtone.

Force push

The user can set force push to ignore the recipient's DND setting when sending messages:

AgoraChatTextMessageBody *body = [[AgoraChatTextMessageBody alloc] initWithText:@"test"];
AgoraChatMessage *message = [[AgoraChatMessage alloc] initWithConversationID:conversationId from:AgoraChatClient.sharedClient.currentUsername to:conversationId body:body ext:nil];
// Set whether to force push. This extension field is a built-in field with the following values: ` YES ` : force push; (default) ` NO ` : non-force push.
message.ext = @{@"em_force_notification":@YES};
message.chatType = AgoraChatTypeChat;
[AgoraChatClient.sharedClient.chatManager sendMessage:message progress:nil completion:nil];

Send a silent message

Sending silent messages means that the sender sets the message not to be pushed when sending it. That is, when the user is offline, Chat will not push message notifications to the user's device through the third-party push service. When the user is online again, they will receive all the messages received during the offline period.

AgoraChatTextMessageBody *body = [[AgoraChatTextMessageBody alloc] initWithText:@"test"];
AgoraChatMessage *message = [[AgoraChatMessage alloc] initWithConversationID:conversationId from:AgoraChatClient.sharedClient.currentUsername to:conversationId body:body ext:nil];
// Set whether to send silent messages. This field is a built-in extension field with the following values: `YES`: send silent messages; (default) `NO`: push the message.
message.ext = @{@"em_ignore_notification":@YES};
message.chatType = AgoraChatTypeChat;
[AgoraChatClient.sharedClient.chatManager sendMessage:message progress:nil completion:nil];

Implement rich text push

If your target platform is iOS 10.0 or above, you can refer to the following code to implement the rich text push function of UNNotificationServiceExtension.

AgoraChatTextMessageBody *body = [[AgoraChatTextMessageBody alloc] initWithText:@"test"];
AgoraChatMessage *message = [[AgoraChatMessage alloc] initWithConversationID:conversationId from:AgoraChatClient.sharedClient.currentUsername to:conversationId body:body ext:nil];
// em_apns_ext: message extension field
message.ext = @{@"em_apns_ext":@{@"em_push_mutable_content":@YES}};
message.chatType = AgoraChatTypeChat;
[AgoraChatClient.sharedClient.chatManager sendMessage:message progress:nil completion:nil];

Parameters	Description
`body`	The push message content.
`conversationId`	The conversation ID to which the message belongs.
`from`	The user ID of the sender of the message.
`to`	The user ID of the message recipient.
`em_apns_ext`	The built-in message extension fields.
`em_push_mutable_content`	Whether to use rich text push notification (`em_apns_ext`): `YES`: Rich text push notification; (Default)`NO`: Regular push notification. This field is a built-in field and its name cannot be modified.

When the receiver gets a rich text push, the didReceiveNotificationRequest:withContentHandler: callback is triggered. The sample code is as follows:

- (void)didReceiveNotificationRequest:(UNNotificationRequest *)request withContentHandler:(void (^)(UNNotificationContent * _Nonnull))contentHandler {
    // Push extension fields
    NSDictionary *userInfo = request.content.userInfo;
    // Notification content
    UNNotificationContent *content = [request.content mutableCopy];
    contentHandler(content);
}

Parameters	Description
`body`	The push message content. .
`badge`	The square badge number.
`sound`	The recipient will hear a ringtone when receiving the message.
`mutable-content`	Set to `1` to activate `UNNotificationServiceExtension` .
`f`	The user ID of the message sender.
`t`	The user ID of the message recipient.
`m`	The message ID.

You can use extension fields to implement force push and send silent messages. For more information, see Offline push notification extension.

Force push

The user can set force push to ignore the recipient's DND setting when sending messages:

// The following takes text messages as an example. The setting methods for other types of messages are the same.
const sendTextMsg = () => {
  const options: AgoraChat.CreateTextMsgParameters = {
    chatType: chatType,
    type: "txt",
    to: targetUserId,
    msg: msgContent,
    ext: {
      // Set whether to force push. This field is a built-in field with the following values: `YES`: force push; (default) `NO`: non-force push.
      em_force_notification: "YES",
    },
  };
  const msg = AgoraChat.message.create(options);
  chatClient.send(msg);
};

Send a silent message

A silent message means that when a user is offline, Chat will not push notifications to the user's device through the push service. Therefore, the user will not receive message push notifications. When the user is online again, they will receive all the messages received during the offline period.

Both silent message sending and do not disturb mode pause push messages. The difference is that silent message sending is set by the sender when sending the message, while do not disturb mode is set by the receiver.

// The following takes text messages as an example. The setting methods for other types of messages are the same.
const sendTextMsg = () => {
  const options: AgoraChat.CreateTextMsgParameters = {
    chatType: chatType,
    type: "txt",
    to: targetUserId,
    msg: msgContent,
    ext: {
      // Set whether to send silent messages. This field is a built-in field with the following values: `YES`: send silent messages; (default) `NO`: push the message.
      em_ignore_notification: "NO",
    },
  };
  const msg = AgoraChat.message.create(options);
  chatClient.send(msg);
};

Set custom push fields

When creating a push message, you can add custom fields to the message to meet personalized business needs:

// This example takes text messages as an example. The setting methods for message types such as pictures and files are the same.
ChatMessage msg = ChatMessage.createTxtSendMessage(
  targetId: 'receiveId',
  content: 'content',
);
msg.attributes = {
  // Set the push extension to the message.
  "em_push_ext": {
        "custom": {
            "key1": "value1",
            "key2": "value2"
        }
    }
};
try {
  await ChatClient.getInstance.chatManager.sendMessage(msg);
} on ChatError catch (e) {}

The data structure of the custom field is as follows:

{
    "em_push_ext": {
        "custom": {
            "key1": "value1",
            "key2": "value2"
        }
    }
}

Parameters	Description
`em_push_ext`	The extension fixed value, cannot be modified.
`custom`	The message extension. Use the extension method to add custom fields to the push, the value is fixed.
`key1`/`key2`	Customize the specific content of the message push extension.

Force push

The user can set force push to ignore the recipient's DND setting when sending messages:

// This example takes text messages as an example. The setting methods for message types such as pictures and files are the same.
ChatMessage msg = ChatMessage.createTxtSendMessage(
  targetId: 'receiveId',
  content: 'content',
);
msg.attributes = {
  'em_force_notification': true,
};
try {
  await ChatClient.getInstance.chatManager.sendMessage(msg);
} on ChatError catch (e) {}

Send a silent message

// This example takes text messages as an example. The setting methods for message types such as pictures and files are the same.
ChatMessage msg = ChatMessage.createTxtSendMessage(
  targetId: 'receiveId',
  content: 'content',
);
msg.attributes = {
  'em_ignore_notification': true,
};
try {
  await ChatClient.getInstance.chatManager.sendMessage(msg);
} on ChatError catch (e) {}

Set custom push fields

When creating a push message, you can add custom fields to the message to meet personalized business needs:

msg.attributes = {
  // Message extension fields.
   "em_push_ext": {
        "custom": {
            "key1": "value1",
            "key2": "value2"
        }
    },
};

The data structure of the custom field is as follows:

{
    "em_push_ext": {
        "custom": {
            "key1": "value1",
            "key2": "value2"
        }
    }
}

Parameters	Description
`em_push_ext`	The fixed extension value, cannot be modified.
`custom`	The message extension. Use the extension method to add custom fields to the push. The value is fixed.
`key1`/`key2`	Customize the specific content of the message push extension.

Force push

The user can set force push to ignore the recipient's DND setting when sending messages:

// The following takes text messages as an example. The setting methods for other types of messages are the same.
msg.attributes = {
  // Whether to force push. This field is a built-in field, and the values are as follows: `true`: force push; (default) `false`: non-force push.
  em_force_notification: true,
};

Send a silent message

// The following takes text messages as an example. The setting methods for other types of messages are the same.
msg.attributes = {
  // Whether to send a silent message. This field is a built-in field, and the values are as follows: `true`: send a silent message; (default) `false`: push the message.
  em_ignore_notification: true,
};

Configure push notifications

Set custom push fields

Force push

Send a silent message

Set custom push fields

Custom ringtones

Force push

Send a silent message

Implement rich text push

Force push

Send a silent message

Set custom push fields

Force push

Send a silent message

Set custom push fields

Force push

Send a silent message

Contact Us

Contact Us