# Members and roles

> Find members, give and take roles, and kick, ban, time out or move people.

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"))
```