黑名单 - IM 即时通讯

开发者中心

IM 即时通讯

集成开发

黑名单

更新时间： 2025/07/16 17:47:16

网易云信即时通讯 SDK（NetEase IM SDK，简称 NIM SDK）提供用户黑名单的管理。

本文详细介绍了 NIM SDK 的用户黑名单管理功能。您将了解如何添加、移除黑名单用户，以及如何获取黑名单列表。本文还包含了各平台的代码示例，帮助开发者快速集成和使用黑名单功能。

支持平台

本文内容适用的开发平台或框架如下表所示，涉及的接口请参考下文相关接口章节：

安卓	iOS	macOS/Windows	Web/uni-app/小程序	Node.js/Electron	鸿蒙	Flutter
✔️️️️️️	✔️️️️️️	✔️️️️️️	✔️️️️️️	✔️️️️️️	✔️️️️️️	✔️️️

技术原理

NIM SDK 支持用户的黑名单列表管理。若需要屏蔽指定用户的消息，可以该用户拉入黑名单列表。

NIM SDK 通过维护一个用户级别的黑名单列表来实现黑名单功能。当一个用户被加入黑名单后，SDK 会在本地和服务器端同步这一信息。黑名单的实现主要涉及以下几个方面：

功能	描述
消息过滤	当收到消息时，SDK 会检查发送者是否在接收者的黑名单中。如果在，则会拦截该消息，不会传递给应用层。
发送限制	当用户尝试向将自己加入黑名单的用户发送消息时，SDK 会返回发送失败的错误。
实时更新	当黑名单发生变化时（如添加或移除用户），SDK 会触发相应的回调，使应用能够及时更新 UI。

黑名单操作的基本流程：

graph LR
    A[添加用户到黑名单] --> B[本地更新黑名单列表]
    B --> C[同步到云信服务器]
    C --> D[其他端同步黑名单变更]
    D --> E[触发黑名单变更回调]
    E --> F[更新 UI 显示]

前提条件

在使用黑名单功能之前，请确保您已完成以下步骤:

已实现登录 IM。
了解 NIM SDK 中黑名单功能的原理。

注意事项

每个账号可设置黑名单的上限为 3000。
当用户 A 将用户 B 拉黑：
- 用户 A 将不会再接收到用户 B 发送的任何消息。
- 用户 B 发送消息给用户 A 时，消息会发送失败，并提示已被对方拉黑。
- 用户 A 仍能发送消息给用户 B，B 可以正常接收。
当用户 A 将用户 B 拉黑后，用户 B 默认仍能对用户 A 发起呼叫（信令功能）。若需要使被拉黑者无法唤起呼叫，可以在网易云信控制台为应用开通 被拉黑时被拉黑者无法唤起呼叫 开关。
当用户 A 将用户 B 拉黑后，用户 A 仍能发送消息给用户 B，但是不会接收到用户 B 的消息（包括已读回执），因此在该场景下，用户 A 无法知晓发送给用户 B 的消息，用户 B 是否已读。若用户 A 需要知晓用户 B 是否已读，即需要接收用户 B 发送的消息已读回执，可以在网易云信控制台为应用开通 拉黑场景可以正常下发消息已读回执通知 开关。

黑名单配置.png

监听黑名单相关事件

在进行黑名单相关操作前，您可以提前注册相关事件。注册成功后，当黑名单相关事件发生时，SDK 会触发对应回调通知。

注册监听

黑名单相关回调：

onBlockListAdded：黑名单新增用户回调，返回新加入黑名单的用户列表。当客户端本端添加用户到黑名单，或者其他端同步添加用户到黑名单时触发该回调。
onBlockListRemoved：黑名单移除用户回调，返回移出黑名单的用户列表。当客户端本端从黑名单移除用户，或者其他端同步从黑名单移除用户时触发该回调。

示例代码：

安卓

调用 addUserListener 方法注册监听：

JavaNIMClient.getService(V2NIMUserService.class).addUserListener(new V2NIMUserListener() {
    @Override
    public void onBlockListAdded(V2NIMUser user) {
        // 处理新增黑名单用户的逻辑
        Log.d("BlackList", "User added to blacklist: " + user.getAccountId());
    }
    @Override
    public void onBlockListRemoved(String accountId) {
        // 处理移除黑名单用户的逻辑
        Log.d("BlackList", "User removed from blacklist: " + accountId);
    }
});

iOS

调用 addUserListener 方法注册监听：

Objective-C[[[NIMSDK sharedSDK] v2UserService] addUserListener:self];

