channels_modify
Update an existing Discord channel's settings by passing only the fields to change, such as name, topic, slowmode, category, NSFW status, or forum tags.
Instructions
Purpose: Update an existing channel's settings. Pass only the fields you want to change.
When to use:
Rename, move under a category, toggle nsfw, change slowmode, retag a forum channel.
When NOT to use:
Permission overwrites for a single role/user → use
channels_modify_permissions.Deleting → use
channels_delete.
Field applicability mirrors channels_create_guild_channel. Discord ignores fields that do not apply to the channel type.
Permission sync: Set lock_permissions:true with an explicit category parent_id (the current parent for Sync Now, or a new parent to move and sync). This replaces every channel overwrite with the category set, including an empty set, using one PATCH as discord.js does. Requires VIEW_CHANNEL, MANAGE_CHANNELS and MANAGE_ROLES; the conservative preflight checks these on both channel and category. Do not also pass permission_overwrites. A false or omitted flag preserves ordinary modification behavior.
Permission verification: Sync reads both channel and category after PATCH. permissions_verified:true means their parent and complete overwrite sets matched the copied category snapshot. A concurrent category change or unavailable readback returns a non-retriable verification error with patch_succeeded:true; read both channels before retrying.
Forum tags: Read channels_get first. available_tags is the complete desired set: keep IDs for existing tags; omit id only for additions. Every omitted existing ID must be listed in remove_available_tag_ids. Omitted emoji/moderated fields are preserved for existing IDs. The tool reads the current set before PATCH and refuses an incomplete state.
Emoji: emoji_id is a guild emoji ID; application emoji compatibility is not guaranteed. To reuse application emoji artwork, upload it with emojis_create and use the resulting guild emoji ID. Set either emoji_id or emoji_name; set both to null to clear.
Verification: Tag changes are read back after PATCH. After editing forum tags, read existing posts with channels_get or the active/archived thread lists to confirm their applied_tags still reference the retained IDs. Verification failure means PATCH succeeded: read current state before retrying.
Returns: {id, name, type, parent_id, permission_overwrites?, permissions_verified?, available_tags?, applied_tags?, tags_verified?}. tags_verified:true confirms this channel's tag readback only. name is null for DM / unnamed group DM channels.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | New channel name | |
| nsfw | No | ||
| type | No | Convert text↔announcement only (Discord limitation) | |
| flags | No | Channel flags bitfield | |
| topic | No | ||
| bitrate | No | ||
| position | No | ||
| parent_id | No | ||
| channel_id | Yes | Channel to modify | |
| rtc_region | No | ||
| user_limit | No | ||
| applied_tags | No | Complete desired tag IDs on a forum/media post. [] explicitly removes all post tags; omit to preserve. | |
| audit_reason | No | Reason recorded in audit log (X-Audit-Log-Reason header) | |
| available_tags | No | Complete desired tag set. Keep existing IDs; omit id for additions. Read channels_get first. | |
| lock_permissions | No | Copy the complete category overwrite set and verify it. True requires explicit non-null parent_id and excludes permission_overwrites. | |
| default_sort_order | No | ||
| video_quality_mode | No | ||
| rate_limit_per_user | No | ||
| default_forum_layout | No | ||
| permission_overwrites | No | ||
| default_reaction_emoji | No | ||
| remove_available_tag_ids | No | Explicit IDs to delete from the current set; requires available_tags with those IDs omitted. | |
| default_auto_archive_duration | No | ||
| default_thread_rate_limit_per_user | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||