Extended Actions

NapCat-specific extensions and advanced features

Overview

NapCat provides extended actions beyond the standard OneBot 11 protocol. These actions enable advanced features specific to NapCat and the NTQQ platform.

Image & Media

ocr_image

Perform OCR (text recognition) on an image.

This action is only supported on Windows platform.

Request

image · string · required

Image path, URL, or Base64-encoded image data

Response

texts · array

Array of recognized text objects with position and content

language · string

Detected language

Example

// Request
{
  "image": "https://example.com/image.png"
}

// Response
{
  "status": "ok",
  "retcode": 0,
  "data": {
    "texts": [
      {
        "text": "Hello World",
        "confidence": 0.95,
        "coordinates": [[10, 20], [100, 20], [100, 40], [10, 40]]
      }
    ],
    "language": "en"
  }
}

fetch_custom_face

Fetch custom emoji/sticker from user’s collection.

Request

count · number · default: "48"

Number of custom faces to fetch

fetch_emoji_like

Fetch emoji reactions available for messages.

Request

emojiId · string · required

Emoji ID

emojiType · string · required

Emoji type

message_id · string · required

Message ID

count · number · default: "20"

Number of reactions to fetch

get_emoji_likes

Get list of users who reacted with emoji to a message.

Status & Profile

set_online_status

Set the bot’s online status.

Request

status · number | string · required

Status code (see status list below)

ext_status · number | string · required

Extended status code

battery_status · number | string · required

Battery status (0-100)

Status Codes

Basic Status:

• 10 - Online
• 30 - Away
• 40 - Invisible
• 50 - Busy
• 60 - Q Me
• 70 - Do Not Disturb

Extended Status (ext_status):

• 1028 - Listening to Music
• 1018 - Studying
• 1016 - Sleeping
• 1027 - Gaming (TIMI)
• 1300 - Slacking Off
• 1032 - Staying Up Late
• 1401 - Emo
• And many more…

Example

// Request - Set to "Busy"
{
  "status": 50,
  "ext_status": 0,
  "battery_status": 100
}

// Request - Set to "Listening to Music"
{
  "status": 10,
  "ext_status": 1028,
  "battery_status": 85
}

// Response
{
  "status": "ok",
  "retcode": 0,
  "data": null
}

set_diy_online_status

Set a custom DIY online status.

Request

status · string · required

Custom status text

set_qq_avatar

Set the bot’s QQ avatar/profile picture.

Request

file · string · required

Image path, URL, or Base64 data

set_qq_profile

Update QQ profile information.

Request

nickname · string

Nickname

personal_note · string

Personal signature

sex · number

Gender: 0 (unknown), 1 (male), 2 (female)

set_long_nick

Set extended nickname/signature.

Request

longNick · string · required

Extended nickname text

get_profile_like

Get list of users who liked the bot’s profile.

get_user_status

Get a user’s current online status.

Request

user_id · string · required

User QQ number

Group Extensions

get_group_info_ex

Get extended group information (more details than standard get_group_info).

Request

group_id · string · required

Group number

get_group_add_request

Get pending group join requests.

Request

group_id · string · required

Group number

set_group_remark

Set remark/note for a group.

Request

group_id · string · required

Group number

remark · string · required

Group remark text

set_group_add_option

Set group join approval options.

Request

group_id · string · required

Group number

option · number · required

Join option: 0 (anyone), 1 (approval required), 2 (reject all)

set_group_search

Set whether group can be found in search.

Request

group_id · string · required

Group number

enable · boolean · required

Enable or disable group search

set_group_robot_add_option

Set robot/bot join approval options for group.

set_group_kick_members

Kick multiple members from group at once.

Request

group_id · string · required

Group number

user_ids · array · required

Array of user QQ numbers to kick

reject_add_request · boolean · default: "false"

Reject future join requests

set_special_title

Set a member’s special title in group.

Request

group_id · string · required

Group number

user_id · string · required

Member QQ number

special_title · string · required

Special title text (empty to remove)

duration · number · default: "-1"

Title duration in seconds (-1 for permanent)

set_group_sign

Perform group check-in/sign.

Request

group_id · string · required

Group number

set_input_status

Set typing status in a conversation.

Request

user_id · string

User QQ number (for private chat)

group_id · string

Group number (for group chat)

status · number · required

Input status: 1 (typing), 0 (not typing)

Group Album

get_qun_album_list

Get list of group photo albums.

Request

group_id · string · required

Group number

get_group_album_media_list

Get media list from a group album.

Request

group_id · string · required

Group number

album_id · string · required

Album ID

upload_image_to_qun_album

Upload image to group album.

Request

group_id · string · required

Group number

album_id · string · required

Album ID

image · string · required

Image path or URL

do_group_album_comment

Comment on a group album photo.

Request

group_id · string · required

Group number

album_id · string · required

Album ID

photo_id · string · required

Photo ID

comment · string · required

Comment text

set_group_album_media_like

Like a group album photo.

del_group_album_media

Delete media from group album.

Advanced Features

get_rkey

Get Rkey for advanced operations.

get_clientkey

Get client key for authentication.

get_credentials

Get credentials (cookies, csrf token, etc.).

Response

cookies · string

Cookie string

csrf_token · string

CSRF token

get_ai_characters

Get available AI character list.

Request

chat_type · number · required

Chat type: 1 (private), 2 (group)

get_mini_app_ark

Get mini app ARK message data.

Request

app_id · string · required

Mini app ID

share_contact

Share contact card.

Request

group_id · string

Target group number

user_id · string

Target user QQ number

phone_number · string

Phone number to share

translate_en_word_to_zn

Translate English word to Chinese.

Request

word · string · required

English word to translate

create_collection

Add message to favorites/collection.

Request

message_id · string · required

Message ID to collect

get_collection_list

Get list of collected/favorited messages.

Request

category · number · default: "0"

Collection category

count · number · default: "50"

Number of items to retrieve

get_robot_uin_range

Get robot/bot QQ number range information.

send_packet

Send raw protocol packet (advanced).

Request

cmd · string · required

Command name

data · string · required

Packet data (hex string)

bot_exit

Gracefully exit/shutdown the bot.

Request

No parameters required.

click_inline_keyboard_button

Click an inline keyboard button in a bot message.

Request

message_id · string · required

Message ID containing the keyboard

button_id · string · required

Button ID to click

data · string · required

Button callback data

System Actions

get_version_info

Get NapCat version information.

get_status

Get bot online status and statistics.

get_csrf_token

Get CSRF token for web operations.

can_send_image

Check if bot can send images.

can_send_record

Check if bot can send voice records.

set_restart

Restart the bot.

Request

delay · number · default: "0"

Restart delay in milliseconds

clean_cache

Clear bot’s cache.

Poke Actions

send_poke

Send a poke/nudge to user or group.

Request

user_id · string

User QQ number (for private poke)

group_id · string

Group number (for group poke)

friend_poke

Poke a friend.

Request

user_id · string · required

Friend QQ number

group_poke

Poke in a group.

Request

group_id · string · required

Group number

user_id · string · required

Target member QQ number

Extended actions are specific to NapCat and may not be available in other OneBot implementations. Always check the action availability before using in production.