- (void)onBlockListAdded:(V2NIMUser *)user {
    // 处理新增黑名单用户的逻辑
    NSLog(@"User added to blacklist: %@", user.accountId);
}

- (void)onBlockListRemoved:(NSString *)accountId {
    // 处理移除黑名单用户的逻辑
    NSLog(@"User removed from blacklist: %@", accountId);
}

macOS/Windows

调用 addUserListener 方法注册监听：

C++V2NIMUserListener listener;
listener.onBlockListAdded = [](V2NIMUser user) {
    // 处理新增黑名单用户的逻辑
    std::cout << "User added to blacklist: " << user.accountId << std::endl;
};
listener.onBlockListRemoved = [](std::string accountId) {
    // 处理移除黑名单用户的逻辑
    std::cout << "User removed from blacklist: " << accountId << std::endl;
};
userService.addUserListener(listener);

Web/uni-app/小程序

调用 on("EventName") 方法注册监听：

TypeScriptnim.V2NIMUserService.on("onBlockListAdded", function (user: V2NIMUser) {
    // 处理新增黑名单用户的逻辑
    console.log("User added to blacklist:", user.accountId);
})
nim.V2NIMUserService.on("onBlockListRemoved", function (accountId: string) {
    // 处理移除黑名单用户的逻辑
    console.log("User removed from blacklist:", accountId);
})

Node.js/Electron

调用 on("EventName") 方法注册监听：

TypeScriptv2.userService.on("blockListAdded", function (user: V2NIMUser) {
    // 处理新增黑名单用户的逻辑
    console.log("User added to blacklist:", user.accountId);
})
v2.userService.on("blockListRemoved", function (accountId: string) {
    // 处理移除黑名单用户的逻辑
    console.log("User removed from blacklist:", accountId);
})

鸿蒙

调用 on("EventName") 方法注册监听：

TypeScriptnim.userService.on("onBlockListAdded", function (user: V2NIMUser) {
    // 处理新增黑名单用户的逻辑
    console.log("User added to blacklist:", user.accountId);
})
nim.userService.on("onBlockListRemoved", function (accountId: string) {
    // 处理移除黑名单用户的逻辑
    console.log("User removed from blacklist:", accountId);
})

Flutter

调用 listen 方法注册监听：

Dartsubsriptions.add(NimCore.instance.userService.onBlockListAdded.listen((e) {
    // 处理新增黑名单用户的逻辑
    print("User added to blacklist: ${e.accountId}");
}));

subsriptions.add(NimCore.instance.userService.onBlockListRemoved.listen((e) {
    // 处理移除黑名单用户的逻辑
    print("User removed from blacklist: $e");
}));

移除监听

安卓

如需移除黑名单相关监听器，可调用 removeUserListener 方法。

JavaNIMClient.getService(V2NIMUserService.class).removeUserListener(listener);

iOS

如需移除黑名单相关监听器，可调用 removeUserListener 方法。

Objective-C[[[NIMSDK sharedSDK] v2UserService] removeUserListener:self];

macOS/Windows

如需移除黑名单相关监听器，可调用 removeUserListener 方法。

C++userService.removeUserListener(listener);

Web/uni-app/小程序

如需移除黑名单相关监听器，可调用 off("EventName") 方法。

TypeScriptnim.V2NIMUserService.off("onBlockListAdded", function (user: V2NIMUser) {})
nim.V2NIMUserService.off("onBlockListRemoved", function (accountId: string) {})

Node.js/Electron

如需移除黑名单相关监听器，可调用 off("EventName") 方法。

TypeScriptv2.userService.off("blockListAdded", function (user: V2NIMUser) {})
v2.userService.off("blockListRemoved", function (accountId: string) {})

鸿蒙

如需移除黑名单相关监听器，可调用 off("EventName") 方法。

TypeScriptnim.userService.off("onBlockListAdded", function (user: V2NIMUser) {})
nim.userService.off("onBlockListRemoved", function (accountId: string) {})

Flutter

如需移除黑名单相关监听器，可调用 cancel 方法。

Dartsubsriptions.forEach((subsription) {
    subsription.cancel();
});

添加指定用户进黑名单

调用 addUserToBlockList 方法将指定用户添加进黑名单，即拉黑指定用户。添加成功后，SDK 会返回黑名单用户新增回调 onBlockListAdded。

如果指定用户被加入了黑名单，那么就不再会收到此用户发送的任何消息。但是对于指定用户而言，不受影响。例如：A 用户将 B 用户加入黑名单，B 用户发送的消息，A 用户将接收不到。但是 A 用户发送的消息，B 用户依然可以接收到。

