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_id	snowflake	id of owner
region	string	{voice_region.id}
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	level of verification required for the guild
default_message_notifications	integer	default message notifications level
explicit_content_filter	integer	default 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
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": "SEkgTU9NIElUUyBBTkRSRUkhISEhISEh",
    "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	array of role object id's
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.

JSON Params

Field	Type	Description
name	string	name of the guild (2-100 characters)
region	string	{voice_region.id} for voice
icon	string	base64 128x128 jpeg image for the guild icon
verification_level	integer	guild verification level
default_message_notifications	integer	default message notifications setting
roles	array of role objects	new guild roles
channels	array of partial channel objects	new guild's channels

Example Partial Channel Object

{
    "name": "naming-things-is-hard",
    "type": 0
}

Returns the guild object for the given id. Modify a guild's settings. Returns the updated guild object on success. Fires a Guild Update Gateway event.

JSON Params

Field	Type	Description
name	string	guild name
region	string	guild {voice_region.id}
verification_level	integer	guild verification level
default_message_notifications	integer	default message notifications setting
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)

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 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.

JSON Params

Field	Type	Description
name	string	channel name (2-100 characters)
type	string	"voice" or "text"
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

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.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.

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.

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	array of roles 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.

JSON Params

Field	Type	Description	Permission
nick	string	value to set users nickname to	MANAGE_NICKNAMES
roles	array	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

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)

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. Requires the 'MANAGE_ROLES' permission. 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 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)

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. Returns a list of integration objects for the guild. Requires the 'MANAGE_GUILD' permission. 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.