圈组系统通知概览

系统通知可分为内置系统通知和自定义系统通知。

系统通知类型	说明	离线系统通知限制
内置系统通知	圈组内置的系统通知, 类型包括“邀请服务器成员”、“踢除服务器成员”、“修改频道信息” 等	服务器成员管理事件的系统通知支持存离线，每月至多存 1,000 条离线通知。其他内置系统通知不存离线
自定义系统通知	开发者自定义系统通知。 SDK 不解析自定义系统通知，仅负责传递	每月 1,000 条离线通知

内置系统通知分类

圈组内置系统通知，可进一步分为服务器成员管理事件的系统通知、服务器其他相关事件的系统通知、频道事件系统通知、频道分组事件系统通知、身份组成员管理事件的系统通知和身份组权限事件系统通知。除了服务器成员管理事件的系统通知，其余类型都通过参与者与观察者机制控制接收人及其接收条件。

每个类型的具体触发条件和接收条件，请参考服务端的圈组系统通知。

技术原理

圈组中的系统通知时由云信服务器下发给用户的通知类消息，用于包括创建 Server、创建 Channel、申请加入 Server 等事件的通知。 SDK 中的 QChatMsgServiceInterface 模块提供 QChatSystemNotification 结构定义圈组的系统通知。

QChatSystemNotification 结构的重要参数如下：

参数	类型	说明
serverId	string	通知所属的圈组服务器的 ID
channelId	string	通知所属的频道的 ID
toAccids	string[]	通知接收者账号列表
fromAccount	string	通知发送者的网易云信账号 ID
type	TSystemMessageType	系统通知类型，字符串，具体的系统通知类型可参考 ESystemMessageType
time	number	通知发送成功的时间戳(毫秒)
updateTime	number	通知更新时间戳
msgIdClient	string	客户端生成的通知 ID, 主键，可做去重
msgIdServer	string	服务器生成的通知 ID，全局唯一
body	string	通知内容
attach	object	通知附件
status	number	状态，默认为 0。大于 10,000 为用户自定义的状态
persistEnable	boolean	是否存离线，只有 toAccids 不为空，才能设置为存离线
pushEnable	boolean	是否需要推送，默认false
needBadge	boolean	是否需要计数

实现方法

发送自定义系统通知

SDK 提供发送自定义系统通知的能力，完整参数见 QChatMsgServiceInterface-sendSystemNotification。

js/**
 * 发送自定义系统通知
 *
 * 自定义系统通知属于系统通知, 可用于更自由的离线通知某些账号。SDK 不会解析这些通知, SDK 仅仅负责传递这些通知。
 *
 * 那么系统消息的接收者会收到 {@link QChatEventInterface.systemNotification | systemNotification} 事件
 */
sendSystemNotification(options: SendSystemNotificationOptions): Promise<QChatSystemNotification>

调用 sendSystemNotification 方法，调用时传入自定义系统通知入参 SendSystemNotificationOptions，即可实现发送自定义系统通知。

根据 SendSystemNotificationOptions 中传入的 serverId、channelId、toAccids 的不同，可自定义通知范围，包括：

• 通知指定服务器下所有成员
• 通知所有订阅过指定频道的成员
• 通知指定服务器下指定账号成员
• 通知订阅过指定频道的指定账号成员

频道下人数小于某个阈值时，是默认订阅的。超过某个阈值需要手动订阅。

示例代码：

js// 1.
await qchat.qchatMsg.sendSystemNotification({
  "serverId": "{{YOUR_SERVER_ID}}",
  "body": "notify all member from server"
})

// 2.
await qchat.qchatMsg.sendSystemNotification({
  "serverId": "{{YOUR_SERVER_ID}}",
  "channelId": "{{YOUR_CHANNEL_ID}}",
  "body": "notify all member from channel"
})

// 3.
await qchat.qchatMsg.sendSystemNotification({
  "serverId": "{{YOUR_SERVER_ID}}",
  "toAccids": ["YOUR_ACCOUNT_ID1", "YOUR_ACCOUNT_ID2"],
  "body": "notify some member from server"
})

// 4.
await qchat.qchatMsg.sendSystemNotification({
  "serverId": "{{YOUR_SERVER_ID}}",
  "channelId": "{{YOUR_CHANNEL_ID}}",
  "toAccids": ["YOUR_ACCOUNT_ID1", "YOUR_ACCOUNT_ID2"],
  "body": "notify some member from channel"
})

系统通知接收监听

初始化事件systemNotification, 参见 TS 定义 QChatInterface-QChatEventInterface-systemNotification，可以通过注册监听的方式监听圈组中发送给自己的系统通知。

示例代码

jsconst qchat = new QChatSDK({
  ... 
})
qchat.on('systemNotification', function (systemNotification) {
  console.log('receive a systemNotification', systemNotification)
})

await qchat.login()

更新系统通知

updateSystemNotification对于已发送的系统通知，可以修改系统通知中部分信息。完整参数参见 QChatMsgServiceInterface-updateSystemNotification。

js/**
 * 更新系统通知
 *
 * 注意：满足两个条件才可以更新通知，否则返回 414
 *
 * 1. 该系统通知存离线(msgIdServer 不为 0);
 * 2. 操作人是系统通知的接收者
 */
updateSystemNotification(options: UpdateSystemNotificationOptions): Promise<QChatSystemNotification>

其中，UpdateSystemNotificationOptions 是更新系统通知的入参，必填 msgIdServer、type。选填 body、ext、status 作为可更新的内容。

示例代码

jslet notification = await qchat.qchatMsg.sendSystemNotification({
  "serverId": "{{YOUR_SERVER_ID}}",
  "body": "notify all member from server"
})

notification = await qchat.qchatMsg.updateSystemNotification({
  "msgIdServer": notification.msgIdServer,
  "type": notification.type,
  "body": "I Change the notification"
})

系统通知更新状态监听

初始化事件systemNotificationUpdate, 参见 TS 定义 QChatInterface-QChatEventInterface-systemNotificationUpdate，可以通过注册监听的方式监听圈组中发送给自己的系统通知更新状态。

示例代码

jsconst qchat = new QChatSDK({
  ... 
})
qchat.on('systemNotificationUpdate', function (systemNotification) {
  console.log('receive a systemNotificationUpdate', systemNotification)
})

await qchat.login()

系统通知标志已读

可以对系统通知标记已读。标记已读后的系统通知将从服务端删除，后续不会在其他端接收到了。参见 TS 定义 QChatMsgServiceInterface-markSystemNotificationsRead。

js/**
 * 标记消息已读，下次登陆不会再同步到此通知
 * 注意：标记已读后，也无法再次修改这条通知。
 */
markSystemNotificationsRead(options: MarkSystemNotificationsReadOptions): Promise<void>

其中，MarkSystemNotificationsReadOptions 是标记系统通知已读的入参。

示例代码

jsconst qchat = new QChatSDK({
  ... 
})
qchat.on('systemNotification', async function (systemNotification) {
  console.log('receive a systemNotification', systemNotification)

  await qchat.qchatMsg.markSystemNotificationsRead({
    systemNotifications: systemNotifications
  })

  console.log('mark success')
})

await qchat.login()