Members and roles

These functions work in commands, events and component handlers.

Most of them need no await. The bot adds it for you. The table shows the ones where you must write await yourself.

Write `await` yourself	No `await` needed
`get_or_fetch_member`, `getch_member`, `edit_member`	everything else on this page

The bot needs permission

Every action here needs the matching Discord permission, like Manage Roles or Ban Members. The bot's own role must also be above the roles and members it changes. Discord rule.

Limits#

Each run of a command or event can change a fixed number of roles. Pre-hook and post-hook share one count.

Function	Free	Premium
`add_roles`	5	15
`remove_roles`	5	15

get_member#

Finds a member by ID. Looks only in the bot's memory, so it is fast. Returns None when the member is not found.

python

get_member(member_id)

member_id must be a number. Text like "1234" does not work. Use int(...) first.

python

member = get_member(int(user_id_text))
if member is None:
    set_error("That member is not in the server.")

get_or_fetch_member#

Finds a member by ID. When the bot does not have them in memory, it asks Discord. Returns None when the member is not in the server.

python

await get_or_fetch_member(member_id)

getch_member is a short name for the same function.

python

member = await getch_member(1290000000000000000)

list_members#

Lists the members who have a role.

python

list_members(
    role,
    ignored_roles=None,
    as_mention=True,
    role_cond="any",
    ignore_cond="any",
)

Argument	What it does
`role`	A role, role ID or role name. A list of them also works.
`ignored_roles`	A list of role IDs. Members with these roles are left out.
`as_mention`	`True` gives mentions like `@Alex`. `False` gives member objects.
`role_cond`	`"any"`: has any of the roles. `"all"`: has all of them.
`ignore_cond`	`"any"` or `"all"`, the same way for `ignored_roles`.

python

staff = list_members("Staff")
set_content(f"Our staff: {', '.join(staff)}")

add_roles#

Gives one or more roles to a member.

python

add_roles(member, *roles, after=None)

Argument	What it does
`member`	The member.
`*roles`	Roles, role IDs or role names. Add as many as you like.
`after`	A time like `"10 minutes"` or `"2 days"`. The role is added after that time.

python

add_roles(user, "Verified", "Member")

Watch out

Do not use member.add_role(...). It is blocked. Always use add_roles.

remove_roles#

Takes one or more roles away from a member. Same arguments as add_roles.

python

remove_roles(member, *roles, after=None)

Example: a temporary role

python

add_roles(user, "Event Pass")
remove_roles(user, "Event Pass", after="24 hours")

A delayed change is saved, so it still happens after the bot restarts.

has_role#

Checks if a member has all the roles you list. Returns True or False.

python

has_role(member, *roles)

python

if has_role(user, "VIP"):
    set_content("Welcome to the VIP lounge!")

has_any_role#

Checks if a member has at least one of the roles. Returns True or False.

python

has_any_role(member, *roles)

has_permission#

Checks if a member has all the permissions you list. Returns True or False.

python

has_permission(member, *permissions)

Write permission names in lowercase with _, like "manage_messages", "kick_members" or "administrator". A wrong name stops the script and lists the valid names.

python

if has_permission(user, "manage_messages"):
    purge_messages(channel.id, 10)

has_any_permission#

Checks if a member has at least one of the permissions. Returns True or False.

python

has_any_permission(member, *permissions)

get_role#

Finds a role. Returns None when there is no match.

python

get_role(role)

role is a role ID (a number) or the exact role name.

python

vip = get_role("VIP")
set_content(f"{vip.mention} has {len(list_members(vip))} members")

get_roles#

Finds several roles at once. Returns the ones that match. Names or IDs with no match are skipped.

python

get_roles(*roles)

To list every role in the server, use server.get_roles().values().

create_role#

Makes a new role. Returns the role.

python

create_role(name, **options)

Extra options go to Discord, for example color, hoist (show separately) and mentionable.

python

role = create_role("Event Winner", color=0xF1C40F, hoist=True)
add_roles(user, role)

update_role#

Changes a role. Returns the changed role.

python

update_role(role, **options)

python