示例代码：

安卓

JavaNIMClient.getService(V2NIMUserService.class).addUserToBlockList(accountId,
new V2NIMSuccessCallback<Void>() {
    @Override
    public void onSuccess(Void unused) {
        // 添加成功,可以在这里更新UI或执行其他操作
        Log.d("BlackList", "User successfully added to blacklist");
    }
},
new V2NIMFailureCallback() {
    @Override
    public void onFailure(V2NIMError error) {
        // 添加失败,处理错误
        Log.e("BlackList", "Failed to add user to blacklist: " + error.getMessage());
    }
});

iOS

Objective-C[[[NIMSDK sharedSDK] v2UserService] addUserToBlockList:@"accountId" success:^{
    // 添加成功,可以在这里更新UI或执行其他操作
    NSLog(@"User successfully added to blacklist");
} failure:^(V2NIMError * _Nonnull error) {
    // 添加失败,处理错误
    NSLog(@"Failed to add user to blacklist: %@", error.localizedDescription);
}];

macOS/Windows

C++userService.addUserToBlockList(
    "account1",
    []() {
        // 添加成功,可以在这里更新UI或执行其他操作
        std::cout << "User successfully added to blacklist" << std::endl;
    },
    [](V2NIMError error) {
        // 添加失败,处理错误
        std::cerr << "Failed to add user to blacklist: " << error.message << std::endl;
    }
);

Web/uni-app/小程序

TypeScripttry {
    await nim.V2NIMUserService.addUserToBlockList('accountId');
    console.log("User successfully added to blacklist");
    // 添加成功,可以在这里更新UI或执行其他操作
} catch (error) {
    console.error("Failed to add user to blacklist:", error);
    // 添加失败,处理错误
}

Node.js/Electron

TypeScripttry {
    await v2.userService.addUserToBlockList(accountId);
    console.log("User successfully added to blacklist");
    // 添加成功,可以在这里更新UI或执行其他操作
} catch (error) {
    console.error("Failed to add user to blacklist:", error);
    // 添加失败,处理错误
}

鸿蒙

TypeScripttry {
    await nim.userService.addUserToBlockList('accountId');
    console.log("User successfully added to blacklist");
    // 添加成功,可以在这里更新UI或执行其他操作
} catch (error) {
    console.error("Failed to add user to blacklist:", error);
    // 添加失败,处理错误
}

Flutter

Darttry {
    await NimCore.instance.userService.addUserToBlockList(accountId);
    print("User successfully added to blacklist");
    // 添加成功,可以在这里更新UI或执行其他操作
} catch (error) {
    print("Failed to add user to blacklist: $error");
    // 添加失败,处理错误
}

将指定用户移出黑名单

调用 removeUserFromBlockList 方法将指定用户移出黑名单。移除成功后，SDK 会返回黑名单用户移除回调 onBlockListRemoved。

如果一个用户被从黑名单移除，那么会重新收到此用户发送的消息。移出黑名单操作不会影响之前被拦截的消息，那些消息仍然不会被接收。

示例代码：

安卓

JavaNIMClient.getService(V2NIMUserService.class).removeUserFromBlockList(accountId, 
new V2NIMSuccessCallback<Void>() {
    @Override
    public void onSuccess(Void unused) {
        // 移除成功,可以在这里更新UI或执行其他操作
        Log.d("BlackList", "User successfully removed from blacklist");
    }
}, 
new V2NIMFailureCallback() {
    @Override
    public void onFailure(V2NIMError error) {
        // 移除失败,处理错误
        Log.e("BlackList", "Failed to remove user from blacklist: " + error.getMessage());
    }
});

iOS

Objective-C[[[NIMSDK sharedSDK] v2UserService] removeUserFromBlockList:@"accountId" success:^{
    // 移除成功,可以在这里更新UI或执行其他操作
    NSLog(@"User successfully removed from blacklist");
} failure:^(V2NIMError * _Nonnull error) {
    // 移除失败,处理错误
    NSLog(@"Failed to remove user from blacklist: %@", error.localizedDescription);
}];

macOS/Windows

C++userService.removeUserFromBlockList(
    "account1",
    []() {
        // 移除成功,可以在这里更新UI或执行其他操作
        std::cout << "User successfully removed from blacklist" << std::endl;
    },
    [](V2NIMError error) {
        // 移除失败,处理错误
        std::cerr << "Failed to remove user from blacklist: " << error.message << std::endl;
    });

