Extended Actions

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

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

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.

Core APIs

OneBot Actions

Events

Network

​Overview

​Image & Media

​ocr_image

​Request

​Response

​Example

​fetch_custom_face

​Request

​fetch_emoji_like

​Request

​get_emoji_likes

​Status & Profile

​set_online_status

​Request

​Status Codes

​Example

​set_diy_online_status

​Request

​set_qq_avatar

​Request

​set_qq_profile

​Request

​set_long_nick

​Request

​get_profile_like

​get_user_status

​Request

​Group Extensions

​get_group_info_ex

​Request

​get_group_add_request

​Request

​set_group_remark

​Request

​set_group_add_option

​Request

​set_group_search

​Request

​set_group_robot_add_option

​set_group_kick_members

​Request

​set_special_title

​Request

​set_group_sign

​Request

​set_input_status

​Request

​Group Album

​get_qun_album_list

​Request

​get_group_album_media_list

​Request

​upload_image_to_qun_album

​Request

​do_group_album_comment

​Request

​set_group_album_media_like

​del_group_album_media

​Advanced Features

​get_rkey

​get_clientkey

​get_credentials

​Response

​get_ai_characters

​Request

​get_mini_app_ark

​Request

​share_contact

​Request

​translate_en_word_to_zn

​Request

​create_collection

​Request

​get_collection_list

​Request

​get_robot_uin_range

Overview

Image & Media

ocr_image

Request

Response

Example

fetch_custom_face

Request

fetch_emoji_like

Request

get_emoji_likes

Status & Profile

set_online_status

Request

Status Codes

Example

set_diy_online_status

Request

set_qq_avatar

Request

set_qq_profile

Request

set_long_nick

Request

get_profile_like

get_user_status

Request

Group Extensions

get_group_info_ex

Request

get_group_add_request

Request

set_group_remark

Request

set_group_add_option

Request

set_group_search

Request

set_group_robot_add_option

set_group_kick_members

Request

set_special_title

Request

set_group_sign

Request

set_input_status

Request

Group Album

get_qun_album_list

Request

get_group_album_media_list

Request

upload_image_to_qun_album

Request

do_group_album_comment

Request

set_group_album_media_like

del_group_album_media

Advanced Features

get_rkey

get_clientkey

get_credentials

Response

get_ai_characters

Request

get_mini_app_ark

Request

share_contact

Request

translate_en_word_to_zn

Request

create_collection

Request

get_collection_list

Request

get_robot_uin_range

send_packet

Request

bot_exit

Request