update_role("Event Winner", name="Last Event Winner")

delete_role#

Deletes a role.

python

delete_role(role)

change_nick#

Changes a member's nickname. The bot cannot change the server owner's nickname.

python

change_nick(member, nick)

python

change_nick(user, f"[AFK] {user.display_name}")

edit_member#

Changes several things about a member at once.

python

await edit_member(member, **options)

Options go to Discord, for example nickname, mute, deaf and voice_channel.

kick_member#

Kicks a member from the server. They can join again with an invite.

python

kick_member(member, reason=None)

python

kick_member(target, reason=f"Kicked by {user.display_name}")

ban_member#

Bans a member from the server.

python

ban_member(member, reason=None)

timeout_member#

Times out a member. They cannot talk or react until it ends.

python

timeout_member(member, time)

time is text like "10 minutes" or "1 day". The longest timeout is 28 days.

python

timeout_member(target, "1 hour")

remove_timeout#

Ends a member's timeout early.

python

remove_timeout(member)

mute_member#

Server-mutes a member in voice. unmute_member undoes it.

python

mute_member(member)
unmute_member(member)

deaf_member#

Server-deafens a member in voice. undeaf_member undoes it.

python

deaf_member(member)
undeaf_member(member)

move_member#

Moves a member to another voice or stage channel. With no channel, it disconnects them from voice.

python

move_member(member, channel=None)

python

move_member(user, "AFK")

get_voice_state#

Gets a member's voice status, for example which voice channel they are in. Returns None when they are not in voice.

python

get_voice_state(member)

python

state = get_voice_state(user)
if state is None:
    set_error("Join a voice channel first.")

get_user_mentions#

Finds the users mentioned in a message or a text.

python

get_user_mentions(message)

get_role_mentions and get_channel_mentions do the same for roles and channels.

get_permission#

Turns permission names into one permissions value. Useful when you create roles or channels.

python

get_permission(*permissions, safe=False)

With safe=True, wrong names are skipped instead of stopping the script.

python

create_role("Helpers", permissions=get_permission("manage_messages", "kick_members"))

These functions work in commands, events and component handlers.

Most of them need no await. The bot adds it for you. The table shows the ones where you must write await yourself.

Write `await` yourself	No `await` needed
`get_or_fetch_member`, `getch_member`, `edit_member`	everything else on this page

The bot needs permission

Every action here needs the matching Discord permission, like Manage Roles or Ban Members. The bot's own role must also be above the roles and members it changes. Discord rule.

Limits#

Each run of a command or event can change a fixed number of roles. Pre-hook and post-hook share one count.

Function	Free	Premium
`add_roles`	5	15
`remove_roles`	5	15

get_member#

Finds a member by ID. Looks only in the bot's memory, so it is fast. Returns None when the member is not found.

python

get_member(member_id)

member_id must be a number. Text like "1234" does not work. Use int(...) first.

python

member = get_member(int(user_id_text))
if member is None:
    set_error("That member is not in the server.")

get_or_fetch_member#

Finds a member by ID. When the bot does not have them in memory, it asks Discord. Returns None when the member is not in the server.

python

await get_or_fetch_member(member_id)

getch_member is a short name for the same function.

python

member = await getch_member(1290000000000000000)

list_members#

Lists the members who have a role.

python

list_members(
    role,
    ignored_roles=None,
    as_mention=True,
    role_cond="any",
    ignore_cond="any",
)

Argument	What it does
`role`	A role, role ID or role name. A list of them also works.
`ignored_roles`	A list of role IDs. Members with these roles are left out.
`as_mention`	`True` gives mentions like `@Alex`. `False` gives member objects.
`role_cond`	`"any"`: has any of the roles. `"all"`: has all of them.
`ignore_cond`	`"any"` or `"all"`, the same way for `ignored_roles`.

python

staff = list_members("Staff")
set_content(f"Our staff: {', '.join(staff)}")

add_roles#

Gives one or more roles to a member.

python

add_roles(member, *roles, after=None)

Argument	What it does
`member`	The member.
`*roles`	Roles, role IDs or role names. Add as many as you like.
`after`	A time like `"10 minutes"` or `"2 days"`. The role is added after that time.

