# Channels

> Find, create, change, lock and delete channels and threads.

These functions work in commands, events and component handlers.

When a function asks for a `channel`, you can pass:

- a channel object, like the `channel` variable;
- a channel ID, as a number;
- the exact channel name, like `"general"`.

A channel ID written as text, like `"1234"`, is read as a name and is not found. Use `int(...)` first.

| Write `await` yourself | No `await` needed |
|---|---|
| `lock_channel`, `unlock_channel`, `set_slowmode` | everything else on this page |

> **The bot needs permission:** Creating, changing and deleting channels needs **Manage Channels**. Locking needs permission to edit the channel's permissions.

## get_channel

Finds one channel or thread. Returns `None` when there is no match.

```python
get_channel(channel)
```

```python
log = get_channel("mod-log")
if log is None:
    set_error("Make a #mod-log channel first.")
```

## get_channels

With no arguments, returns every channel in the server, without categories and threads. With arguments, returns the channels that match.

```python
get_channels(*channels)
```

```python
count = len(get_channels())
set_content(f"This server has {count} channels.")
```

## get_text_channels

Returns every text channel. Announcement, forum and media channels are included. Threads are not.

```python
get_text_channels()
```

## get_voice_channels

Returns every voice and stage channel.

```python
get_voice_channels()
```

## is_thread

Checks if a channel is a thread. Returns `True` or `False`.

```python
is_thread(channel)
```

## create_text_channel

Makes a text channel. Returns the new channel.

```python
create_text_channel(name, **options)
```

Options go to Discord, for example `topic`, `category`, `nsfw` and `permission_overwrites`.

```python
ticket = create_text_channel(f"ticket-{user.username}", topic=f"Ticket for {user.display_name}")
send_message(ticket, f"{user.mention} a staff member will be with you soon.")
```

## create_voice_channel

Makes a voice channel. Returns the new channel.

```python
create_voice_channel(name, **options)
```

## create_category

Makes a category. Returns the new category.

```python
create_category(name, **options)
```

## create_thread

Makes a thread. Returns the new thread.

```python
create_thread(
    channel,
    name=None,
    message=None,
    type="public",
    initial_message=None,
)
```

| Argument | What it does |
|---|---|
| `channel` | The channel to make the thread in. |
| `name` | The thread name. Default is `"Unnamed"`. |
| `message` | A message or message ID. The thread starts from that message. |
| `type` | `"public"` or `"private"`. A thread from a message is always public. |
| `initial_message` | Text the bot posts in the new thread. |

```python
create_thread(channel, name=f"Help for {user.display_name}", type="private",
              initial_message=f"{user.mention} describe your problem here.")
```

A message can have only one thread. A second try fails with a clear message.

## update_channel

Changes a channel. Returns the changed channel.

```python
update_channel(channel, **options)
```

```python
update_channel(channel, name="closed-ticket", topic="Closed")
```

## delete_channel

Deletes a channel.

```python
delete_channel(channel)
```

> **Watch out:** A deleted channel cannot come back. Its messages are lost.

## lock_channel

Stops `@everyone` from sending messages in a channel. Other permissions stay as they are.

```python
await lock_channel(channel=None, reason=None)
```

With no channel, it locks the channel where the command ran.

```python
await lock_channel(reason=f"Locked by {user.display_name}")
set_content("This channel is locked.")
```

## unlock_channel

Lets `@everyone` send messages again.

```python
await unlock_channel(channel=None, reason=None)
```

## set_slowmode

Sets how many seconds each member must wait between messages.

```python
await set_slowmode(seconds, channel=None, reason=None)
```

`seconds` goes from `0` (off) to `21600` (6 hours). Bigger numbers are cut to 6 hours.

```python
await set_slowmode(10)
set_content("Slowmode is on: one message every 10 seconds.")
```

## PermissionOverwrites

Sets who can see or use a new channel. Pass it as `permission_overwrites=` to `create_text_channel`, `create_voice_channel`, `create_category`, `create_thread` or `update_channel`.

```python
perms = PermissionOverwrites()
perms.add_role(role, allow=..., deny=...)
perms.add_member(member, allow=..., deny=...)
perms.remove(role_or_member)
```

`allow` and `deny` take a permissions value from `get_permission(...)`.

**Example: a private ticket channel**

```python
perms = PermissionOverwrites()
# @everyone has the same ID as the server
perms.add_role(server.id, deny=get_permission("view_channel"))
perms.add_member(user, allow=get_permission("view_channel", "send_messages"))
perms.add_role(get_role("Staff"), allow=get_permission("view_channel", "send_messages"))

ticket = create_text_channel(f"ticket-{user.username}", permission_overwrites=perms)
```

See the [ticket system guide](https://ccbot.app/docs/guides/tickets) for the full version.