role_create

Create a role that you can then give to members. The new role goes to the bottom of the role order.

Request

{
  "cmd": "role_create",
  "name": "photography",
  "description": "Share your shots",
  "color": "#a78bfa",
  "icon": "https://example.com/roles/camera.png",
  "self_assignable": true,
  "category": "Hobbies"
}

Field	Type	Required	Description
`name`	string	Yes	Role name, 1 to 64 characters. Must not match an existing role. Members and channel rules refer to roles by this name.
`description`	string	No	Text shown with the role. Defaults to `""`.
`color`	string	No	Display color, such as `#a78bfa`. Defaults to `""`.
`icon`	string	No	Absolute `http` or `https` URL of an image for the role. Surrounding spaces are trimmed. Defaults to `""`.
`gradient`	array	No	Gradient colors for usernames. Defaults to `[]`.
`permissions`	string[]	No	Administrative permissions the role grants, such as `manage_users`. You can only include permissions you hold. Defaults to `[]`.
`hoisted`	boolean	No	When `true`, clients list members with this role in their own group. Defaults to `false`.
`self_assignable`	boolean	No	When `true`, members can add the role to themselves with `self_role_add`. Defaults to `false`.
`category`	string	No	Label clients use to group roles. Defaults to `""`.
`price`	number	No	Price members pay through Rotur to self-assign the role, from 0 to 1,000,000. `0` means free. Defaults to `0`. See `self_role_add`.

Response

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

val is the new role object. The server generates id and sets position to the number of roles that existed before, which places the role last. Use role_reorder to move it.

Every other authenticated connection receives the same role_create frame. The change is recorded in the audit log.

Permissions

Requires manage_roles. It is blocked while you are timed out.

Every entry in permissions must be a permission you hold. The owner and members with administrator hold them all.

Errors

`val`	When
`Role already exists`	A role with this `name` exists.
`Role icon must be an absolute HTTP or HTTPS URL`	`icon` is blank, relative, uses another scheme, or contains spaces.
`Cannot assign permission '<permission>' — you don't have this permission`	`permissions` includes one you don’t hold.
`Failed to create role`	The server could not save the role.
Validation message	`name` is missing or too long, a field has the wrong type, or `price` is out of range.

See also