Skip to main content

​
Overview

The Online File API (NTQQOnlineApi) provides methods for sending and receiving online files and folders. Unlike flash transfers, online files are delivered directly through QQ’s messaging system.
Online files are sent as special message types and can be received, refused, or canceled by recipients.

​
API Reference

​
sendOnlineFile

Send an online file to a user or group.
​
peer
Peer
required
Target peer (user or group)
{
  chatType: ChatType.Private | ChatType.Group,
  peerUid: string
}
​
filePath
string
required
Local path to the file
​
fileName
string
required
Display name for the file
​
result
object
Upload result
Example: 
import { ChatType } from 'napcat-core';

const result = await core.apis.OnlineApi.sendOnlineFile(
  { chatType: ChatType.Private, peerUid: 'u_123456' },
  '/path/to/document.pdf',
  'Important Document.pdf'
);

console.log('File sent, message ID:', result.msgId);

​
sendOnlineFolder

Send an entire folder as an online transfer.
​
peer
Peer
required
Target peer
​
folderPath
string
required
Local path to the folder
​
folderName
string
required
Display name for the folder
​
result
object
Upload result with message and element IDs
Example: 
const result = await core.apis.OnlineApi.sendOnlineFolder(
  { chatType: ChatType.Group, peerUid: 'g_123456' },
  '/path/to/project',
  'Project Files'
);

console.log('Folder sent');

​
getOnlineFileMsg

Retrieve online file messages for a peer.
​
peer
Peer
required
Target peer
​
messages
array
Array of online file messages
Example: 
const messages = await core.apis.OnlineApi.getOnlineFileMsg(
  { chatType: ChatType.Private, peerUid: 'u_123456' }
);

messages.forEach(msg => {
  console.log(`${msg.fileName}: ${msg.status}`);
});

​
cancelMyOnlineFileMsg

Cancel a sent online file transfer.
​
peer
Peer
required
Target peer
​
msgId
string
required
Message identifier
Example: 
await core.apis.OnlineApi.cancelMyOnlineFileMsg(
  { chatType: ChatType.Private, peerUid: 'u_123456' },
  'msg_abc123'
);

console.log('File transfer canceled');

​
refuseOnlineFileMsg

Refuse an incoming online file transfer.
​
peer
Peer
required
Source peer
​
msgId
string
required
Message identifier
​
elementId
string
required
File element identifier
Example: 
await core.apis.OnlineApi.refuseOnlineFileMsg(
  { chatType: ChatType.Private, peerUid: 'u_123456' },
  'msg_abc123',
  'elem_xyz789'
);

console.log('File transfer refused');

​
receiveOnlineFileOrFolder

Accept and receive an online file or folder.
​
peer
Peer
required
Source peer
​
msgId
string
required
Message identifier
​
elementId
string
required
File element identifier
​
downloadPath
string
Local path where file was saved
Example: 
const downloadPath = await core.apis.OnlineApi.receiveOnlineFileOrFolder(
  { chatType: ChatType.Private, peerUid: 'u_123456' },
  'msg_abc123',
  'elem_xyz789'
);

console.log('File saved to:', downloadPath);

​
switchFileToOffline

Switch an online file to offline mode (group files).
​
peer
Peer
required
Group peer
​
msgId
string
required
Message identifier
Example: 
await core.apis.OnlineApi.switchFileToOffline(
  { chatType: ChatType.Group, peerUid: 'g_123456' },
  'msg_abc123'
);

console.log('File switched to offline mode');

​
Complete Example

import { NapCatCore, ChatType, Peer } from 'napcat-core';

class OnlineFileManager {
  constructor(private core: NapCatCore) {}
  
  // Send file with progress tracking
  async sendFileWithProgress(peer: Peer, filePath: string, fileName: string) {
    console.log(`Sending ${fileName}...`);
    
    const result = await this.core.apis.OnlineApi.sendOnlineFile(
      peer,
      filePath,
      fileName
    );
    
    console.log('File sent successfully');
    return result;
  }
  
