Channels Resource

Channel Object

Represents a guild or DM channel within Discord.
Channel Structure
FieldTypeDescription
idsnowflakethe id of this channel
typeintegerthe type of channel
guild_id?snowflakethe id of the guild
position?integersorting position of the channel
permission_overwrites?array of overwrite objectsexplicit permission overwrites for members and roles
name?stringthe name of the channel (2-100 characters)
topic?stringthe channel topic (0-1024 characters)
nsfw?boolif the channel is nsfw
last_message_id??snowflakethe id of the last message sent in this channel (may not point to an existing or valid message)
bitrate?integerthe bitrate (in bits) of the voice channel
user_limit?integerthe user limit of the voice channel
recipients?array of user objectsthe recipients of the DM
icon??stringicon hash
owner_id?snowflakeid of the DM creator
application_id?snowflakeapplication id of the group DM creator if it is bot-created
parent_id??snowflakeid of the parent category for a channel
Channel Types
TypeID
GUILD_TEXT0
DM1
GUILD_VOICE2
GROUP_DM3
GUILD_CATEGORY4
Example Guild Text Channel
{
    "id": "41771983423143937",
    "guild_id": "41771983423143937",
    "name": "general",
    "type": 0,
    "position": 6,
    "permission_overwrites": [],
    "nsfw": true,
    "topic": "24/7 chat about how to gank Mike #2",
    "last_message_id": "155117677105512449",
    "parent_id": "399942396007890945"
}
Example Guild Voice Channel
{
    "id": "155101607195836416",
    "guild_id": "41771983423143937",
    "name": "ROCKET CHEESE",
    "type": 2,
    "position": 5,
    "permission_overwrites": [],
    "bitrate": 64000,
    "user_limit": 0,
    "parent_id": null
}
Example DM Channel
{
    "last_message_id": "3343820033257021450",
    "type": 1,
    "id": "319674150115610528",
    "recipients": [
        {
            "username": "test",
            "discriminator": "9999",
            "id": "82198898841029460",
            "avatar": "33ecab261d4681afa4d85a04691c4a01"
        }
    ]
}
Example Group DM Channel
{
    "name": "Some test channel",
    "icon": null,
    "recipients": [
        {
            "username": "test",
            "discriminator": "9999",
            "id": "82198898841029460",
            "avatar": "33ecab261d4681afa4d85a04691c4a01"
        },
        {
            "username": "test2",
            "discriminator": "9999",
            "id": "82198810841029460",
            "avatar": "33ecab261d4681afa4d85a10691c4a01"
        }
    ],
    "last_message_id": "3343820033257021450",
    "type": 3,
    "id": "319674150115710528",
    "owner_id": "82198810841029460"
}
Example Channel Category
{
    "permission_overwrites": [],
    "name": "Test",
    "parent_id": null,
    "nsfw": false,
    "position": 0,
    "guild_id": "290926798629997250",
    "type": 4,
    "id": "399942396007890945"
}

Message Object

Represents a message sent in a channel within Discord.
Message Structure
FieldTypeDescription
idsnowflakeid of the message
channel_idsnowflakeid of the channel the message was sent in
author*user objectthe author of this message (not guaranteed to be a valid user, see below)
contentstringcontents of the message
timestampISO8601 timestampwhen this message was sent
edited_timestamp?ISO8601 timestampwhen this message was edited (or null if never)
ttsboolwhether this was a TTS message
mention_everyoneboolwhether this message mentions everyone
mentionsarray of user objectsusers specifically mentioned in the message
mention_rolesarray of role object idsroles specifically mentioned in this message
attachmentsarray of attachment objectsany attached files
embedsarray of embed objectsany embedded content
reactions?array of reaction objectsreactions to the message
nonce??snowflakeused for validating a message was sent
pinnedboolwhether this message is pinned
webhook_id?stringif the message is generated by a webhook, this is the webhook's id
typeinttype of message
  • The author object follows the structure of the user object, but is only a valid user in the case where the message is generated by a user or bot user. If the message is generated by a webhook, the author object corresponds to the webhook's id, username, and avatar. You can tell if a message is generated by a webhook by checking for the webhook_id on the message object.
