Friend API

NTQQFriendApi methods for managing friends and friend requests

Overview

The NTQQFriendApi class provides methods for managing friend lists, handling friend requests, and performing friend-related operations.

Friend List

getBuddy

Get the complete friend list.

async getBuddy(): Promise<FriendV2[]>

return · FriendV2[]

Array of friend objects with detailed information

Example:

const friends = await core.apis.FriendApi.getBuddy();
friends.forEach(friend => {
  console.log(`${friend.nick} (${friend.uin})`);
});

getBuddyV2SimpleInfoMap

Get friend list as a map of UID to user info.

async getBuddyV2SimpleInfoMap(): Promise<Map<string, FriendV2>>

return · Map<string, FriendV2>

Map with UID as key and friend info as value

getBuddyIdMap

Get a map of UIN to UID for friends.

async getBuddyIdMap(): Promise<LimitedHashTable<string, string>>

return · LimitedHashTable<string, string>

Hash table mapping UIN to UID

Example:

const idMap = await core.apis.FriendApi.getBuddyIdMap();
const uid = idMap.get('123456789'); // Get UID from UIN

getBuddyV2ExWithCate

Get friend list with category information.

async getBuddyV2ExWithCate(): Promise<Array<{
  categoryId: number;
  categorySortId: number;
  categoryName: string;
  categoryMbCount: number;
  onlineCount: number;
  buddyList: FriendV2[];
}>>

return · Array<CategoryInfo>

Array of friend categories with their members

Example:

const categories = await core.apis.FriendApi.getBuddyV2ExWithCate();
categories.forEach(cat => {
  console.log(`Category: ${cat.categoryName}`);
  console.log(`Friends: ${cat.categoryMbCount}`);
  console.log(`Online: ${cat.onlineCount}`);
  cat.buddyList.forEach(friend => {
    console.log(`  - ${friend.nick}`);
  });
});

Friend Management

isBuddy

Check if a user is a friend.

async isBuddy(uid: string): Promise<boolean>

uid · string · required

User UID to check

return · boolean

true if user is a friend, false otherwise

Example:

const isFriend = await core.apis.FriendApi.isBuddy('u_abc123');
if (isFriend) {
  console.log('User is already a friend');
}

setBuddyRemark

Set remark/note for a friend.

async setBuddyRemark(uid: string, remark: string)

uid · string · required

Friend UID

remark · string · required

New remark text

Example:

await core.apis.FriendApi.setBuddyRemark('u_abc123', 'My Best Friend');

delBuddy

Delete a friend.

async delBuddy(
  uid: string,
  tempBlock: boolean = false,
  tempBothDel: boolean = false
)

uid · string · required

Friend UID to delete

tempBlock · boolean · default: "false"

Whether to temporarily block the user

tempBothDel · boolean · default: "false"

Whether to delete from both sides

Example:

// Simple delete
await core.apis.FriendApi.delBuddy('u_abc123');

// Delete and block
await core.apis.FriendApi.delBuddy('u_abc123', true);

Friend Requests

getBuddyReq

Get list of pending friend requests.

async getBuddyReq(): Promise<FriendRequest[]>

return · FriendRequest[]

Array of friend request objects

Example:

const requests = await core.apis.FriendApi.getBuddyReq();
requests.forEach(req => {
  console.log(`Request from: ${req.friendNick}`);
  console.log(`Message: ${req.extWords}`);
});

handleFriendRequest

Approve or reject a friend request.

async handleFriendRequest(
  notify: FriendRequest,
  accept: boolean
)

notify · FriendRequest · required

Friend request object from getBuddyReq()

accept · boolean · required

true to accept, false to reject

Example:

const requests = await core.apis.FriendApi.getBuddyReq();

for (const req of requests) {
  // Accept all friend requests
  await core.apis.FriendApi.handleFriendRequest(req, true);
}

clearBuddyReqUnreadCnt

Clear unread count for friend requests.

async clearBuddyReqUnreadCnt()

Example:

await core.apis.FriendApi.clearBuddyReqUnreadCnt();

Doubt Friend Requests

“Doubt” friend requests are requests that need additional verification.

getDoubtFriendRequest

Get list of doubt friend requests.

async getDoubtFriendRequest(count: number): Promise<Array<{
  flag: string;
  uin: number;
  nick: string;
  source: string;
  reason: string;
  msg: string;
  group_code: string;
  time: string;
  type: 'doubt';
}>>

count · number · required

Number of requests to retrieve

return · Array<DoubtRequest>

Array of doubt friend request objects

Example:

const doubtRequests = await core.apis.FriendApi.getDoubtFriendRequest(20);
doubtRequests.forEach(req => {
  console.log(`Doubt request from: ${req.nick}`);
  console.log(`Source: ${req.source}`);
  console.log(`Reason: ${req.reason}`);
});

handleDoubtFriendRequest

Handle a doubt friend request.

async handleDoubtFriendRequest(
  friendUid: string,
  str1: string = '',
  str2: string = ''
)

friendUid · string · required

Friend UID from doubt request

str1 · string · default: "''"

Additional parameter 1

str2 · string · default: "''"

Additional parameter 2

Example:

const doubtRequests = await core.apis.FriendApi.getDoubtFriendRequest(10);

for (const req of doubtRequests) {
  // Approve doubt request
  await core.apis.FriendApi.handleDoubtFriendRequest(req.flag);
}

Complete Example

Here’s a complete example of handling friend requests:

import { NapCatCore } from '@/napcat-core';

async function manageFriendRequests(core: NapCatCore) {
  // Get normal friend requests
  const requests = await core.apis.FriendApi.getBuddyReq();
  
  console.log(`${requests.length} friend requests pending`);
  
  for (const req of requests) {
    console.log(`\nRequest from: ${req.friendNick}`);
    console.log(`UID: ${req.friendUid}`);
    console.log(`Message: ${req.extWords}`);
    
    // Auto-accept if message contains "bot"
    if (req.extWords.toLowerCase().includes('bot')) {
      await core.apis.FriendApi.handleFriendRequest(req, true);
      console.log('✓ Accepted');
    } else {
      console.log('⊘ Skipped');
    }
  }
  
  // Get doubt requests
  const doubtRequests = await core.apis.FriendApi.getDoubtFriendRequest(20);
  
  console.log(`\n${doubtRequests.length} doubt requests pending`);
  
  for (const req of doubtRequests) {
    console.log(`\nDoubt request from: ${req.nick}`);
    console.log(`Source: ${req.source}`);
    console.log(`Group: ${req.group_code}`);
    
    // Handle doubt request
    await core.apis.FriendApi.handleDoubtFriendRequest(req.flag);
    console.log('✓ Processed');
  }
  
  // Clear unread count
  await core.apis.FriendApi.clearBuddyReqUnreadCnt();
}

// Usage
manageFriendRequests(core).catch(console.error);

Notes

• Friend operations may require appropriate permissions
• UIDs and UINs are different identifiers - use conversion methods from UserApi if needed
• Friend requests have expiration times and may become invalid
• Some operations may have rate limits imposed by QQ servers