Collection API

NTQQCollectionApi for managing QQ collections

Overview

The Collection API (NTQQCollectionApi) provides methods for creating and managing QQ collections. Collections allow users to save messages, images, and other content for later reference.

This API requires Node.js 18.0.0 or higher.

API Reference

createCollection

Create a new collection with specified content.

authorUin · string · required

Author’s UIN (QQ number)

authorUid · string · required

Author’s UID (unique identifier)

authorName · string · required

Author’s display name

brief · string · required

Brief description of the collection

rawData · string · required

Raw data/content to be collected (JSON string)

result · object

Result of collection creation

Show properties

collectionId · string

Unique identifier for the created collection

createTime · number

Creation timestamp

Example:

const result = await core.apis.CollectionApi.createCollection(
  '123456789',  // authorUin
  'u_abc123',   // authorUid
  'Alice',      // authorName
  'Important conversation',  // brief
  JSON.stringify({
    type: 'message',
    content: 'This is the saved message content'
  })  // rawData
);

console.log('Collection created:', result.collectionId);

getAllCollection

Retrieve all collections for the current user.

category · number · required

Collection category filter

• 0 - All categories
• 1 - Messages
• 2 - Images
• 3 - Videos

count · number · required

Maximum number of collections to retrieve

collections · array

Array of collection objects

Show Collection Object

collectionId · string

Unique identifier for the collection

authorUin · string

Author’s UIN

authorName · string

Author’s display name

brief · string

Brief description

createTime · number

Creation timestamp

rawData · string

Raw collection data (JSON string)

Example:

// Get all message collections (up to 100)
const collections = await core.apis.CollectionApi.getAllCollection(1, 100);

collections.forEach(collection => {
  console.log(`Collection: ${collection.brief}`);
  console.log(`Created: ${new Date(collection.createTime).toLocaleString()}`);
  console.log(`Data: ${collection.rawData}`);
});

Use Cases

Save Important Messages

Collections are useful for saving important messages that you want to reference later:

// Save a message to collections
async function saveMessage(msg: RawMessage) {
  const content = {
    type: 'message',
    text: msg.elements.find(e => e.textElement)?.textElement?.content || '',
    sender: msg.senderUin,
    time: msg.msgTime
  };
  
  await core.apis.CollectionApi.createCollection(
    msg.senderUin,
    msg.senderUid,
    msg.sendNickName,
    'Saved message',
    JSON.stringify(content)
  );
}

Organize Saved Content

Retrieve and organize saved collections by category:

// Get all saved messages
const messageCollections = await core.apis.CollectionApi.getAllCollection(1, 50);

// Filter by date
const recentCollections = messageCollections.filter(c => {
  const daysSinceCreation = (Date.now() - c.createTime) / (1000 * 60 * 60 * 24);
  return daysSinceCreation <= 7; // Last 7 days
});

console.log(`You have ${recentCollections.length} collections from the last week`);

Complete Example

import { NapCatCore } from 'napcat-core';

class CollectionManager {
  constructor(private core: NapCatCore) {}
  
  // Save a message to collections
  async saveMessage(message: RawMessage) {
    const content = {
      type: 'message',
      text: this.extractTextContent(message),
      sender: message.senderUin,
      senderName: message.sendNickName,
      timestamp: message.msgTime
    };
    
    return await this.core.apis.CollectionApi.createCollection(
      message.senderUin,
      message.senderUid,
      message.sendNickName,
      `Message from ${message.sendNickName}`,
      JSON.stringify(content)
    );
  }
  
  // Get all saved messages
  async getSavedMessages(limit: number = 100) {
    const collections = await this.core.apis.CollectionApi.getAllCollection(1, limit);
    
    return collections.map(c => {
      const data = JSON.parse(c.rawData);
      return {
        id: c.collectionId,
        text: data.text,
        sender: data.senderName,
        savedAt: new Date(c.createTime)
      };
    });
  }
  
  private extractTextContent(msg: RawMessage): string {
    return msg.elements
      .filter(e => e.textElement)
      .map(e => e.textElement!.content)
      .join('');
  }
}

Related APIs

Message API

Send and receive messages

System API

System utilities and operations