Message Types
TypeValue
DEFAULT0
RECIPIENT_ADD1
RECIPIENT_REMOVE2
CALL3
CHANNEL_NAME_CHANGE4
CHANNEL_ICON_CHANGE5
CHANNEL_PINNED_MESSAGE6
GUILD_MEMBER_JOIN7
Example Message
{
    "reactions": [
        {
            "count": 1,
            "me": false,
            "emoji": {
                "id": null,
                "name": "🔥"
            }
        }
    ],
    "attachments": [],
    "tts": false,
    "embeds": [],
    "timestamp": "2017-07-11T17:27:07.299000+00:00",
    "mention_everyone": false,
    "id": "334385199974967042",
    "pinned": false,
    "edited_timestamp": null,
    "author": {
        "username": "Mason",
        "discriminator": "9999",
        "id": "53908099506183680",
        "avatar": "a_bab14f271d565501444b2ca3be944b25"
    },
    "mention_roles": [],
    "content": "Supa Hot",
    "channel_id": "290926798999357250",
    "mentions": [],
    "type": 0
}

Reaction Object

Reaction Structure
FieldTypeDescription
countintegertimes this emoji has been used to react
meboolwhether the current user reacted using this emoji
emojipartial emoji objectemoji information

Overwrite Object

Overwrite Structure
FieldTypeDescription
idsnowflakerole or user id
typestringeither "role" or "member"
allowintegerpermission bit set
denyintegerpermission bit set

Embed Object

Embed Structure
FieldTypeDescription
titlestringtitle of embed
typestringtype of embed (always "rich" for webhook embeds)
descriptionstringdescription of embed
urlstringurl of embed
timestampISO8601 timestamptimestamp of embed content
colorintegercolor code of the embed
footerembed footer objectfooter information
imageembed image objectimage information
thumbnailembed thumbnail objectthumbnail information
videoembed video objectvideo information
providerembed provider objectprovider information
authorembed author objectauthor information
fieldsarray of embed field objectsfields information
Embed Thumbnail Structure
FieldTypeDescription
urlstringsource url of thumbnail (only supports http(s) and attachments)
proxy_urlstringa proxied url of the thumbnail
heightintegerheight of thumbnail
widthintegerwidth of thumbnail
Embed Video Structure
FieldTypeDescription
urlstringsource url of video
heightintegerheight of video
widthintegerwidth of video
Embed Image Structure
FieldTypeDescription
urlstringsource url of image (only supports http(s) and attachments)
proxy_urlstringa proxied url of the image
heightintegerheight of image
widthintegerwidth of image
Embed Provider Structure
FieldTypeDescription
namestringname of provider
urlstringurl of provider
Embed Author Structure
FieldTypeDescription
namestringname of author
urlstringurl of author
icon_urlstringurl of author icon (only supports http(s) and attachments)
proxy_icon_urlstringa proxied url of author icon
FieldTypeDescription
textstringfooter text
icon_urlstringurl of footer icon (only supports http(s) and attachments)
proxy_icon_urlstringa proxied url of footer icon
Embed Field Structure
FieldTypeDescription
namestringname of the field
valuestringvalue of the field
inlineboolwhether or not this field should display inline

Attachment Object

Attachment Structure
FieldTypeDescription
idsnowflakeattachment id
filenamestringname of file attached
sizeintegersize of file in bytes
urlstringsource url of file
proxy_urlstringa proxied url of file
height?integerheight of file (if image)
width?integerwidth of file (if image)

Embed Limits

To facilitate showing rich content, rich embeds do not follow the traditional limits of message content. However, some limits are still in place to prevent excessively large embeds. The following table describes the limits:
Limits
FieldLimit
title256 characters
description2048 characters
fieldsUp to 25 field objects
field.name256 characters
field.value1024 characters
footer.text2048 characters
author.name256 characters
In addition to the limits above, the sum of all characters in an embed structure must not exceed 6000 characters.

Get Channel

GET/channels/{channel.id}
Get a channel by ID. Returns a channel object.

Modify Channel

PUT/PATCH/channels/{channel.id}
Update a channels settings. Requires the 'MANAGE_CHANNELS' permission for the guild. Returns a channel on success, and a 400 BAD REQUEST on invalid parameters. Fires a Channel Update Gateway event. If modifying a category, individual Channel Update events will fire for each child channel that also changes. For the PATCH method, all the JSON Params are optional.
JSON Params
FieldTypeDescriptionChannel Type
namestring2-100 character channel nameAll
positionintegerthe position of the channel in the left-hand listingAll
topicstring0-1024 character channel topicText
nsfwboolif the channel is nsfwText
bitrateintegerthe bitrate (in bits) of the voice channel; 8000 to 96000 (128000 for VIP servers)Voice
user_limitintegerthe user limit of the voice channel; 0 refers to no limit, 1 to 99 refers to a user limitVoice
permission_overwritesarray of overwrite objectschannel or category-specific permissionsAll
parent_idsnowflakeid of the new parent category for a channelText, Voice

