文档中心
即时通讯
服务端 API
会话相关
设置会话消息免打扰

设置会话消息免打扰

更新时间：2024-09-18 16:57

描述

调用过此接口，可批量设置单聊或群聊会话的消息免打扰状态。设置为免打扰后，ZIM SDK 将不会向用户推送相关会话的消息通知，同时用户的“消息未读总数”也不会增加。

用户默认最多可对 500 个单聊会话设置为免打扰。如需上调，请联系 ZEGO 技术支持，最多可为 1000。

群聊会话的免打扰上限是各用户加入群组的数量上限。

客户端将通过 ZIM SDK 的回调接口，接收会话的消息免打扰状态变化。

iOS	Android	macOS	Windows	Web
conversationChanged	onConversationChanged	conversationChanged	onConversationChanged	conversationChanged
小程序	Flutter	React Native	uni-app	Unity3D
conversationChanged	onConversationChanged	conversationChanged	conversationChanged	OnConversationChanged

接口原型

请求方法：POST
请求地址：https://zim-api.zego.im/?Action=SilenceConvNotification
传输协议：HTTPS
调用频率限制：20次/秒。

请求参数

以下请求参数列表仅列出了接口请求参数和部分公共参数，完整公共参数列表请参考调用方式 - 公共请求参数。

参数	类型	是否必选	描述
FromUserId	String	是	请求设置该 UserID 的会话消息免打扰状态。
ConvType	Number	是	会话类型： 0：单聊会话。 2：群聊会话。
ConvIds	Array of String	是	待设置免打扰状态的会话 ID 列表，长度不超过 10。此列表中的会话类型需保持一致，否则会导致接口调用失败。
Enable	Boolean	是	是否免打扰： true：开启免打扰。 false：取消免打扰。

FromUserId 仅支持数字，英文字符和 '!'，'#'，'$'，'%'，'&'，'('，')'，'+'，'-'，':'，';'，'<'，'='，'.'，'>'，'?'，'@'，'['，']'，'^'，'_'，' '，'{'，'}'，'|'，'~'。

请求示例

请求地址 URL：

https://zim-api.zego.im/?Action=SilenceConvNotification
&<公共请求参数>

请求消息体：

{
    "FromUserId": "userA",
    "ConvIds": [
        "ConvId1",
        "ConvId2",
    ],
    "ConvType": 0,
    "Enable": true
}

响应参数

参数	类型	描述
Code	Number	返回码。当您发起请求修改多个会话的免打扰状态时：只需成功修改 1 个或以上会话的状态，Code 都会返回 0，表示成功。此时请参考 ErrorList 中的具体信息，了解会话修改状态失败详情。如果所有会话的状态都修改失败，Code 会返回相关返回码，具体请参考全局返回码。
Message	String	请求结果的说明信息。
RequestId	String	请求 ID。
ErrorList	Array of Object	失败列表。 Code 为 0： ErrorList 为空，全部会话的免打扰状态修改成功。 ErrorList 不为空，表示部分会话的免打扰状态修改失败。请参考 SubCode、SubMessage 处理。 Code 不为 0： ErrorList 为空，表示参数错误、接口频率限制、系统错误。 ErrorList 不为空，表示全部会话免打扰状态都修改失败。
ConvId	String	免打扰状态修改失败的会话 ID。
SubCode	Number	免打扰状态修改失败的具体错误码。
SubMessage	String	免打扰状态修改失败的具体错误描述。

响应示例

{
    "Code": 0,
    "Message": "success",
    "RequestId": "343649807833778782",
    "ErrorList": [
        {
            "ConvId": "ConvId1",
            "SubCode": 660800030,
            "SubMessage": "input params error"
        }
    ]
}

返回码

以下仅列出了接口业务逻辑相关的返回码，完整返回码请参考全局返回码。

返回码	说明	处理建议
660000001	业务类通用错误。	请重试，或联系 ZEGO 技术支持。
660000002	输入参数错误。	请检查输入的参数。
660300005	调用接口的频率超出了 AppID 级别限制。	请稍后再试。
660500002	FromUserId 未注册。	请先注册 FromUserId。
660600001	群组不存在。	请确认输入的 GroupId 是否正确。
660600009	获取群相关信息失败。	请先确认 GroupID 是否正确。如果正确，请联系 ZEGO 技术支持。
660600024	FromUserId 不在目标群组中。	请先加入该群组。
660700015	如果此错误码是 code，表示所有单聊会话的对端用户都未注册。如果此错误码是 subCode，表示 ConvID 对应的单聊会话对端用户未注册。	请先注册对端用户。
660800030	用户的免打扰列表超过长度限制，默认 500，可联系技术支持配置，最大可为 1000。	请联系 ZEGO 技术支持。
660800051	会话已为免打扰，无法再次设置为免打扰。	无需处理。
660800052	会话已被取消免打扰，无法再次取消。	无需处理