Guild Resource
Guilds in Discord represent an isolated collection of users and channels, and are often referred to as "servers" in the UI.Guild Object
Guild Structure
Field | Type | Description |
---|
id | snowflake | guild id |
name | string | guild name (2-100 characters) |
icon | ?string | icon hash |
splash | ?string | splash hash |
owner? | bool | whether or not the user is the owner of the guild |
owner_id | snowflake | id of owner |
permissions? | integer | total permissions for the user in the guild (does not include channel overrides) |
region | string | voice region id for the guild |
afk_channel_id | ?snowflake | id of afk channel |
afk_timeout | integer | afk timeout in seconds |
embed_enabled? | bool | is this guild embeddable (e.g. widget) |
embed_channel_id? | snowflake | id of embedded channel |
verification_level | integer | verification level required for the guild |
default_message_notifications | integer | default message notifications level |
explicit_content_filter | integer | explicit content filter level |
roles | array of role objects | roles in the guild |
emojis | array of emoji objects | custom guild emojis |
features | array of strings | enabled guild features |
mfa_level | integer | required MFA level for the guild |
application_id | ?snowflake | application id of the guild creator if it is bot-created |
widget_enabled? | bool | whether or not the server widget is enabled |
widget_channel_id? | snowflake | the channel id for the server widget |
system_channel_id | ?snowflake | the id of the channel to which system messages are sent |
joined_at? * | ISO8601 timestamp | when this guild was joined at |
large? * | bool | whether this is considered a large guild |
unavailable? * | bool | is this guild unavailable |
member_count? * | integer | total number of members in this guild |
voice_states? * | array of partial voice state objects | (without the guild_id key) |
members? * | array of guild member objects | users in the guild |
channels? * | array of channel objects | channels in the guild |
presences? * | array of partial presence update objects | presences of the users in the guild |
* These fields are only sent within the GUILD_CREATE event Default Message Notification Level
Key | Value |
---|
ALL_MESSAGES | 0 |
ONLY_MENTIONS | 1 |
Explicit Content Filter Level
Level | Integer |
---|
DISABLED | 0 |
MEMBERS_WITHOUT_ROLES | 1 |
ALL_MEMBERS | 2 |
MFA Level
Level | Integer |
---|
NONE | 0 |
ELEVATED | 1 |
Verification Level
Level | Integer | Description |
---|
NONE | 0 | unrestricted |
LOW | 1 | must have verified email on account |
MEDIUM | 2 | must be registered on Discord for longer than 5 minutes |
HIGH | 3 | (╯°□°)╯︵ ┻━┻ - must be a member of the server for longer than 10 minutes |
VERY_HIGH | 4 | ┻━┻ミヽ(ಠ益ಠ)ノ彡┻━┻ - must have a verified phone number |
Example Guild
{
"id": "41771983423143937",
"application_id": null,
"name": "Discord Developers",
"icon": "86e39f7ae3307e811784e2ffd11a7310",
"splash": null,
"owner_id": "80351110224678912",
"region": "us-east",
"afk_channel_id": "42072017402331136",
"afk_timeout": 300,
"embed_enabled": true,
"embed_channel_id": "41771983444115456",
"verification_level": 1,
"default_message_notifications": 0,
"explicit_content_filter": 0,
"mfa_level": 0,
"widget_enabled": false,
"widget_channel_id": "41771983423143937",
"roles": [],
"emojis": [],
"features": ["INVITE_SPLASH"],
"unavailable": false
}
Unavailable Guild Object
A partial guild object. Represents an Offline Guild, or a Guild whose information has not been provided through Guild Create events during the Gateway connect.Example Unavailable Guild
{
"id": "41771983423143937",
"unavailable": true
}
Guild Embed Object
Guild Embed Structure
Field | Type | Description |
---|
enabled | bool | if the embed is enabled |
channel_id | ?snowflake | the embed channel id |
Example Guild Embed
{
"enabled": true,
"channel_id": "41771983444115456"
}
Guild Member Object
Guild Member Structure
Field | Type | Description |
---|
user | object | user object |
nick? | string | this users guild nickname (if one is set) |
roles | array of snowflakes | array of role object ids |
joined_at | ISO8601 timestamp | when the user joined the guild |
deaf | bool | if the user is deafened |
mute | bool | if the user is muted |
Example Guild Member
{
"user": {},
"nick": "NOT API SUPPORT",
"roles": [],
"joined_at": "2015-04-26T06:26:56.936000+00:00",
"deaf": false,
"mute": false
}
Integration Object
Integration Structure
Field | Type | Description |
---|
id | snowflake | integration id |
name | string | integration name |
type | string | integration type (twitch, youtube, etc) |
enabled | bool | is this integration enabled |
syncing | bool | is this integration syncing |
role_id | snowflake | id that this integration uses for "subscribers" |
expire_behavior | integer | the behavior of expiring subscribers |
expire_grace_period | integer | the grace period before expiring subscribers |
user | user object | user for this integration |
account | account object | integration account information |
synced_at | ISO8601 timestamp | when this integration was last synced |
Integration Account Object
Integration Account Structure
Field | Type | Description |
---|
id | string | id of the account |
name | string | name of the account |
Ban Object
Ban Structure
Field | Type | Description |
---|
reason | ?string | the reason for the ban |
user | user object | the banned user |
Example Ban
{
"reason": "mentioning b1nzy",
"user": {
"username": "Mason",
"discriminator": "9999",
"id": "53908099506183680",
"avatar": "a_bab14f271d565501444b2ca3be944b25"
}
}
Create a new guild. Returns a guild object on success. Fires a Guild Create Gateway event.This endpoint can be used only by bots in less than 10 guilds. Creating channel categories from this endpoint is not supported.
JSON Params
When using the roles
parameter, the first member of the array is used to change properties of the guild's @everyone
role. If you are trying to bootstrap a guild with additional roles, keep this in mind.
Example Partial Channel Object
{
"name": "naming-things-is-hard",
"type": 0
}
If roles are specified, the required id
field within each role object is an integer placeholder, and will be replaced by the API upon consumption. Its purpose is to allow you to overwrite a role's permissions in a channel when also passing in channels with the channels array.
Returns the guild object for the given id.
Modify a guild's settings. Requires the 'MANAGE_GUILD' permission. Returns the updated guild object on success. Fires a Guild Update Gateway event.All parameters to this endpoint are optional
JSON Params
Field | Type | Description |
---|
name | string | guild name |
region | string | guild voice region id |
verification_level | integer | verification level |
default_message_notifications | integer | default message notification level |
explicit_content_filter | integer | explicit content filter level |
afk_channel_id | snowflake | id for afk channel |
afk_timeout | integer | afk timeout in seconds |
icon | string | base64 128x128 jpeg image for the guild icon |
owner_id | snowflake | user id to transfer guild ownership to (must be owner) |
splash | string | base64 128x128 jpeg image for the guild splash (VIP only) |
system_channel_id | snowflake | the id of the channel to which system messages are sent |
Delete a guild permanently. User must be owner. Returns 204 No Content
on success. Fires a Guild Delete Gateway event.
Returns a list of guild channel objects.Create Guild Channel
POST/guilds/{guild.id}/channels
Create a new channel object for the guild. Requires the 'MANAGE_CHANNELS' permission. Returns the new channel object on success. Fires a Channel Create Gateway event.All parameters for this endpoint are optional excluding 'name'
JSON Params
Field | Type | Description |
---|
name | string | channel name (2-100 characters) |
type | integer | the type of channel |
topic | string | channel topic (0-1024 characters) |
bitrate | integer | the bitrate (in bits) of the voice channel (voice only) |
user_limit | integer | the user limit of the voice channel (voice only) |
permission_overwrites | an array of overwrite objects | the channel's permission overwrites |
parent_id | snowflake | id of the parent category for a channel |
nsfw | bool | if the channel is nsfw |
Modify Guild Channel Positions
PATCH/guilds/{guild.id}/channels
Modify the positions of a set of channel objects for the guild. Requires 'MANAGE_CHANNELS' permission. Returns a 204 empty response on success. Fires multiple Channel Update Gateway events.Only channels to be modified are required, with the minimum being a swap between at least two channels.
This endpoint takes a JSON array of parameters in the following format:JSON Params
Field | Type | Description |
---|
id | snowflake | channel id |
position | integer | sorting position of the channel |
Returns a guild member object for the specified user.
Returns a list of guild member objects that are members of the guild.All parameters to this endpoint are optional
Query String Params
Field | Type | Description | Default |
---|
limit | integer | max number of members to return (1-1000) | 1 |
after | snowflake | the highest user id in the previous page | 0 |
Adds a user to the guild, provided you have a valid oauth2 access token for the user with the guilds.join
scope. Returns a 201 Created with the guild member as the body. Fires a Guild Member Add Gateway event. Requires the bot to have the CREATE_INSTANT_INVITE
permission.All parameters to this endpoint except for access_token
are optional.
JSON Params
Field | Type | Description | Permission |
---|
access_token | string | an oauth2 access token granted with the guilds.join to the bot's application for the user you want to add to the guild | |
nick | string | value to set users nickname to | MANAGE_NICKNAMES |
roles | array of snowflakes | array of role ids the member is assigned | MANAGE_ROLES |
mute | bool | if the user is muted | MUTE_MEMBERS |
deaf | bool | if the user is deafened | DEAFEN_MEMBERS |
Modify attributes of a guild member. Returns a 204 empty response on success. Fires a Guild Member Update Gateway event.All parameters to this endpoint are optional. When moving members to channels, the API user
must have permissions to both connect to the channel and have the MOVE_MEMBERS permission.
JSON Params
Field | Type | Description | Permission |
---|
nick | string | value to set users nickname to | MANAGE_NICKNAMES |
roles | array of snowflakes | array of role ids the member is assigned | MANAGE_ROLES |
mute | bool | if the user is muted | MUTE_MEMBERS |
deaf | bool | if the user is deafened | DEAFEN_MEMBERS |
channel_id | snowflake | id of channel to move user to (if they are connected to voice) | MOVE_MEMBERS |
Modify Current User Nick
PATCH/guilds/{guild.id}/members/@me/nick
Modifies the nickname of the current user in a guild. Returns a 200 with the nickname on success. Fires a Guild Member Update Gateway event.JSON Params
Field | Type | Description | Permission |
---|
nick | string | value to set users nickname to | CHANGE_NICKNAME |
Adds a role to a guild member. Requires the 'MANAGE_ROLES' permission. Returns a 204 empty response on success. Fires a Guild Member Update Gateway event.
Removes a role from a guild member. Requires the 'MANAGE_ROLES' permission. Returns a 204 empty response on success. Fires a Guild Member Update Gateway event.
Remove a member from a guild. Requires 'KICK_MEMBERS' permission. Returns a 204 empty response on success. Fires a Guild Member Remove Gateway event.
Returns a list of ban objects for the users banned from this guild. Requires the 'BAN_MEMBERS' permission.
Create a guild ban, and optionally delete previous messages sent by the banned user. Requires the 'BAN_MEMBERS' permission. Returns a 204 empty response on success. Fires a Guild Ban Add Gateway event.Query String Params
Field | Type | Description |
---|
delete-message-days | integer | number of days to delete messages for (0-7) |
reason | string | reason for the ban |
Remove the ban for a user. Requires the 'BAN_MEMBERS' permissions. Returns a 204 empty response on success. Fires a Guild Ban Remove Gateway event.
Returns a list of role objects for the guild.
Create a new role for the guild. Requires the 'MANAGE_ROLES' permission. Returns the new role object on success. Fires a Guild Role Create Gateway event. All JSON params are optional.JSON Params
Field | Type | Description | Default |
---|
name | string | name of the role | "new role" |
permissions | integer | bitwise of the enabled/disabled permissions | @everyone permissions in guild |
color | integer | RGB color value | 0 |
hoist | bool | whether the role should be displayed separately in the sidebar | false |
mentionable | bool | whether the role should be mentionable | false |
Modify Guild Role Positions
PATCH/guilds/{guild.id}/roles
Modify the positions of a set of role objects for the guild. Requires the 'MANAGE_ROLES' permission. Returns a list of all of the guild's role objects on success. Fires multiple Guild Role Update Gateway events.This endpoint takes a JSON array of parameters in the following format:JSON Params
Field | Type | Description |
---|
id | snowflake | role |
position | integer | sorting position of the role |
Modify a guild role. Requires the 'MANAGE_ROLES' permission. Returns the updated role on success. Fires a Guild Role Update Gateway event.JSON Params
Field | Type | Description |
---|
name | string | name of the role |
permissions | integer | bitwise of the enabled/disabled permissions |
color | integer | RGB color value |
hoist | bool | whether the role should be displayed separately in the sidebar |
mentionable | bool | whether the role should be mentionable |
Delete a guild role. Requires the 'MANAGE_ROLES' permission. Returns a 204 empty response on success. Fires a Guild Role Delete Gateway event.
Returns an object with one 'pruned' key indicating the number of members that would be removed in a prune operation. Requires the 'KICK_MEMBERS' permission.Query String Params
Field | Type | Description |
---|
days | integer | number of days to count prune for (1 or more) |
Begin a prune operation. Requires the 'KICK_MEMBERS' permission. Returns an object with one 'pruned' key indicating the number of members that were removed in the prune operation. Fires multiple Guild Member Remove Gateway events.Query String Params
Field | Type | Description |
---|
days | integer | number of days to prune (1 or more) |
Get Guild Voice Regions
GET/guilds/{guild.id}/regions
Returns a list of voice region objects for the guild. Unlike the similar /voice
route, this returns VIP servers when the guild is VIP-enabled.
Returns a list of invite objects (with invite metadata) for the guild. Requires the 'MANAGE_GUILD' permission.Get Guild Integrations
GET/guilds/{guild.id}/integrations
Returns a list of integration objects for the guild. Requires the 'MANAGE_GUILD' permission.Create Guild Integration
POST/guilds/{guild.id}/integrations
Attach an integration object from the current user to the guild. Requires the 'MANAGE_GUILD' permission. Returns a 204 empty response on success. Fires a Guild Integrations Update Gateway event.JSON Params
Field | Type | Description |
---|
type | string | the integration type |
id | snowflake | the integration id |
Modify the behavior and settings of a integration object for the guild. Requires the 'MANAGE_GUILD' permission. Returns a 204 empty response on success. Fires a Guild Integrations Update Gateway event.JSON Params
Field | Type | Description |
---|
expire_behavior | integer | the behavior when an integration subscription lapses (see the integration object documentation) |
expire_grace_period | integer | period (in seconds) where the integration will ignore lapsed subscriptions |
enable_emoticons | bool | whether emoticons should be synced for this integration (twitch only currently) |
Delete the attached integration object for the guild. Requires the 'MANAGE_GUILD' permission. Returns a 204 empty response on success. Fires a Guild Integrations Update Gateway event.
Sync an integration. Requires the 'MANAGE_GUILD' permission. Returns a 204 empty response on success.
Returns the guild embed object. Requires the 'MANAGE_GUILD' permission.
Modify a guild embed object for the guild. All attributes may be passed in with JSON and modified. Requires the 'MANAGE_GUILD' permission. Returns the updated guild embed object.Get Guild Vanity URL
GET/guilds/{guild.id}/vanity-url
Returns a partial invite object for guilds with that feature enabled. Requires the 'MANAGE_GUILD' permission.Example Partial Invite Object
{
"code": "abc"
}