User API

NTQQUserApi methods for user information and profile management

Overview

The NTQQUserApi class provides methods for retrieving user information, managing profiles, handling conversions between UID/UIN, and accessing user-related services.

User Information

getUserDetailInfo

Get detailed information about a user.

async getUserDetailInfo(
  uid: string,
  no_cache: boolean = false
): Promise<User>

uid · string · required

User UID

no_cache · boolean · default: "false"

Whether to fetch from server instead of cache

return · User

User object with detailed information

Example:

const user = await core.apis.UserApi.getUserDetailInfo('u_abc123');
console.log('Nickname:', user.nick);
console.log('QQ Level:', user.qqLevel);
console.log('Age:', user.age);

fetchUserDetailInfo

Fetch user detail from specific source.

async fetchUserDetailInfo(
  uid: string,
  mode: UserDetailSource = UserDetailSource.KDB
)

uid · string · required

User UID

mode · UserDetailSource · default: "UserDetailSource.KDB"

Data source: KDB (cache) or KSERVER (server)

return · UserDetailInfo

Detailed user profile information

getCoreAndBaseInfo

Get core and basic information for multiple users.

async getCoreAndBaseInfo(
  uids: string[]
): Promise<Map<string, UserInfo>>

uids · string[] · required

Array of user UIDs

return · Map<string, UserInfo>

Map of UID to user information

Example:

const users = await core.apis.UserApi.getCoreAndBaseInfo([
  'u_user1',
  'u_user2',
  'u_user3'
]);

users.forEach((info, uid) => {
  console.log(`${uid}: ${info.nick}`);
});

UID/UIN Conversion

getUidByUinV2

Convert UIN to UID.

async getUidByUinV2(uin: string): Promise<string>

uin · string · required

User UIN (QQ number)

return · string

User UID, or empty string if not found

Example:

const uid = await core.apis.UserApi.getUidByUinV2('123456789');
if (uid) {
  console.log('UID:', uid);
}

getUinByUidV2

Convert UID to UIN.

async getUinByUidV2(uid: string): Promise<string>

uid · string · required

User UID

return · string

User UIN (QQ number), or ‘0’ if not found

Example:

const uin = await core.apis.UserApi.getUinByUidV2('u_abc123');
if (uin !== '0') {
  console.log('QQ:', uin);
}

Profile Management

modifySelfProfile

Modify bot’s own profile.

async modifySelfProfile(param: ModifyProfileParams)

param · ModifyProfileParams · required

Object containing profile fields to modify

Example:

await core.apis.UserApi.modifySelfProfile({
  nick: 'My Bot',
  longNick: 'This is my bot description',
  // ... other profile fields
});

setLongNick

Set bot’s signature/personal description.

async setLongNick(longNick: string)

longNick · string · required

Signature text

Example:

await core.apis.UserApi.setLongNick('I am a helpful QQ bot!');

setQQAvatar

Set bot’s QQ avatar.

async setQQAvatar(
  filePath: string
): Promise<{ result: number, errMsg: string }>

filePath · string · required

Path to image file

return · { result: number, errMsg: string }

Result code and error message

Example:

const result = await core.apis.UserApi.setQQAvatar('/path/to/avatar.png');
if (result.result === 0) {
  console.log('Avatar updated successfully');
} else {
  console.error('Failed:', result.errMsg);
}

Online Status

setSelfOnlineStatus

Set bot’s online status.

async setSelfOnlineStatus(
  status: number,
  extStatus: number,
  batteryStatus: number
)

status · number · required

Status code (online, away, busy, etc.)

extStatus · number · required

Extended status code

batteryStatus · number · required

Battery status

Example:

// Set to online
await core.apis.UserApi.setSelfOnlineStatus(1, 0, 0);

setDiySelfOnlineStatus

Set custom online status with emoji and text.

async setDiySelfOnlineStatus(
  faceId: string,
  wording: string,
  faceType: string
)

faceId · string · required

Emoji/face ID

wording · string · required

Status text

faceType · string · required

Face type identifier

Example:

await core.apis.UserApi.setDiySelfOnlineStatus(
  '123',
  'Working on something awesome',
  '1'
);