Web/uni-app/小程序

TypeScripttry {
    await nim.V2NIMUserService.removeUserFromBlockList('accountId');
    console.log("User successfully removed from blacklist");
    // 移除成功,可以在这里更新UI或执行其他操作
} catch (error) {
    console.error("Failed to remove user from blacklist:", error);
    // 移除失败,处理错误
}

Node.js/Electron

TypeScripttry {
    await v2.userService.removeUserFromBlockList(accountId);
    console.log("User successfully removed from blacklist");
    // 移除成功,可以在这里更新UI或执行其他操作
} catch (error) {
    console.error("Failed to remove user from blacklist:", error);
    // 移除失败,处理错误
}

鸿蒙

TypeScripttry {
    await nim.userService.removeUserFromBlockList('accountId');
    console.log("User successfully removed from blacklist");
    // 移除成功,可以在这里更新UI或执行其他操作
} catch (error) {
    console.error("Failed to remove user from blacklist:", error);
    // 移除失败,处理错误
}

Flutter

Darttry {
    await NimCore.instance.userService.removeUserFromBlockList(accountId);
    print("User successfully removed from blacklist");
    // 移除成功,可以在这里更新UI或执行其他操作
} catch (error) {
    print("Failed to remove user from blacklist: $error");
    // 移除失败,处理错误
}

获取黑名单用户

调用 getBlockList 方法获取黑名单用户列表，查看已拉黑的用户。

获取黑名单列表可能需要一定时间，特别是在黑名单用户较多的情况下。建议在应用启动时获取一次黑名单列表，并在本地缓存，后续可通过监听黑名单变更事件来更新缓存。

示例代码：

安卓

JavaNIMClient.getService(V2NIMUserService.class).getBlockList(
    new V2NIMSuccessCallback<List<String>>() {
        @Override
        public void onSuccess(List<String> blockList) {
            // 获取成功,处理黑名单列表
            Log.d("BlackList", "Block list retrieved: " + blockList.toString());
        }
    },
    new V2NIMFailureCallback() {
        @Override
        public void onFailure(V2NIMError error) {
            // 获取失败,处理错误
            Log.e("BlackList", "Failed to get block list: " + error.getMessage());
        }
    }
);

iOS

Objective-C[[[NIMSDK sharedSDK] v2UserService] getBlockList:^(NSArray<NSString *> * _Nonnull blockList) {
    // 获取成功,处理黑名单列表
    NSLog(@"Block list retrieved: %@", blockList);
} failure:^(V2NIMError * _Nonnull error) {
    // 获取失败,处理错误
    NSLog(@"Failed to get block list: %@", error.localizedDescription);
}];

macOS/Windows

C++userService.getBlockList(
    [](std::vector<std::string> blockList) {
        // 获取成功,处理黑名单列表
        std::cout << "Block list retrieved:" << std::endl;
        for (const auto& accountId : blockList) {
            std::cout << accountId << std::endl;
        }
    },
    [](V2NIMError error) {
        // 获取失败,处理错误
        std::cerr << "Failed to get block list: " << error.message << std::endl;
    });

Web/uni-app/小程序

TypeScripttry {
    const blockList = await nim.V2NIMUserService.getBlockList();
    console.log("Block list retrieved:", blockList);
    // 获取成功,处理黑名单列表
} catch (error) {
    console.error("Failed to get block list:", error);
    // 获取失败,处理错误
}

Node.js/Electron

TypeScripttry {
    const blockList = await v2.userService.getBlockList();
    console.log("Block list retrieved:", blockList);
    // 获取成功,处理黑名单列表
} catch (error) {
    console.error("Failed to get block list:", error);
    // 获取失败,处理错误
}

鸿蒙

TypeScripttry {
    const blockList = await nim.userService.getBlockList();
    console.log("Block list retrieved:", blockList);
    // 获取成功,处理黑名单列表
} catch (error) {
    console.error("Failed to get block list:", error);
    // 获取失败,处理错误
}

Flutter

Darttry {
    final blockList = await NimCore.instance.userService.getBlockList();
    print("Block list retrieved: $blockList");
    // 获取成功,处理黑名单列表
} catch (error) {
    print("Failed to get block list: $error");
    // 获取失败,处理错误
}

查看是否在黑名单

查看指定用户是否在黑名单中。

返回 true 的账号表示在黑名单中，若不在黑名单，或者账号不存在则统一返回 false。

示例代码

Android