python

add_roles(user, "Verified", "Member")

Watch out

Do not use member.add_role(...). It is blocked. Always use add_roles.

remove_roles#

Takes one or more roles away from a member. Same arguments as add_roles.

python

remove_roles(member, *roles, after=None)

Example: a temporary role

python

add_roles(user, "Event Pass")
remove_roles(user, "Event Pass", after="24 hours")

A delayed change is saved, so it still happens after the bot restarts.

has_role#

Checks if a member has all the roles you list. Returns True or False.

python

has_role(member, *roles)

python

if has_role(user, "VIP"):
    set_content("Welcome to the VIP lounge!")

has_any_role#

Checks if a member has at least one of the roles. Returns True or False.

python

has_any_role(member, *roles)

has_permission#

Checks if a member has all the permissions you list. Returns True or False.

python

has_permission(member, *permissions)

Write permission names in lowercase with _, like "manage_messages", "kick_members" or "administrator". A wrong name stops the script and lists the valid names.

python

if has_permission(user, "manage_messages"):
    purge_messages(channel.id, 10)

has_any_permission#

Checks if a member has at least one of the permissions. Returns True or False.

python

has_any_permission(member, *permissions)

get_role#

Finds a role. Returns None when there is no match.

python

get_role(role)

role is a role ID (a number) or the exact role name.

python

vip = get_role("VIP")
set_content(f"{vip.mention} has {len(list_members(vip))} members")

get_roles#

Finds several roles at once. Returns the ones that match. Names or IDs with no match are skipped.

python

get_roles(*roles)

To list every role in the server, use server.get_roles().values().

create_role#

Makes a new role. Returns the role.

python

create_role(name, **options)

Extra options go to Discord, for example color, hoist (show separately) and mentionable.

python

role = create_role("Event Winner", color=0xF1C40F, hoist=True)
add_roles(user, role)

update_role#

Changes a role. Returns the changed role.

python

update_role(role, **options)

python

update_role("Event Winner", name="Last Event Winner")

delete_role#

Deletes a role.

python

delete_role(role)

change_nick#

Changes a member's nickname. The bot cannot change the server owner's nickname.

python

change_nick(member, nick)

python

change_nick(user, f"[AFK] {user.display_name}")

edit_member#

Changes several things about a member at once.

python

await edit_member(member, **options)

Options go to Discord, for example nickname, mute, deaf and voice_channel.

kick_member#

Kicks a member from the server. They can join again with an invite.

python

kick_member(member, reason=None)

python

kick_member(target, reason=f"Kicked by {user.display_name}")

ban_member#

Bans a member from the server.

python

ban_member(member, reason=None)

timeout_member#

Times out a member. They cannot talk or react until it ends.

python

timeout_member(member, time)

time is text like "10 minutes" or "1 day". The longest timeout is 28 days.

python

timeout_member(target, "1 hour")

remove_timeout#

Ends a member's timeout early.

python

remove_timeout(member)

mute_member#

Server-mutes a member in voice. unmute_member undoes it.

python

mute_member(member)
unmute_member(member)

deaf_member#

Server-deafens a member in voice. undeaf_member undoes it.

python

deaf_member(member)
undeaf_member(member)

move_member#

Moves a member to another voice or stage channel. With no channel, it disconnects them from voice.

python

move_member(member, channel=None)

python

move_member(user, "AFK")

get_voice_state#

Gets a member's voice status, for example which voice channel they are in. Returns None when they are not in voice.

python

get_voice_state(member)

python

state = get_voice_state(user)
if state is None:
    set_error("Join a voice channel first.")

get_user_mentions#

Finds the users mentioned in a message or a text.

python

get_user_mentions(message)

get_role_mentions and get_channel_mentions do the same for roles and channels.

get_permission#

Turns permission names into one permissions value. Useful when you create roles or channels.

python

get_permission(*permissions, safe=False)

With safe=True, wrong names are skipped instead of stopping the script.

python

create_role("Helpers", permissions=get_permission("manage_messages", "kick_members"))