Skip to main content

​
Channel Resource

Channels represent spaces for communication within guilds or direct messages between users.

​
Channel Object

​
Structure

​
id
Snowflake
required
Unique channel identifier
​
type
integer
required
Channel type (see Channel Types)
​
guild_id
Snowflake | null
Guild ID (null for DM channels)
​
name
string | null
Channel name (1-100 characters for guild channels)
​
topic
string | null
Channel topic/description (max 1024 characters)
​
icon_hash
string | null
Hash of the channel’s icon (group DMs)
​
url
string | null
URL for link channels
​
parent_id
Snowflake | null
ID of parent category channel
​
position
integer
default:"0"
Sorting position
​
owner_id
Snowflake | null
Owner ID for group DMs
​
recipient_ids
array of Snowflakes
Recipient user IDs for DM/group DM channels
​
nsfw
boolean
default:"false"
Whether the channel is age-restricted
​
rate_limit_per_user
integer
default:"0"
Slowmode delay in seconds (0-21600)
​
bitrate
integer | null
Voice channel bitrate in bits per second
​
user_limit
integer | null
Voice channel user limit (0 = unlimited)
​
rtc_region
string | null
Voice region override (null = automatic)
​
last_message_id
Snowflake | null
ID of the last message sent
​
last_pin_timestamp
ISO8601 timestamp | null
When the last message was pinned
​
permission_overwrites
array of objects
Permission overwrite objects (see Permission Overwrites)
​
version
integer
required
Version for optimistic concurrency control

​
Example Channel

{
  "id": "444555666777888999",
  "type": 0,
  "guild_id": "987654321098765432",
  "name": "general",
  "topic": "Welcome to the general chat!",
  "icon_hash": null,
  "parent_id": "333444555666777888",
  "position": 0,
  "nsfw": false,
  "rate_limit_per_user": 0,
  "last_message_id": "555666777888999000",
  "last_pin_timestamp": "2026-03-01T15:30:00.000Z",
  "permission_overwrites": [],
  "version": 12
}

​
Channel Types

​
Permission Overwrites

Permission overwrites control role or member-specific permissions in a channel.

​
Structure

​
id
Snowflake
required
Role or user ID
​
type
integer
required
0 for role, 1 for member
​
allow
string
required
Allowed permissions bitfield
​
deny
string
required
Denied permissions bitfield

​
Example

{
  "id": "222333444555666777",
  "type": 0,
  "allow": "1024",
  "deny": "2048"
}

​
Permissions

Channel permissions control what actions users can perform. See the Permissions page for the complete list.

​
Common Permissions

​
Endpoints

​
Get Channel

GET /api/v1/channels/{channel_id}
Returns a channel object.

​
Modify Channel

PATCH /api/v1/channels/{channel_id}
Update channel settings. Requires MANAGE_CHANNELS permission.
​
name
string
New channel name (1-100 characters)
​
topic
string | null
New topic (max 1024 characters)
​
position
integer
New sorting position
​
nsfw
boolean
Whether the channel is NSFW
​
rate_limit_per_user
integer
Slowmode delay in seconds (0-21600)
​
bitrate
integer
Voice channel bitrate (8000-384000)
​
user_limit
integer
Voice channel user limit (0-99, 0 = unlimited)
​
parent_id
Snowflake | null
New parent category
​
permission_overwrites
array
Permission overwrite objects

​
Delete Channel

DELETE /api/v1/channels/{channel_id}
Delete the channel. Requires MANAGE_CHANNELS permission or channel ownership (for DMs).

​
Get Channel Messages

GET /api/v1/channels/{channel_id}/messages
Returns messages in the channel.
​
limit
integer
default:"50"
Max messages to return (1-100)
​
before
Snowflake
Get messages before this message ID
​
after
Snowflake
Get messages after this message ID
​
around
Snowflake
Get messages around this message ID

​
Create Message

POST /api/v1/channels/{channel_id}/messages
Send a message to the channel. See Messages for details.

​
Trigger Typing

POST /api/v1/channels/{channel_id}/typing
Trigger a typing indicator (lasts ~10 seconds).

​
Get Pinned Messages

GET /api/v1/channels/{channel_id}/pins
Returns all pinned messages in the channel.

​
Pin Message

PUT /api/v1/channels/{channel_id}/pins/{message_id}
Pin a message. Requires MANAGE_MESSAGES permission.

​
Unpin Message

DELETE /api/v1/channels/{channel_id}/pins/{message_id}
Unpin a message. Requires MANAGE_MESSAGES permission.

Build docs developers (and LLMs) love

Get started for freeTalk to us