JavaList<String> accountIds = new ArrayList<>();
accountIds.add("accountId1");
accountIds.add("accountId2");
accountIds.add("accountId3");

NIMClient.getService(V2NIMUserService.class).checkBlock(accountIds, 
    new V2NIMSuccessCallback<Map<String, Boolean>>() {
        @Override
        public void onSuccess(Map<String, Boolean> result) {
            // 返回结果为 Map，key 是 accountId，value 是是否在黑名单中（true 代表在黑名单中）
            for (Map.Entry<String, Boolean> entry : result.entrySet()) {
                String accountId = entry.getKey();
                boolean isBlocked = entry.getValue();
                Log.d("CheckBlock", "Account: " + accountId + ", isBlocked: " + isBlocked);
            }
        }
    }, 
    new V2NIMFailureCallback() {
        @Override
        public void onFailure(int code, String errorMsg) {
            Log.e("CheckBlock", "Error code: " + code + ", message: " + errorMsg);
        }
    }
);

iOS

Objective-CNSArray<NSString *> *accountIds = @[@"accountId1", @"accountId2", @"accountId3"];
// 结构：key: <accountId: NSString>, value: <isBlocked: NSNumber>。
NSDictionary <NSString *, NSNumber *> *blockDict = [[NIMSDK sharedSDK].v2UserService checkBlock:accountIds];

macOS/Windows

C++nstd::vector<nstd::string> accountIds = {"test1", "test2"};
userService.checkBlock(
    accountIds,
    [](const nstd::map<nstd::string, bool>& result) {
        for (auto&& item : result) {
            // do something
        }
    },
    [](V2NIMError error) {
        // check blocklist failed, handle error
    });

Web/uni-app/小程序

TypeScriptconst accountIds: string[] = ['accountId1', 'accountId2', 'accountId3'];
nim.V2NIMUserService.checkBlock(accountIds)

Node.js/Electron

TypeScriptconst result = await v2.userService.checkBlock(['accountId1', 'accountId2'])
// handle result

鸿蒙

TypeScriptconst accountIds: string[] = ['accountId1', 'accountId2', 'accountId3'];
try {
  const result: Map<string, boolean> = await nim.userService.checkBlock(accountIds);
} catch (error) {
  console.error('checkBlock Error:', err)
}

Flutter

dartNimCore.instance.userService.checkBlock(['test']).then((result) {

});

API	说明
`addUserListener`	注册用户资料相关监听器
`removeUserListener`	取消注册用户资料相关监听器
`addUserToBlockList`	添加指定用户进黑名单
`removeUserFromBlockList`	将指定用户移出黑名单
`getBlockList`	获取黑名单用户列表
`checkBlock`	查看指定用户是否在黑名单中

API	说明
`on("EventName")`	注册用户资料相关监听器
`off("EventName")`	取消注册用户资料相关监听器
`addUserToBlockList`	添加指定用户进黑名单
`removeUserFromBlockList`	将指定用户移出黑名单
`getBlockList`	获取黑名单用户列表
`checkBlock`	查看指定用户是否在黑名单中

API	说明
`listen`	注册用户资料相关监听器
`cancel`	取消注册用户资料相关监听器
`addUserToBlockList`	添加指定用户进黑名单
`removeUserFromBlockList`	将指定用户移出黑名单
`getBlockList`	获取黑名单用户列表
`checkBlock`	查看指定用户是否在黑名单中

常见问题

Q: 将用户加入黑名单后，之前的聊天记录会怎样？

A: 加入黑名单不会删除之前的聊天记录，但会阻止接收该用户的新消息。

Q: 黑名单是双向的吗？

A: 不是。如果用户 A 将用户 B 加入黑名单，只会阻止 A 接收 B 的消息，不会影响 B 接收 A 的消息。

Q: 黑名单有数量限制吗？

A: 是的，每个账号最多可以将 3000 个用户加入黑名单。

Q: 如何处理黑名单同步问题？

A: SDK 会自动同步黑名单信息到所有登录设备。您只需要监听黑名单变更事件并更新 UI 即可。

Q: 被加入黑名单的用户会收到通知吗？

A: 不会。被加入黑名单的用户不会收到任何通知，只会在尝试发送消息时收到发送失败的提示。

此文档是否对你有帮助？

有帮助

去反馈

支持平台
技术原理
前提条件
注意事项
监听黑名单相关事件
注册监听
移除监听
添加指定用户进黑名单
将指定用户移出黑名单
获取黑名单用户
查看是否在黑名单
相关接口
常见问题