role_delete

Delete a role from the server. The built-in owner, admin, and user roles can’t be deleted.

Request

{
  "cmd": "role_delete",
  "id": "b7e2d6a1-54c3-4f7a-8e0d-2c9f61a3e4b8"
}

Field	Type	Required	Description
`id`	string	See below	ID or name of the role to delete.
`name`	string	See below	Name or ID of the role to delete. Used only when `id` is absent.

Send id, name, or both. If you send both, id wins.

Response

{
  "cmd": "role_delete",
  "val": {
    "id": "b7e2d6a1-54c3-4f7a-8e0d-2c9f61a3e4b8",
    "name": "photography",
    "description": "Share your shots",
    "color": "#a78bfa",
    "icon": "",
    "gradient": [],
    "hoisted": false,
    "permissions": [],
    "self_assignable": true,
    "category": "Hobbies",
    "price": 0,
    "position": 4
  }
}

val is the role as it was before deletion. Every other authenticated connection receives the same role_delete frame. The deletion is recorded in the audit log.

Members who had the role keep its name in their roles array. Clients should skip role names that aren’t in roles_list.
Other roles keep their position values, so the order may have a gap.

Permissions

Requires manage_roles. It is blocked while you are timed out. The server owner can delete any custom role. Everyone else must also pass these checks:

The role ranks below your highest role. A lower position is a higher rank.
You hold every permission the role grants, unless you have administrator. Without administrator, you can’t delete a role that grants owner or administrator.

Errors

`val`	When
`Role not found`	No role matches the `id` or `name` you sent.
`Cannot delete system roles`	The role is `owner`, `admin`, or `user`.
`Cannot manage roles at or above your position`	The role ranks at or above your highest role.
`Cannot assign '<permission>' — you don't have this permission yourself`	The role grants a permission you don’t hold.
`Failed to delete role`	The server could not save the change.
Validation message	Neither `id` nor `name` was sent, or one is not a string.

See also