Delete/Close Channel

DELETE/channels/{channel.id}
Delete a channel, or close a private message. Requires the 'MANAGE_CHANNELS' permission for the guild. Deleting a category does not delete its child channels; they will have their parent_id removed and a Channel Update Gateway event will fire for each of them. Returns a channel object on success. Fires a Channel Delete Gateway event.
Deleting a guild channel cannot be undone. Use this with caution, as it is impossible to undo this action when performed on a guild channel. In contrast, when used with a private message, it is possible to undo the action by opening a private message with the recipient again.

Get Channel Messages

GET/channels/{channel.id}/messages
Returns the messages for a channel. If operating on a guild channel, this endpoint requires the 'READ_MESSAGES' permission to be present on the current user. Returns an array of message objects on success.
The before, after, and around keys are mutually exclusive, only one may be passed at a time.
Query String Params
FieldTypeDescriptionRequiredDefault
aroundsnowflakeget messages around this message IDfalseabsent
beforesnowflakeget messages before this message IDfalseabsent
aftersnowflakeget messages after this message IDfalseabsent
limitintegermax number of messages to return (1-100)false50

Get Channel Message

GET/channels/{channel.id}/messages/{message.id}
Returns a specific message in the channel. If operating on a guild channel, this endpoints requires the 'READ_MESSAGE_HISTORY' permission to be present on the current user. Returns a message object on success.

Create Message

POST/channels/{channel.id}/messages
Post a message to a guild text or DM channel. If operating on a guild channel, this endpoint requires the 'SEND_MESSAGES' permission to be present on the current user. Returns a message object. Fires a Message Create Gateway event. See message formatting for more information on how to properly format messages.
This endpoint supports both JSON and form data bodies. It does require multipart/form-data requests instead of the normal JSON request type when uploading files. Make sure you set your Content-Type to multipart/form-data if you're doing that. Note that in that case, the embed field cannot be used, but you can pass an url-encoded JSON body as a form value for payload_json.
JSON Params
FieldTypeDescriptionRequired
contentstringthe message contents (up to 2000 characters)true
noncesnowflakea nonce that can be used for optimistic message sendingfalse
ttsbooltrue if this is a TTS messagefalse
filefile contentsthe contents of the file being sentone of content, file, embeds (multipart form data only)
embedembed objectembedded rich contentfalse
For the embed object, you can set every field except type (it will be rich regardless of if you try to set it), provider, video, and any height, width, or proxy_url values for images.
Using Attachments within Embeds
You can upload attachments when creating a message and use those attachments within your embed. To do this, you will want to upload files as part of your multipart/form-data body. Make sure that you're uploading files that contain a filename, as you will need a filename to reference against.In the embed object, you can then set an image to use an attachment as its url with our attachment scheme syntax: attachment://filename.pngFor example:
{
    "embed": {
        "image": {
            "url": "attachment://screenshot.png"
        }
    }
}
Only filenames with proper image extensions are supported for the time being.

Create Reaction

PUT/channels/{channel.id}/messages/{message.id}/reactions/{emoji}/@me
Create a reaction for the message. This endpoint requires the 'READ_MESSAGE_HISTORY' permission to be present on the current user. Additionally, if nobody else has reacted to the message using this emoji, this endpoint requires the 'ADD_REACTIONS' permission to be present on the current user. Returns a 204 empty response on success.

Delete Own Reaction

DELETE/channels/{channel.id}/messages/{message.id}/reactions/{emoji}/@me
Delete a reaction the current user has made for the message. Returns a 204 empty response on success.

Delete User Reaction

DELETE/channels/{channel.id}/messages/{message.id}/reactions/{emoji}/{user.id}
Deletes another user's reaction. This endpoint requires the 'MANAGE_MESSAGES' permission to be present on the current user. Returns a 204 empty response on success.

Get Reactions

GET/channels/{channel.id}/messages/{message.id}/reactions/{emoji}
Get a list of users that reacted with this emoji. Returns an array of user objects on success.
Query String Params
FieldTypeDescriptionRequiredDefault
beforesnowflakeget users before this user IDfalseabsent
aftersnowflakeget users after this user IDfalseabsent
limitintegermax number of users to return (1-100)false100

Delete All Reactions

DELETE/channels/{channel.id}/messages/{message.id}/reactions
Deletes all reactions on a message. This endpoint requires the 'MANAGE_MESSAGES' permission to be present on the current user.

