Role schema

A role is a named group of members with shared permissions and display settings. roles_list returns every role, and the role_create, role_update, and role_delete events carry one in val.

{
  "id": "2b4d6f8a-0c1e-4a3b-8d5f-7a9c1e3b5d7f",
  "name": "artist",
  "description": "Shares artwork in #gallery",
  "color": "#E91E63",
  "icon": "https://cdn.example.com/roles/artist.png",
  "gradient": ["#E91E63", "#9C27B0"],
  "permissions": [],
  "hoisted": true,
  "self_assignable": true,
  "category": "Interests",
  "price": 0,
  "position": 4
}

interface Role {
  id: string;
  name: string;
  description: string;
  color: string | null;
  icon?: string;
  gradient: string[] | null;
  permissions: string[];
  hoisted: boolean;
  self_assignable: boolean;
  category: string | null;
  price?: number;
  position: number;
}

Field	Description
id	A UUID that stays the same when the role is renamed. Role mentions in messages use it.
name	The role’s name, up to 64 characters. Users’ roles lists and most role commands use names, so keep both.
description	Free text.
color	Display colour, such as #E91E63. Roles made with role_create store "" for no colour. Built-in roles use null.
icon	An absolute http or https image URL. "" when a created role has none. Built-in roles don’t have the field.
gradient	Colours for a gradient name style. Roles made with role_create store [] for none. Built-in roles use null.
permissions	Permission keys the role grants. See below.
hoisted	Whether members with this role are listed separately in the member list.
self_assignable	Whether members can give themselves this role with self_role_add.
category	Group name for role pickers. "" or null when there is none.
price	Cost to self-assign the role, from 0 to 1,000,000. 0 means free. Built-in roles don’t have the field. See self_role_add.
position	Rank order. Lower numbers rank higher: owner is 0.

roles_list returns an object keyed by role name, not an array. Sort by position to show roles in order.

Built-in roles

A new server starts with four roles:

Role	position	Default permissions
owner	0	owner, administrator
admin	1	administrator
moderator	2	manage_messages, manage_threads, kick_members, manage_nicknames, mute_members, deafen_members, move_members
user	3	create_invite

owner, admin, and user can’t be deleted or made self-assignable. New members get the server’s default roles, user unless the operator changed it.

Colours on users

A user’s color is the color of the first role in their roles list that has one set. Because created roles store "", a user’s colour can be an empty string.

Events that describe a user’s roles, such as user_roles_get, also carry gradient. The server walks the user’s roles in order and stops at the first one with a gradient array (even an empty one) or a non-null color. It returns that array, or else that colour string. When no role matches, gradient is null.

Permissions

permissions holds permission keys. The handshake lists the eleven administrative permissions that gate commands. Roles can also hold other keys that commands check, such as administrator, manage_threads, or manage_messages. Treat the list as open-ended, not a fixed enum.

administrator grants every permission. A member can only give a role permissions they hold themselves. Otherwise the request fails with Cannot assign permission '<name>' — you don't have this permission.

Paid roles

When a role has a price above 0, members without manage_roles must pay through Rotur to self-assign it, and server accounts can’t buy it. The server records each purchase on the account as a role ID in purchased_roles. That list is stored with the account but isn’t part of the public user object.

See also

• Roles and permissions: how roles and channel permissions work together.
• role_create: create a role.