Invites
An invite is a code that lets an account join a guild or a group direct message. A guild can also have one custom invite URL.
Invite object
Section titled “Invite object”Structure
Section titled “Structure”| Field | Type | Description |
|---|---|---|
| code | string | The unique code of the invite |
| type | integer | Invite type |
| guild? | partial guild object | The guild the invite joins |
| channel? | partial invite channel object | The channel the invite targets |
| inviter1 | ?partial user object | The account that created the invite |
| member_count? | integer | The member count of the guild, or the recipient count of the group direct message |
| presence_count? | integer | The online member count of the guild |
| expires_at | ?ISO8601 timestamp | When the invite stops working, or null when it never expires |
| temporary2 | boolean | Whether joining through this invite gives temporary membership |
1 Null for a custom invite URL
2 Has no effect on a group direct message invite
A guild invite has guild, channel, member_count and presence_count. A group direct message invite has channel and member_count.
Example
Section titled “Example”{ "code": "aB3dEf7h", "type": 0, "guild": {"id": "1489002177550843904", "name": "Example guild"}, "channel": {"id": "1489002177550843905", "name": "general", "type": 0}, "inviter": {"id": "1501314428688998182", "username": "example"}, "member_count": 412, "presence_count": 87, "expires_at": null, "temporary": false}Invite types
Section titled “Invite types”| Value | Name | Description |
|---|---|---|
| 0 | GUILD | Joins a guild |
| 1 | GROUP_DM | Joins a group direct message |
Invite metadata object
Section titled “Invite metadata object”The metadata object extends the invite object with creation and usage details. Create channel invite, List channel invites and List guild invites return it.
Structure
Section titled “Structure”| Field | Type | Description |
|---|---|---|
| created_at | ISO8601 timestamp | When the invite was created |
| uses | integer | How many accounts joined through the invite |
| max_uses | integer | The maximum number of joins, where 0 is unlimited |
| max_age? | integer | The lifetime in seconds, where 0 never expires. Only when type is 0 |
Partial invite channel object
Section titled “Partial invite channel object”The channel field of an invite object.
Structure
Section titled “Structure”| Field | Type | Description |
|---|---|---|
| id | snowflake | The ID of the channel |
| name | ?string | The name of the channel |
| type | integer | Channel type |
| recipients?1 | array[partial invite recipient object] | The accounts in the group direct message |
1 Only on a group direct message invite
Partial invite recipient object
Section titled “Partial invite recipient object”An entry in recipients on a group direct message invite.
Structure
Section titled “Structure”| Field | Type | Description |
|---|---|---|
| username | string | The username of the recipient |
Custom invite URLs
Section titled “Custom invite URLs”A custom invite URL is a guild invite with a code you choose. It has no inviter, no expiry and no use limit. Its code is case-insensitive, and clearing or replacing it stops the old link from working right away. List channel invites and List guild invites leave it out, and Delete invite returns UNKNOWN_INVITE for it. To read the code, use Get guild custom invite URL.
Get invite
Section titled “Get invite”GET/v1/invites/{invite_code}Returns an invite object without using up the invite. Codes from Create channel invite are case-sensitive.
Path parameters
Section titled “Path parameters”| Field | Type | Description |
|---|---|---|
| invite_code | string | The invite code (1-256 characters) |
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 200 | invite object | The invite was returned |
| 404 | error response | UNKNOWN_INVITE, UNKNOWN_CHANNEL or UNKNOWN_GUILD when the invite or its target is gone |
The rate limit is 100 requests per 10 seconds, on the invite:read::invite_code bucket.
Accept invite
Section titled “Accept invite”POST/v1/invites/{invite_code}Joins the authenticated account to the target of the invite and returns an invite object. Each new join counts as one use, and the invite is deleted after max_uses joins. An account that is already in the target gets a 200 and no use is counted, unless the guild has paused invites or disabled INSTANT_INVITES.
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 200 | invite object | The account joined or was already in the target |
| 400 | error response | TEMPORARY_INVITE_REQUIRES_PRESENCE when a temporary invite is accepted with no active presence |
| 400 | error response | UNCLAIMED_ACCOUNT_CANNOT_JOIN_GROUP_DMS when an unclaimed account joins a group direct message |
| 400 | error response | INVALID_CHANNEL_TYPE when a type 1 invite targets a private channel that is not a group direct message |
| 400 | error response | MAX_GUILDS when the account is in the maximum number of guilds |
| 400 | error response | MAX_GUILD_MEMBERS or MAX_GROUP_DM_RECIPIENTS when the target is full |
| 403 | error response | NSFW_CONTENT_AGE_RESTRICTED when the guild or channel is age restricted and the age check fails |
| 403 | error response | INVITES_DISABLED when the guild has paused invites |
| 403 | error response | FEATURE_TEMPORARILY_DISABLED when INSTANT_INVITES is set in the guild's disabled operations |
| 403 | error response | USER_BANNED_FROM_GUILD or USER_IP_BANNED_FROM_GUILD when the account or its network address is banned |
| 403 | error response | ACCOUNT_LIMITED when the account is limited and not already in the target |
| 404 | error response | UNKNOWN_INVITE when the code is unknown or used up, UNKNOWN_GUILD or UNKNOWN_CHANNEL when the target is gone |
A guild join sends Guild Create and Guild Member Add, and a group direct message join sends Channel Create and Channel Recipient Add.
The rate limit is 10 requests per 10 seconds, on the invite:accept bucket.
Visit invite guild
Section titled “Visit invite guild”POST/v1/invites/{invite_code}/visitStarts a visit to the guild of a guild invite and returns a guild visit start object. Only user accounts can call it, and a user account without the guild_visits experiment assignment gets UNKNOWN_INVITE. A visit doesn't count as a use, and the visit ends when the invite is deleted or expires. Sessions with the GUILD_VISITS session flag get Guild Create with visiting: true.
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 200 | guild visit start object | The visit started or was already open, or the caller is a member |
| 403 | error response | GUILD_VISITS_DISABLED when the guild does not accept visitors |
| 403 | error response | GUILD_VISIT_AGE_RESTRICTED when the guild is for adults and the caller may not see it |
| 403 | error response | INVITES_DISABLED when the guild has paused invites |
| 403 | error response | FEATURE_TEMPORARILY_DISABLED when INSTANT_INVITES is set in the guild's disabled operations |
| 403 | error response | USER_BANNED_FROM_GUILD or USER_IP_BANNED_FROM_GUILD when the caller is banned |
| 403 | error response | ACCOUNT_LIMITED when the account is limited |
| 403 | error response | DATE_OF_BIRTH_REQUIRED or ACCOUNT_BELOW_MINIMUM_AGE when the age check fails |
| 404 | error response | UNKNOWN_INVITE or UNKNOWN_GUILD when the invite or guild is unavailable |
The rate limit is 10 requests per 60 seconds, on the guild:visit:start bucket. Each IP address can also start 30 visits per 60 seconds.
Delete invite
Section titled “Delete invite”DELETE/v1/invites/{invite_code}Deletes an invite. For a guild invite, the creator can delete it and anyone else needs MANAGE_GUILD. For a group direct message invite, you need to own the group. Sends Invite Delete, and a guild invite also records an INVITE_DELETE audit action.
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 204 | empty | The invite was deleted |
| 400 | error response | TWO_FACTOR_REQUIRED when the guild needs multi-factor authentication you lack |
| 404 | error response | UNKNOWN_INVITE when the code is unknown or is the guild's custom invite URL |
The rate limit is 20 requests per 10 seconds, on the invite:delete::invite_code bucket.
Create channel invite
Section titled “Create channel invite”POST/v1/channels/{channel_id}/invitesCreates an invite for a channel and returns an invite metadata object. A guild channel needs VIEW_CHANNEL and CREATE_INSTANT_INVITE, and a private channel needs you to be a recipient. Sends Invite Create for a new invite, and a guild invite also records an INVITE_CREATE audit action.
A guild channel makes a guild invite, and a group direct message makes a group direct message invite.
JSON body
Section titled “JSON body”| Field | Type | Description |
|---|---|---|
| max_uses? | ?integer | The maximum number of joins (0-100, default 0 for unlimited) |
| max_age? | ?integer | The lifetime in seconds (0-604800, default 0 for never) |
| unique? | ?boolean | Whether to always make a new invite (default false)1 |
| temporary? | ?boolean | Whether joining gives temporary membership (default false)2 |
1 When false, an existing invite with the same creator, channel, max_uses, max_age and temporary is returned
2 Has no effect on a private channel
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 200 | invite metadata object | The invite was created or an existing one was returned |
| 400 | error response | MAX_INVITES when the guild has max_guild_invites invites (default 1,000), counting its custom invite URL |
| 400 | error response | INVALID_CHANNEL_TYPE when the channel is a thread, forum channel or media channel |
| 403 | error response | FEATURE_TEMPORARILY_DISABLED when instant invites are paused for the guild |
| 403 | error response | NSFW_CONTENT_AGE_RESTRICTED when the guild or channel is age restricted and the age check fails |
The rate limit is 20 requests per minute, on the invite:create::channel_id bucket.
List channel invites
Section titled “List channel invites”GET/v1/channels/{channel_id}/invitesReturns the channel's invite metadata objects, newest first, with no pagination. A guild channel needs VIEW_CHANNEL and MANAGE_CHANNELS, and a group direct message needs you to own it.
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 200 | array[invite metadata object] | The invites were returned |
| 400 | error response | TWO_FACTOR_REQUIRED when the guild needs multi-factor authentication you lack |
| 403 | error response | NSFW_CONTENT_AGE_RESTRICTED when the guild or channel is age restricted and the age check fails |
The rate limit is 40 requests per 10 seconds, on the invite:list::channel_id bucket.
List guild invites
Section titled “List guild invites”GET/v1/guilds/{guild_id}/invitesReturns the invite metadata objects for every channel in the guild, newest first, with no pagination. You need MANAGE_GUILD.
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 200 | array[invite metadata object] | The invites were returned |
| 400 | error response | TWO_FACTOR_REQUIRED when the guild needs multi-factor authentication you lack |
The rate limit is 40 requests per 10 seconds, on the invite:list::guild_id bucket.