Edit Message

PATCH/channels/{channel.id}/messages/{message.id}
Edit a previously sent message. You can only edit messages that have been sent by the current user. Returns a message object. Fires a Message Update Gateway event.
All parameters to this endpoint are optional.
JSON Params
FieldTypeDescription
contentstringthe new message contents (up to 2000 characters)
embedembed objectembedded rich content

Delete Message

DELETE/channels/{channel.id}/messages/{message.id}
Delete a message. If operating on a guild channel and trying to delete a message that was not sent by the current user, this endpoint requires the 'MANAGE_MESSAGES' permission. Returns a 204 empty response on success. Fires a Message Delete Gateway event.

Bulk Delete Messages

POST/channels/{channel.id}/messages/bulk-delete
Delete multiple messages in a single request. This endpoint can only be used on guild channels and requires the 'MANAGE_MESSAGES' permission. Returns a 204 empty response on success. Fires multiple Message Delete Gateway events.Any message IDs given that do not exist or are invalid will count towards the minimum and maximum message count (currently 2 and 100 respectively). Additionally, duplicated IDs will only be counted once.
This endpoint will not delete messages older than 2 weeks, and will fail if any message provided is older than that. An endpoint will be added in the future to prune messages older than 2 weeks from a channel.
JSON Params
FieldTypeDescription
messagesarray of snowflakesan array of message ids to delete (2-100)

Bulk Delete Messages (deprecated)

POST/channels/{channel.id}/messages/bulk_delete
Same as above, but this endpoint is deprecated.

Edit Channel Permissions

PUT/channels/{channel.id}/permissions/{overwrite.id}
Edit the channel permission overwrites for a user or role in a channel. Only usable for guild channels. Requires the 'MANAGE_ROLES' permission. Returns a 204 empty response on success. For more information about permissions, see permissions.
JSON Params
FieldTypeDescription
allowintegerthe bitwise value of all allowed permissions
denyintegerthe bitwise value of all disallowed permissions
typestring"member" for a user or "role" for a role

Get Channel Invites

GET/channels/{channel.id}/invites
Returns a list of invite objects (with invite metadata) for the channel. Only usable for guild channels. Requires the 'MANAGE_CHANNELS' permission.

Create Channel Invite

POST/channels/{channel.id}/invites
Create a new invite object for the channel. Only usable for guild channels. Requires the CREATE_INSTANT_INVITE permission. All JSON paramaters for this route are optional, however the request body is not. If you are not sending any fields, you still have to send an empty JSON object ({}). Returns an invite object.
JSON Params
FieldTypeDescriptionDefault
max_ageintegerduration of invite in seconds before expiry, or 0 for never86400 (24 hours)
max_usesintegermax number of uses or 0 for unlimited0
temporaryboolwhether this invite only grants temporary membershipfalse
uniqueboolif true, don't try to reuse a similar invite (useful for creating many unique one time use invites)false

Delete Channel Permission

DELETE/channels/{channel.id}/permissions/{overwrite.id}
Delete a channel permission overwrite for a user or role in a channel. Only usable for guild channels. Requires the 'MANAGE_ROLES' permission. Returns a 204 empty response on success. For more information about permissions, see permissions

Trigger Typing Indicator

POST/channels/{channel.id}/typing
Post a typing indicator for the specified channel. Generally bots should not implement this route. However, if a bot is responding to a command and expects the computation to take a few seconds, this endpoint may be called to let the user know that the bot is processing their message. Returns a 204 empty response on success. Fires a Typing Start Gateway event.

Get Pinned Messages

GET/channels/{channel.id}/pins
Returns all pinned messages in the channel as an array of message objects.

Add Pinned Channel Message

PUT/channels/{channel.id}/pins/{message.id}
Pin a message in a channel. Requires the 'MANAGE_MESSAGES' permission. Returns a 204 empty response on success.

Delete Pinned Channel Message

DELETE/channels/{channel.id}/pins/{message.id}
Delete a pinned message in a channel. Requires the 'MANAGE_MESSAGES' permission. Returns a 204 empty response on success.

Group DM Add Recipient

PUT/channels/{channel.id}/recipients/{user.id}
Adds a recipient to a Group DM using their access token
JSON Params
FieldTypeDescription
access_tokenstringaccess token of a user that has granted your app the gdm.join scope
nickstringnickname of the user being added

Group DM Remove Recipient

DELETE/channels/{channel.id}/recipients/{user.id}
Removes a recipient from a Group DM