Profile Likes

like

Send like(s) to a user’s profile.

async like(
  uid: string,
  count: number = 1
): Promise<{ result: number, errMsg: string, succCounts: number }>

uid · string · required

Target user UID

count · number · default: "1"

Number of likes to send (1-20)

return · { result: number, errMsg: string, succCounts: number }

Result with success count

Example:

const result = await core.apis.UserApi.like('u_abc123', 10);
console.log(`Sent ${result.succCounts} likes`);

getProfileLike

Get profile like information.

async getProfileLike(
  uid: string,
  start: number,
  count: number,
  type: number = 2
)

uid · string · required

User UID

start · number · required

Starting index

count · number · required

Number of records to fetch

type · number · default: "2"

Type: 2 for self, 1 for others

Cookies & Authentication

getCookies

Get cookies for a specific domain.

async getCookies(domain: string): Promise<{ [key: string]: string }>

domain · string · required

Domain name (e.g., ‘qun.qq.com’)

return · { [key: string]: string }

Object containing cookies

Example:

const cookies = await core.apis.UserApi.getCookies('qun.qq.com');
console.log('p_skey:', cookies.p_skey);

getPSkey

Get PSkey for domains.

async getPSkey(domainList: string[])

domainList · string[] · required

Array of domain names

return · { domainPskeyMap: Map<string, string> }

Map of domain to PSkey

Example:

const result = await core.apis.UserApi.getPSkey(['qun.qq.com', 'ti.qq.com']);
const pskey = result.domainPskeyMap.get('qun.qq.com');

getSKey

Get SKey for authentication.

async getSKey(): Promise<string | undefined>

return · string | undefined

SKey string if successful

getQzoneCookies

Get cookies specifically for Qzone.

async getQzoneCookies(): Promise<{ [key: string]: string }>

return · { [key: string]: string }

Qzone cookies

forceFetchClientKey

Force fetch client key.

async forceFetchClientKey()

return · { result: number, clientKey: string, keyIndex: string }

Client key information

Recent Contacts

getRecentContactList

Get list of recent contacts.

async getRecentContactList()

return · RecentContact[]

Array of recent contact objects

getRecentContactListSnapShot

Get snapshot of recent contacts.

async getRecentContactListSnapShot(count: number)

count · number · required

Number of contacts to retrieve

getRecentContactListSync

Get synced recent contact list.

async getRecentContactListSync()

getRecentContactListSyncLimit

Get synced recent contacts with limit.

async getRecentContactListSyncLimit(count: number)

count · number · required

Maximum number of contacts

Utility Methods

getUserDetailInfoByUin

Get user detail by UIN directly.

async getUserDetailInfoByUin(Uin: string)

Uin · string · required

User UIN (QQ number)

getBuddyRecommendContactArkJson

Get friend recommendation card in Ark JSON format.

async getBuddyRecommendContactArkJson(
  uin: string,
  sencenID: string = ''
)

uin · string · required

User UIN

sencenID · string · default: "''"

Scene ID

getRobotUinRange

Get robot UIN range information.

async getRobotUinRange(): Promise<Array<unknown>>

return · Array<unknown>

Array of robot UIN range data

Complete Example

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

async function manageUserProfile(core: NapCatCore) {
  // Get user info by UID
  const user = await core.apis.UserApi.getUserDetailInfo('u_abc123', true);
  console.log(`User: ${user.nick}`);
  console.log(`Level: ${user.qqLevel}`);
  
  // Convert between UID and UIN
  const uin = await core.apis.UserApi.getUinByUidV2('u_abc123');
  const uid = await core.apis.UserApi.getUidByUinV2('123456789');
  
  // Update bot profile
  await core.apis.UserApi.setLongNick('I am a helpful bot!');
  await core.apis.UserApi.setQQAvatar('/path/to/avatar.png');
  
  // Set online status
  await core.apis.UserApi.setSelfOnlineStatus(1, 0, 0);
  
  // Send likes to user
  await core.apis.UserApi.like('u_abc123', 10);
  
  // Get recent contacts
  const recent = await core.apis.UserApi.getRecentContactList();
  console.log(`${recent.length} recent contacts`);
}