设置推送通知方式和免打扰模式

大约 8 分钟

设置推送通知方式和免打扰模式

为优化用户在处理大量推送通知时的体验，环信即时通讯 IM 在 app 和会话层面提供了推送通知方式和免打扰模式的细粒度选项。

推送通知方式和免打扰模式为推送的高级功能，若要设置，你需要在 环信即时通讯控制台open in new window的即时通讯 > 功能配置 > 功能配置总览页面激活推送高级功能。如需关闭推送高级功能必须联系商务，因为该操作会删除所有相关配置。

image

推送通知方式

推送通知方式 remindType 包含三种类型，如下表所示。其中，会话级别的 remindType 设置优先于 app 级别的设置，未设置推送通知方式的会话默认采用 app 的设置。例如，假设 app 的推送方式设置为 MENTION_ONLY，而指定会话的推送方式设置为 ALL。你会收到来自该会话的所有推送通知，而对于其他会话来说，你只会收到提及你的消息的推送通知。

推送通知方式参数

描述

应用范围

ALL

接收所有离线消息的推送通知。

 

App 或单聊/群聊会话

MENTION_ONLY

仅接收提及某些用户的消息的推送通知。

该参数推荐在群聊中使用。若提及一个或多个用户，需在创建消息时对 ext 字段传 "em_at_list":["user1", "user2" ...]；若提及所有人，对该字段传 "em_at_list":"all"。

NONE

不接收离线消息的推送通知。

 

免打扰模式

你可以在 app 级别指定免打扰时间段和免打扰时长，即时通讯 IM 在这两个时间段内不发送离线推送通知。若既设置了免打扰时间段，又设置了免打扰时长，免打扰模式的生效时间为这两个时间段的累加。

免打扰时间参数的说明如下表所示：

免打扰时间参数类型描述应用范围
startTime - endTimeInt每天定时触发离线推送免打扰的时间段，采用 24 小时制，精确到分钟，格式为 H:M-H:M，例如 8:30-10:0，开始时间和结束时间中的小时数和分钟数的取值范围分别为 [0,23] 和 [0,59]。免打扰时间段的设置说明如下：
- 开始时间和结束时间设置后，免打扰模式每天定时触发。例如，若该时间段设置为 8:0-10:0，免打扰模式在每天的 8:00-10:00 内生效。若你在 11:00 设置开始时间为 8:0，结束时间为 12:0，则免打扰模式在当天的 11:00-12:00 生效，以后每天均在 8:00-12:00 生效。
- 若开始时间和结束时间相同，免打扰模式则全天生效。不过，若设置为 0:0-0:0，则关闭免打扰模式。
- 若结束时间早于开始时间，则免打扰模式在每天的开始时间到次日的结束时间内生效。例如，开始时间为 10:0，结束时间为 8:0，则免打扰模式的在当天的 10:00 到次日的 8:00 生效。
- 目前仅支持在每天的一个指定时间段内开启免打扰模式，不支持多个免打扰时间段，新的设置会覆盖之前的设置。
- 若该参数和免打扰时长 expireTimestamp 均设置，免打扰模式当日在这两个时间段均生效，例如，上午 8:00 将免打扰的时间段设置为 8:0-10:0，免打扰时长设置为 240 分钟（4 个小时），则 app 在当天 8:00-12:00 和以后每天 8:00-10:00 处于免打扰模式。		仅针对 app 生效，对单聊或群聊不生效。
expireTimestampInt免打扰时长，单位为毫秒。免打扰时长最长不超过 7 天。
与免打扰时间段（startTime - endTime）的设置每天生效不同，该参数为一次有效。设置后立即生效，例如，上午 8:00 将 app 层级的免打扰时长设置为 4 个小时，则 app 在当天 8:00-12:00 处于免打扰模式。
- 若该参数和免打扰时间段均设置，免打扰模式当日在这两个时间段均生效，例如，上午 8:00 将 app 级的免打扰时间段设置为 8:00-10:00，免打扰时长设置为 4 个小时，则 app 在当前 8:00-12:00 和以后每天 8:00-10:00 处于免打扰模式。		App 或单聊/群聊会话。

若在免打扰时段或时长生效期间需要对指定用户推送消息，需设置强制推送。

推送通知方式与免打扰时间设置之间的关系

对于 app 和 app 中的所有会话，免打扰模式的设置优先于推送通知方式的设置。例如，假设在 app 级别指定了免打扰时间段，并将指定会话的推送通知方式设置为 ALL。App 在指定的时间段内进入免打扰模式，你不会收到任何推送通知。

或者，假设为会话指定了免打扰时间段，而 app 没有任何免打扰设置并且其推送通知方式设置为 ALL。在指定的免打扰时间段内，你不会收到来自该会话的任何推送通知，而所有其他会话的推送保持不变。