  // Auto-accept files from specific users
  async autoAcceptFiles(trustedUids: string[]) {
    for (const uid of trustedUids) {
      const peer = { chatType: ChatType.Private, peerUid: uid };
      const messages = await this.core.apis.OnlineApi.getOnlineFileMsg(peer);
      
      for (const msg of messages) {
        if (msg.status === 'pending') {
          console.log(`Auto-accepting ${msg.fileName} from ${uid}`);
          
          const downloadPath = await this.core.apis.OnlineApi.receiveOnlineFileOrFolder(
            peer,
            msg.msgId,
            msg.elementId
          );
          
          console.log(`Saved to: ${downloadPath}`);
        }
      }
    }
  }
  
  // Monitor pending transfers
  async listPendingTransfers(peer: Peer) {
    const messages = await this.core.apis.OnlineApi.getOnlineFileMsg(peer);
    
    const pending = messages.filter(m => m.status === 'pending');
    
    console.log(`\nPending transfers: ${pending.length}`);
    pending.forEach(msg => {
      const sizeMB = (msg.fileSize / 1024 / 1024).toFixed(2);
      console.log(`  - ${msg.fileName} (${sizeMB} MB)`);
    });
    
    return pending;
  }
  
  // Bulk file operations
  async sendMultipleFiles(peer: Peer, files: Array<{path: string, name: string}>) {
    const results = [];
    
    for (const file of files) {
      const result = await this.sendFileWithProgress(peer, file.path, file.name);
      results.push(result);
      
      // Small delay between sends
      await new Promise(resolve => setTimeout(resolve, 1000));
    }
    
    console.log(`Sent ${results.length} files`);
    return results;
  }
}

// Usage
const fileManager = new OnlineFileManager(core);

// Send a file
await fileManager.sendFileWithProgress(
  { chatType: ChatType.Private, peerUid: 'u_123456' },
  '/documents/report.pdf',
  'Monthly Report.pdf'
);

// Auto-accept from trusted users
await fileManager.autoAcceptFiles(['u_123456', 'u_789012']);

// Send multiple files
await fileManager.sendMultipleFiles(
  { chatType: ChatType.Group, peerUid: 'g_123456' },
  [
    { path: '/files/doc1.pdf', name: 'Document 1.pdf' },
    { path: '/files/doc2.pdf', name: 'Document 2.pdf' },
    { path: '/files/doc3.pdf', name: 'Document 3.pdf' }
  ]
);

​
Use Cases

​
Direct File Sharing

Send files directly to users without using group storage: 
// Send confidential document
await core.apis.OnlineApi.sendOnlineFile(
  { chatType: ChatType.Private, peerUid: 'u_client' },
  '/contracts/nda.pdf',
  'NDA - Confidential.pdf'
);

​
Automated File Distribution

Automatically distribute files to team members: 
const teamMembers = ['u_123', 'u_456', 'u_789'];
const reportPath = '/reports/weekly-report.pdf';

for (const member of teamMembers) {
  await core.apis.OnlineApi.sendOnlineFile(
    { chatType: ChatType.Private, peerUid: member },
    reportPath,
    'Weekly Report.pdf'
  );
}

​
File Reception Management

Manage incoming file transfers: 
// Check pending files
const peer = { chatType: ChatType.Private, peerUid: 'u_sender' };
const messages = await core.apis.OnlineApi.getOnlineFileMsg(peer);

for (const msg of messages) {
  if (msg.status === 'pending') {
    // Check file size before accepting
    const sizeMB = msg.fileSize / 1024 / 1024;
    
    if (sizeMB < 100) {
      // Accept small files
      await core.apis.OnlineApi.receiveOnlineFileOrFolder(
        peer, msg.msgId, msg.elementId
      );
    } else {
      // Refuse large files
      await core.apis.OnlineApi.refuseOnlineFileMsg(
        peer, msg.msgId, msg.elementId
      );
    }
  }
}

File API

General file operations

Flash Transfer API

Temporary flash transfers

Group API

Group file management

Build docs developers (and LLMs) love

Get started for freeTalk to us