Group Actions

OneBot 11 group management actions

get_group_info

Get group information.

Request

group_id · string · required

Group number

Response

group_id · number

Group number

group_name · string

Group name

group_remark · string

Group remark (note)

group_all_shut · number

All members muted: -1 if enabled, 0 if disabled

member_count · number

Current member count

max_member_count · number

Maximum member capacity

Example

// Request
{
  "group_id": "123456"
}

// Response
{
  "status": "ok",
  "retcode": 0,
  "data": {
    "group_id": 123456,
    "group_name": "Example Group",
    "group_remark": "My Group",
    "group_all_shut": 0,
    "member_count": 50,
    "max_member_count": 200
  }
}

get_group_list

Get the list of groups the bot has joined.

Request

No parameters required.

Response

data · array

Array of group objects

Each group object contains:

• group_id (number): Group number
• group_name (string): Group name
• group_remark (string): Group remark
• group_all_shut (number): Mute status
• member_count (number): Member count
• max_member_count (number): Max capacity

Example

// Response
{
  "status": "ok",
  "retcode": 0,
  "data": [
    {
      "group_id": 123456,
      "group_name": "Group 1",
      "group_remark": "My Group 1",
      "group_all_shut": 0,
      "member_count": 50,
      "max_member_count": 200
    },
    {
      "group_id": 789012,
      "group_name": "Group 2",
      "group_remark": "My Group 2",
      "group_all_shut": -1,
      "member_count": 100,
      "max_member_count": 500
    }
  ]
}

get_group_member_info

Get information about a group member.

Request

group_id · string · required

Group number

user_id · string · required

Member QQ number

no_cache · boolean | string · default: "false"

Bypass cache and fetch fresh data

Response

group_id · number

Group number

user_id · number

Member QQ number

nickname · string

Member nickname

card · string

Group card (display name in group)

sex · string

Gender: male, female, or unknown

age · number

Age

join_time · number

Join time (Unix timestamp)

last_sent_time · number

Last message time (Unix timestamp)

level · string

Group level

qq_level · number

QQ level

role · string

Role: owner, admin, or member

title · string

Special title

area · string

Location/area

unfriendly · boolean

Has bad record

title_expire_time · number

Special title expiration time

card_changeable · boolean

Can change group card

shut_up_timestamp · number

Mute expiration timestamp

is_robot · boolean

Is a robot/bot account

Example

// Request
{
  "group_id": "123456",
  "user_id": "987654"
}

// Response
{
  "status": "ok",
  "retcode": 0,
  "data": {
    "group_id": 123456,
    "user_id": 987654,
    "nickname": "User",
    "card": "Card Name",
    "sex": "male",
    "age": 20,
    "join_time": 1234567890,
    "last_sent_time": 1234567890,
    "level": "10",
    "qq_level": 64,
    "role": "member",
    "title": "Special Member",
    "shut_up_timestamp": 0,
    "card_changeable": true,
    "is_robot": false
  }
}

get_group_member_list

Get the list of members in a group.

Request

group_id · string · required

Group number

no_cache · boolean | string · default: "false"

Bypass cache and fetch fresh data

Response

data · array

Array of group member objects (same structure as get_group_member_info)

Example

// Request
{
  "group_id": "123456"
}

// Response
{
  "status": "ok",
  "retcode": 0,
  "data": [
    {
      "group_id": 123456,
      "user_id": 111111,
      "nickname": "Owner",
      "card": "Group Owner",
      "role": "owner"
    },
    {
      "group_id": 123456,
      "user_id": 222222,
      "nickname": "Admin",
      "card": "Administrator",
      "role": "admin"
    },
    {
      "group_id": 123456,
      "user_id": 333333,
      "nickname": "Member",
      "card": "Regular Member",
      "role": "member"
    }
  ]
}

set_group_kick

Kick a member from the group.

Request

group_id · string · required

Group number

user_id · string · required

Member QQ number to kick

reject_add_request · boolean | string · default: "false"

Reject future join requests from this user

Response

result · null

Returns null on success

Example

// Request
{
  "group_id": "123456",
  "user_id": "987654",
  "reject_add_request": true
}

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

set_group_ban

Mute a group member.

Request

group_id · string · required

Group number

user_id · string · required

Member QQ number to mute

duration · number | string · default: "1800"

Mute duration in seconds (0 to unmute, max 2592000 = 30 days)

Response

result · null

Returns null on success

Example

// Request - Mute for 1 hour
{
  "group_id": "123456",
  "user_id": "987654",
  "duration": 3600
}

// Request - Unmute
{
  "group_id": "123456",
  "user_id": "987654",
  "duration": 0
}

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

set_group_whole_ban

Enable or disable all members mute.

Request

group_id · string · required

Group number

enable · boolean | string · default: "true"

Enable (true) or disable (false) all members mute

Response

result · null

Returns null on success

Example

// Request - Enable
{
  "group_id": "123456",
  "enable": true
}

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

set_group_admin

Set or remove group admin.

Request

group_id · string · required

Group number

user_id · string · required

Member QQ number

enable · boolean | string · default: "true"

Promote (true) or demote (false) admin

Response

result · null

Returns null on success

Example

// Request - Promote to admin
{
  "group_id": "123456",
  "user_id": "987654",
  "enable": true
}

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

set_group_card

Set a member’s group card (display name).

Request

group_id · string · required

Group number

user_id · string · required

Member QQ number

card · string · default: ""

New group card (empty string to clear)

Response

result · null

Returns null on success

Example

// Request
{
  "group_id": "123456",
  "user_id": "987654",
  "card": "New Card Name"
}

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

set_group_name

Set the group name.

Request

group_id · string · required

Group number

group_name · string · required

New group name

Response

result · null

Returns null on success

Example

// Request
{
  "group_id": "123456",
  "group_name": "New Group Name"
}

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

set_group_leave

Leave a group.

Request

group_id · string · required

Group number to leave

is_dismiss · boolean | string · default: "false"

Dismiss the group (only works if bot is owner)

Response

result · null

Returns null on success

Example

// Request
{
  "group_id": "123456",
  "is_dismiss": false
}

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

set_group_add_request

Approve or reject a group join request.

Request

flag · string · required

Request flag from group request event

sub_type · string · required

Request type: add (join request) or invite (invitation)

approve · boolean | string · default: "true"

Approve (true) or reject (false)

reason · string · default: ""

Rejection reason (only used when rejecting)

Response

result · null

Returns null on success

Example

// Request - Approve
{
  "flag": "request_flag_12345",
  "sub_type": "add",
  "approve": true
}

// Request - Reject
{
  "flag": "request_flag_12345",
  "sub_type": "add",
  "approve": false,
  "reason": "Not accepting new members"
}

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

Additional Group Actions

get_group_essence

Get group essence messages (pinned messages).

set_essence_msg

Set a message as essence (pin it).

del_essence_msg

Remove a message from essence (unpin it).

get_group_notice

Get group announcements.

send_group_notice

Publish a group announcement.

get_group_honor_info

Get group honor information (active members, etc.).

get_group_shut_list

Get list of muted members in a group.