设置 app 的推送通知

你可以调用 setSilentModeForAll 设置 app 级别的推送通知，并通过指定 ChatSilentModeParam 字段设置推送通知方式和免打扰模式，如下代码示例所示：

// convId：会话 ID。
// convType：会话类型。
// 将推送通知方式设置为 `MENTION_ONLY`。
const option = ChatSilentModeParam.constructorWithNotification(
  ChatPushRemindType.MENTION_ONLY
);
// 将免打扰时长设置为 10 分钟。
const option = ChatSilentModeParam.constructorWithDuration(10);
// 将免打扰时间段设置为 10:10-11:00。
const option = ChatSilentModeParam.constructorWithPeriod({
  startTime: new ChatSilentModeTime({ hour: 10, minute: 10 }),
  endTime: new ChatSilentModeTime({ hour: 11, minute: 10 }),
});
// 设置 app 的离线推送通知。
ChatClient.getInstance()
  .pushManager.setSilentModeForAll(option)
  .then(() => {
    console.log("Succeeded in setting the push notification.");
  })
  .catch((reason) => {
    console.log("Failed to set the push notification.", reason);
  });

获取 app 的推送通知设置

你可以调用 fetchSilentModeForAll 获取 app 级别的推送通知设置，如以下代码示例所示：

ChatClient.getInstance()
  .pushManager.fetchSilentModeForAll()
  .then((result) => {
    console.log("Succeeded in getting the push notification settings of the app.", result);
  })
  .catch((reason) => {
    console.log("Failed to get the push notification settings of the app.", reason);
  });

设置单个会话的推送通知

你可以调用 setSilentModeForConversation 方法设置指定会话的推送通知，并通过指定 ChatSilentModeParam 字段设置推送通知方式和免打扰模式，如以下代码示例所示：

// convId：会话 ID。
// convType：会话类型。
// 将推送通知方式设置为 `MENTION_ONLY`。
const option = ChatSilentModeParam.constructorWithNotification(
  ChatPushRemindType.MENTION_ONLY
);
// 将免打扰时长设置为 10 分钟。
const option = ChatSilentModeParam.constructorWithDuration(10);
// 将免打扰时间段设置为 10:10-11:00。
const option = ChatSilentModeParam.constructorWithPeriod({
  startTime: new ChatSilentModeTime({ hour: 10, minute: 10 }),
  endTime: new ChatSilentModeTime({ hour: 11, minute: 10 }),
});
// 设置指定会话的推送通知。
ChatClient.getInstance()
  .pushManager.setSilentModeForConversation({
    convId,
    convType,
    option,
  })
  .then(() => {
    console.log("Succeeded in getting the push notification settings of the conversation.");
  })
  .catch((reason) => {
    console.log("Failed to get the push notification settings of the conversation.", reason);
  });

获取单个会话的推送通知

你可以调用 fetchSilentModeForConversation 方法获取指定会话的推送通知设置，如以下代码示例所示：

// convId：会话 ID。
// convType：会话类型。
ChatClient.getInstance()
  .pushManager.fetchSilentModeForConversation({
    convId,
    convType,
  })
  .then(() => {
    console.log("Succeeded in getting the push notification settings of the conversation.");
  })
  .catch((reason) => {
    console.log("Failed to get the push notification settings of the conversation.", reason);
  });

获取多个会话的推送通知设置

  1. 你可以在每次调用中最多获取 20 个会话的推送通知设置。

  2. 如果会话使用了 app 设置或其推送通知设置已过期，则返回的字典不包含此会话。

你可以调用 fetchSilentModeForConversations 方法获取多个会话的推送通知设置，如以下示例代码所示：

// conversations：会话列表。
ChatClient.getInstance()
  .pushManager.fetchSilentModeForConversations(conversations)
  .then(() => {
    console.log("Succeeded in getting the conversation list.");
  })
  .catch((reason) => {
    console.log("Failed to get the conversation list.", reason);
  });

清除单个会话的推送通知方式的设置

你可以调用 removeSilentModeForConversation 方法清除指定会话的推送通知方式的设置。清除后，默认情况下，该会话会使用 app 的设置。

以下代码示例显示了如何清除会话的推送通知方式：

// convId：会话 ID。
// convType：会话类型。
ChatClient.getInstance()
  .pushManager.removeSilentModeForConversation({
    convId,
    convType,
  })
  .then(() => {
    console.log("Succeeded in deleting the push notification settings of the conversation.");
  })
  .catch((reason) => {
    console.log("Failed to delete the push notification settings of the conversation.", reason);
  });
环信 IM 文档 Version: 1.0.0 ©️环信