Guild channels¶

A guild is divided into channels, and categories group them. The routes on this page list a guild's channels, create channels and categories, and change their order and parent. Channels defines the channel object and every per-channel operation, including modifying and deleting a channel or category, and setting permission overwrites.

All routes are relative to https://tebhos.com/api/v1, require authentication and accept both user sessions and bot tokens, except where a route is marked user-only (a valid bot token is then refused with 403 ACCESS_DENIED). A caller who is not a member of the guild receives 403 FORBIDDEN. Error bodies follow Errors.

Guild channel types¶

These are the channel types that exist inside a guild, and the values Create guild channel accepts in type.

A category is a channel row of type 4. It has a name, a position and permission overwrites, and other channels point to it with parent_id. Categories cannot be nested.

Create permission overwrite object¶

The initial overwrites a channel can be created with. The stored form is the permission overwrite object.

The same bit in both allow and deny returns 400 BAD_REQUEST. Bits that name no defined permission are dropped.

{
  "id": "1489002177550843904",
  "type": 0,
  "allow": "0",
  "deny": "1024"
}

Channel position object¶

One entry of Modify guild channel positions.

Siblings are counted per bucket: categories are ordered among the other categories, and every other channel is ordered among the channels with the same parent (or among the top-level channels). When an entry has neither position nor preceding_sibling_id, a voice channel is placed last and any other channel directly before the first voice sibling.

{
  "id": "1501314428688998182",
  "parent_id": "1501314428688998100",
  "preceding_sibling_id": null,
  "lock_permissions": true
}

List guild channels¶

GET /guilds/{guild_id}/channels

Returns an array of channel objects for the guild, ordered by position and then by ID. A channel or category is included only when the caller holds VIEW_CHANNEL in it. Requires membership. The route has no pagination.

Rate limit: guild:channels:list, 60 per 10 seconds per account and guild.

curl https://tebhos.com/api/v1/guilds/1489002177550843904/channels \
  -H "Authorization: Bot $TEBHOS_BOT_TOKEN"

Create guild channel¶

POST /guilds/{guild_id}/channels

Creates a channel or category and returns its channel object with status 201. Requires MANAGE_CHANNELS. The guild receives Channel Create.

Creating a category (type 4) is user-only. Creating any other type also accepts a bot token.

Rate limit: guild:channel:create, 10 per 60 seconds per account and guild (text, voice and link channels; category creation has no route bucket).

JSON body¶

For a category, only name and permission_overwrites are used.

Permission overwrites. When permission_overwrites is omitted, a channel created inside a category copies that category's overwrites. When it is present (an empty array included), it replaces that inheritance completely. Supplying it requires MANAGE_ROLES as well, and every bit an overwrite allows must be a bit the caller holds in the parent category (or in the guild when there is no parent); otherwise the request fails with 403 FORBIDDEN before anything is created. See Role hierarchy.

Bitrate. A new voice channel defaults to 64000 (64 kbps). The lowest accepted value is 8000 (8 kbps). The highest bitrate a caller can set is the larger of their own allowance and the guild's boost allowance:

A higher value returns 403 BITRATE_REQUIRES_UPGRADE, or 400 BITRATE_EXCEEDS_LIMIT when the ceiling is already 384 kbps.

Position. A new channel is placed after the highest position among the channels with the same parent. A new category is placed after the last category.

Creating a text, voice or link channel records a CHANNEL_CREATE audit log entry.

curl -X POST https://tebhos.com/api/v1/guilds/1489002177550843904/channels \
  -H "Authorization: Bot $TEBHOS_BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "announcements",
    "type": 0,
    "parent_id": "1501314428688998100",
    "permission_overwrites": [
      {"id": "1489002177550843904", "type": 0, "deny": "2048"}
    ]
  }'

Modify guild channel positions¶

PATCH /guilds/{guild_id}/channels

Moves and reorders channels and categories, and returns 204 with no body. The body is a JSON array of channel position objects. Requires MANAGE_CHANNELS.

Rate limit: guild:channel:positions, 30 per 10 seconds per account and guild.

Entries are applied in array order, each to the result of the previous one. The whole request is validated before anything is written, so an invalid entry leaves every channel unchanged:

Within each affected bucket, positions are renumbered from 0 in the resulting order. Moving a category changes only its place among the categories; its channels keep their parent. Only rows whose position, parent or overwrites actually change are written.

lock_permissions takes effect only when the entry moves the channel into a different category. It copies the category's overwrites onto the channel and requires MANAGE_ROLES in the moved channel; every bit the copy allows, and every bit it stops denying, must be one the caller holds there.

When at least one channel changed, the guild receives one Channel Update Bulk event carrying the guild's channels as stored after the change. The operation records no audit log entry.

curl -X PATCH https://tebhos.com/api/v1/guilds/1489002177550843904/channels \
  -H "Authorization: Bot $TEBHOS_BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[{"id": "1501314428688998182", "parent_id": "1501314428688998100", "preceding_sibling_id": null}]'

Categories¶

A category is created with Create guild channel and type 4, and moved with Modify guild channel positions. Renaming a category, changing its overwrites and deleting it use the channel routes: Modify channel, Set channel permission overwrite and Delete channel. Sync channel permissions with category copies a category's overwrites onto one of its channels.