File Actions

OneBot 11 file upload and download actions

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://...