role_update

Edit an existing role. Send only the fields you want to change; everything else stays as it is.

Request

{
  "cmd": "role_update",
  "id": "b7e2d6a1-54c3-4f7a-8e0d-2c9f61a3e4b8",
  "color": "#8b5cf6",
  "description": null
}

Fields sit at the top level, next to cmd. There is no updates object.

Field	Type	Required	Description
id	string	See below	ID of the role to change.
name	string	See below	With id: the new name, 1 to 64 characters. Without id: the role to change, by name or ID.
description	string or null	No	Text shown with the role.
color	string or null	No	Display color, such as #8b5cf6.
icon	string or null	No	Absolute http or https URL of an image for the role. Surrounding spaces are trimmed.
gradient	array or null	No	Gradient colors for usernames.
permissions	string[]	No	Replaces the role’s permission list. You can only include permissions you hold.
hoisted	boolean	No	When true, clients list members with this role in their own group.
self_assignable	boolean	No	When true, members can add the role to themselves.
category	string or null	No	Label clients use to group roles.
price	number	No	Price members pay through Rotur to self-assign the role, from 0 to 1,000,000.

You must send id, name, or both. To rename a role, send its id and the new name. Sending null for a nullable field stores null, which clears it.

Caution

Members and channel permission rules refer to roles by name, and renaming doesn’t update them. After a rename, members who had the role no longer get its color or permissions, and channel rules that named it no longer match. Reassign the role with user_roles_set and update any channel rules.

Response

{
  "cmd": "role_update",
  "val": {
    "id": "b7e2d6a1-54c3-4f7a-8e0d-2c9f61a3e4b8",
    "name": "photography",
    "description": null,
    "color": "#8b5cf6",
    "icon": "https://example.com/roles/camera.png",
    "gradient": [],
    "hoisted": false,
    "permissions": [],
    "self_assignable": true,
    "category": "Hobbies",
    "price": 0,
    "position": 4
  }
}

val is the full role object after the change. Every other authenticated connection receives the same role_update frame. The change is recorded in the audit log.

Permissions

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

• The role isn’t owner, admin, or user.
• The role ranks below your highest role. A lower position is a higher rank.
• You hold every permission the role already has, unless you have administrator. Without administrator, you can’t edit a role that grants owner or administrator.
• You hold every permission in the new permissions list.

Errors

val	When
Role not found	No role matches id, or name when id is absent.
Role icon must be an absolute HTTP or HTTPS URL	icon is blank, relative, uses another scheme, or contains spaces.
Cannot manage protected role '<name>'	You aren’t the owner and 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 already grants a permission you don’t hold.
Role with new name already exists	Another role has the new name.
Role '<name>' cannot be made self-assignable	The owner set self_assignable: true on owner, admin, or user.
Cannot assign permission '<permission>' — you don't have this permission	The new permissions list includes one you don’t hold.
No valid updates provided	Nothing to change, for example only name was sent without id.
Failed to update role	The server could not save the change.
Validation message	Neither id nor name was sent, name is longer than 64 characters, a field has the wrong type, or price is out of range.

See also

• role_create
• role_reorder
• Roles and permissions