Skip to main content

​
upload_group_file

Upload a file to a group’s file system.

​
Request

​
group_id
string
required
Group number
​
file
string
required
File path, URL, or Base64-encoded data
​
name
string
required
File name to display
​
folder
string
Parent folder ID (uploads to root if not specified)
​
folder_id
string
Parent folder ID (alternative parameter for compatibility)
​
upload_file
boolean
default:"true"
Whether to execute the upload

​
Response

​
file_id
string | null
Uploaded file’s UUID (null if upload failed)

​
Example

// Request - Upload from local path
{
  "group_id": "123456",
  "file": "/path/to/file.pdf",
  "name": "Document.pdf",
  "folder": "/folder_id_123"
}

// Request - Upload from URL
{
  "group_id": "123456",
  "file": "https://example.com/file.zip",
  "name": "Archive.zip"
}

// Response
{
  "status": "ok",
  "retcode": 0,
  "data": {
    "file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

​
upload_private_file

Upload a file to a private chat.

​
Request

​
user_id
string
required
User QQ number
​
file
string
required
File path, URL, or Base64-encoded data
​
name
string
required
File name to display

​
Response

​
file_id
string | null
Uploaded file’s UUID

​
Example

// Request
{
  "user_id": "987654321",
  "file": "/path/to/image.png",
  "name": "Photo.png"
}

// Response
{
  "status": "ok",
  "retcode": 0,
  "data": {
    "file_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901"
  }
}

​
get_group_file_url

Get download URL for a group file.

​
Request

​
group_id
string
required
Group number
​
file_id
string
required
File UUID from upload or file list
​
busid
number
required
Business ID (usually 102 for group files)

​
Response

​
url
string
Download URL for the file

​
Example

// Request
{
  "group_id": "123456",
  "file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "busid": 102
}

// Response
{
  "status": "ok",
  "retcode": 0,
  "data": {
    "url": "https://download.example.com/file?..."
  }
}

​
get_private_file_url

Get download URL for a private file.

​
Request

​
user_id
string
required
User QQ number
​
file_id
string
required
File UUID

​
Response

​
url
string
Download URL for the file

​
Example

// Request
{
  "user_id": "987654321",
  "file_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901"
}

// Response
{
  "status": "ok",
  "retcode": 0,
  "data": {
    "url": "https://download.example.com/private/file?..."
  }
}

​
get_file

Get file information and download URL.

​
Request

​
file_id
string
required
File ID from message or file list

​
Response

​
file
string
Local file path or download URL
​
file_name
string
File name
​
file_size
number
File size in bytes
​
url
string
Download URL

​
Example

// Request
{
  "file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

// Response
{
  "status": "ok",
  "retcode": 0,
  "data": {
    "file": "/tmp/napcat/file.pdf",
    "file_name": "document.pdf",
    "file_size": 1048576,
    "url": "https://download.example.com/file?..."
  }
}

​
Group File System Management

​
get_group_root_files

Get files and folders in group’s root directory.
​
group_id
string
required
Group number

​
get_group_files_by_folder

Get files and folders in a specific folder.
​
group_id
string
required
Group number
​
folder_id
string
required
Folder ID

​
get_group_file_system_info

Get group file system information (used space, file count, etc.).
​
group_id
string
required
Group number

​
create_group_file_folder

Create a new folder in group file system.
​
group_id
string
required
Group number
​
name
string
required
Folder name
​
parent_id
string
Parent folder ID (root if not specified)

​
delete_group_file

Delete a file from group file system.
​
group_id
string
required
Group number
​
file_id
string
required
File UUID to delete
​
busid
number
required
Business ID (usually 102)

​
delete_group_folder

Delete a folder from group file system.
​
group_id
string
required
Group number
​
folder_id
string
required
Folder ID to delete

​
Media File Actions

​
get_image

Get image file information.
​
file
string
required
Image file name from message

​
get_record

Get voice/audio record file information.
​
file
string
required
Record file name from message
​
out_format
string
Output format (e.g., mp3, wav)

​
File Transfer Examples

​
Upload and Send File

// 1. Upload file to group
{
  "action": "upload_group_file",
  "params": {
    "group_id": "123456",
    "file": "https://example.com/document.pdf",
    "name": "Important Document.pdf"
  }
}

// 2. Send file as message (alternative)
{
  "action": "send_group_msg",
  "params": {
    "group_id": "123456",
    "message": [
      {
        "type": "file",
        "data": {
          "file": "https://example.com/document.pdf",
          "name": "Important Document.pdf"
        }
      }
    ]
  }
}

​
Download File from Message

// 1. Get file_id from received message event
// message contains: {"type": "file", "data": {"file_id": "..."}}

// 2. Get download URL
{
  "action": "get_file",
  "params": {
    "file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

// 3. Download from returned URL

​
NapCat Extended File Actions

​
move_group_file

Move a file to a different folder in group file system.

​
rename_group_file

Rename a file in group file system.

​
trans_group_file

Transfer group file to another location.
File paths can be specified as:
  • Local absolute path: /path/to/file
  • File URI: file:///path/to/file
  • HTTP/HTTPS URL: https://example.com/file
  • Base64 data: base64://...

Build docs developers (and LLMs) love

Get started for freeTalk to us