设置推送扩展功能

小于 1 分钟

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

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

开通功能

推送通知方式 和 免打扰模式 是推送的高级功能。使用前，你需要在 声网控制台open in new window 免费开通。激活后，如需关闭推送高级功能，必须联系商务，因为该操作会删除高级功能相关的所有配置。

  1. 展开控制台左上角下拉框，选择需要开通即时通讯 IM 服务的项目。

  2. 点击左侧导航栏的全部产品。

  3. 在下拉列表中找到即时通讯 IM 并点击。

  4. 在即时通讯 IM 页面，进入功能配置标签页。

  5. 在推送模板 页签下，点击启用。

  6. 在弹出的对话框中，配置用户相关参数，点击确定。

image

推送通知方式

会话级别的推送通知方式设置优先于 app 级别的设置，未设置推送通知方式的会话默认采用 app 的设置。

例如，假设 app 的推送方式设置为 AT，而指定会话的推送方式设置为 ALL。你会收到来自该会话的所有推送通知，而对于其他会话来说，你只会收到提及你的消息的推送通知。

推送通知方式参数

描述

应用范围

ALL

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

 

App 或单聊/群聊会话

AT

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

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

NONE

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

 

免打扰模式

完成 SDK 初始化和成功登录 app 后，你可以对 app 以及各类型的会话开启离线推送功能以及通过设置免打扰模式关闭推送。

  • 你可以通过 startTime 和 endTime 参数开启全天免打扰和关闭免打扰模式：若开始时间和结束时间相同，免打扰模式则全天生效；若设置为 0:0-0:0，则关闭免打扰模式。
  • 你可以在 app 级别指定免打扰时间段和免打扰时长，即时通讯 IM 在这两个时间段内不发送离线推送通知。若既设置了免打扰时间段，又设置了免打扰时长，免打扰模式的生效时间为这两个时间段的累加。

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

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

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

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

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

设置 app 的推送通知

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

/**
  options // 推送通知配置选项。
	options: {
    paramType: 0, // 推送通知方式。
    remindType: 'ALL' // 可设置为 `ALL`、`AT` 或 `NONE`。
  }
  options: {
    paramType: 1, // 免打扰时长。
    duration: 7200000 // 免打扰时长，单位为毫秒。
  }
  options: {
    paramType: 2, // 免打扰时间段。
    startTime: {
    	hours: 8, // 免打扰时间段的开始时间中的小时数。
    	minutes: 0 // 免打扰时间段的开始时间中的分钟数。
    }，
    endTime: {
    	hours: 12, // 免打扰时间段的结束时间中的小时数。
    	minutes: 0 // 免打扰时间段的结束时间中的分钟数。
    }
  }
*/
const params = {
  options: {
    paramType: 0,
    remindType: 'ALL'
  }
}
WebIM.conn.setSilentModeForAll(params)

获取 app 的推送通知设置

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

// 无需传参数，直接调用。
WebIM.conn.getSilentModeForAll()

获取设置了推送通知方式的所有会话

你可以调用 getSilentModeRemindTypeConversations 方法获取设置了推送通知方式的所有会话。

推送通知方式包含以下三类：接收所有离线消息的推送通知、仅接收提及某些用户的消息的推送通知、不接收离线消息的推送通知。

// pageSize 的取值范围为 [1,100]，默认值为 10。
conn.getSilentModeRemindTypeConversations({pageSize: 10})

设置单个会话的推送通知

你可以调用 setSilentModeForConversation 设置指定会话的推送通知设置，即推送通知方式或免打扰时长，示例代码如下。

调用该接口后，你的其他设备会收到 onMultiDeviceEvent#setSilentModeForConversation 事件。

/**
	const params = {
    conversationId: 'test', // 会话 ID：单聊为对方用户 ID，群聊为群组 ID，聊天室会话为聊天室 ID。
    type: 'singleChat', // 会话类型：singleChat（单聊）、groupChat（群聊）和 chatRoom（聊天室）。
    options: {
      paramType: 0, // 推送通知方式。
      remindType: 'ALL' // 可设置为 `ALL`、`AT` 或 `NONE`。
    }
  }
	
	const params = {
    conversationId: '12345567',
    type: 'groupChat',
    options: {
      paramType: 1, // 免打扰时长。
      duration: 7200000 // 免打扰时长，单位为毫秒。
    }
  }
*/
const params = {
  conversationId: '12345',
  type: 'groupChat',
  options: {
    paramType: 0, // 会话暂不支持设置免打扰时间段，只能设置APP级别的免打扰时间段。
    remindType: 'ALL'
  }
}
WebIM.conn.setSilentModeForConversation(params)

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

调用 getSilentModeForConversation 获取单个会话的推送通知设置，示例代码如下：

const params = {
  conversationId: 'test', // 会话 ID：单聊为对方用户 ID，群聊为群组 ID，聊天室会话为聊天室 ID。
  type: 'singleChat', // 会话类型：singleChat（单聊）、groupChat（群聊）和 chatRoom（聊天室）。
}
WebIM.conn.getSilentModeForConversation(params)

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

  1. 每次最多可获取 20 个会话的推送通知设置。
  2. 如果会话继承了 app 设置或其推送通知设置已过期，则返回的字典不包含此会话。

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

const params = {
  conversationList: [
    {
      id: 'test', // 会话 ID：单聊为对方用户 ID，群聊为群组 ID，聊天室会话为聊天室 ID。
      type: 'singleChat' // 会话类型：singleChat（单聊）、groupChat（群聊）和 chatRoom（聊天室）。
    },
    {
      id: '1234',
      type: 'groupChat'
    }
  ]
}
WebIM.conn.getSilentModeForConversations(params)

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

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

调用该接口后，你的其他设备会收到 onMultiDeviceEvent#removeSilentModeForConversation 事件。

示例代码如下：

const params = {
  conversationId: '12345', // 会话 ID：单聊为对方用户 ID，群聊为群组 ID，聊天室会话为聊天室 ID。
  type: 'groupChat', // 会话类型：singleChat（单聊）、groupChat（群聊）或 chatRoom（聊天室）。
}
WebIM.conn.clearRemindTypeForConversation(params)
上次编辑于:
声网 IM 文档
© 声网 2026