Invite Resource

Invites are used by users to join a guild or group DM, or to add a user to their friends list.

Temporary Invites

Temporary invites (indicated by the temporary field) grant non-permanent access to a guild. Upon accepting a temporary invite, the user is added to the guild and can interact with it unconditionally until all of their sessions are disconnected. If the user does not have an active session at the time of accepting the invite, they will be removed after the next time they disconnect.

Guest Invites

Guest invites (indicated by the flags field), similar to temporary invites, also grant non-permanent access to a guild. However, unlike temporary invites, upon accepting a guest invite, the user does not become a member of the guild. The session ID provided during acceptance is dispatched a Guild Create event containing only the channel the invite was for, and the user receives no other guild-specific events (except for Guild Delete when they are removed). Guest access only allows using a subset of endpoints required for interacting with voice channels, and access is removed after the user disconnects from the voice channel.

Invite Object

A code that when used, adds a user to a guild or group DM channel, or creates a relationship between two users.

Invite Structure

Field	Type	Description
code	string	The invite code (unique ID)
type	integer	The type of invite
channel	?partial channel object	The channel this invite is for; `null` for friend invites that did not have a DM channel created
guild_id?	snowflake	The ID of the guild this invite is for
guild?	invite guild object	The guild this invite is for
inviter?	partial user object	The user who created the invite
flags?	integer	The invite's flags
target_type?	integer	The type of target for this guild invite
target_user?	partial user object	The user whose stream to display for this voice channel stream invite
target_application?	partial application object	The embedded application to open for this voice channel embedded application invite
approximate_member_count? ¹	integer	Approximate count of total members in the guild or group DM
approximate_presence_count? ¹	integer	Approximate count of non-offline members in the guild
expires_at	?ISO8601 timestamp	The expiry date of the invite, if it expires
stage_instance?	invite stage instance object	Stage instance data if there is a public stage instance in the stage channel this invite is for
guild_scheduled_event?	guild scheduled event object	Guild scheduled event data, only included if `guild_scheduled_event_id` contains a valid guild scheduled event ID
new_member? ²	boolean	Whether the user is a new member of the guild
show_verification_form? ²	boolean	Whether the user should be shown the joined guild's member verification form

¹ Only included when fetched from the Get Invite endpoint with with_counts set to true.

² Only included when fetched from the Accept Invite endpoint.

Invite Type

Value	Name	Description
0	GUILD	Joins the user to a guild
1	GROUP_DM	Joins the user to a group DM
2	FRIEND	Adds the user as a friend to the inviter

Invite Target Type

Value	Name	Description
1	STREAM	The invite is for a stream in a voice channel
2	EMBEDDED_APPLICATION	The invite is for an embedded application (activity) in a voice channel
3	ROLE_SUBSCRIPTIONS ¹	The invite redirects to the role subscriptions page within a guild
4	CREATOR_PAGE ¹	The invite originates from the creator page of a guild

¹ Invites with these target types are not returned in the Get Guild Invites and Get Channel Invites endpoints. They are also not deletable through Delete Invite.

Invite Flags

Value	Name	Description
1 << 0	GUEST	The invite grants one-time access to a voice channel in the guild
1 << 1	VIEWED	The invite has been viewed by any user (has been retrieved using Get Invite)

Example Invite Object

{
  "type": 0,
  "code": "jvuBeT38",
  "inviter": {
    "id": "852892297661906993",
    "username": "alien",
    "avatar": "05145cc5646fbcba277b6d5ea2030610",
    "discriminator": "0",
    "public_flags": 4194432,
    "banner": null,
    "accent_color": null,
    "global_name": "Alien",
    "avatar_decoration_data": null
  },
  "expires_at": "2023-07-22T18:30:11+00:00",
  "guild": {
    "id": "1046920999469330512",
    "name": "Alien Network",
    "splash": "b40e61f7730b8781b9a551964570e0cc",
    "banner": "a_98d07f130569f17e8352df80c3a2bc2b",
    "description": "Where the 👽s 👽 and sometimes very 👽 things happen 😨.",
    "icon": "66b0f4d96c145970fa9d96ada8afadf3",
    "features": [],
    "verification_level": 2,
    "vanity_url_code": "alien",
    "premium_subscription_count": 14,
    "nsfw": false,
    "nsfw_level": 0
  },
  "guild_id": "1046920999469330512",
  "channel": {
    "id": "1057241425793798144",
    "type": 2,
    "name": "alien noises"
  },
  "target_type": 2,
  "target_application": {
    "id": "880218394199220334",
    "name": "Watch Together",
    "icon": "ec48acbad4c32efab4275cb9f3ca3a58",
    "description": "Create and watch a playlist of YouTube videos with your friends. Your choice to share the remote or not. ",
    "type": null,
    "cover_image": "3cc9446876ae9eec6e06ff565703c292",
    "bot": {
      "id": "880218394199220334",
      "username": "Watch Together",
      "avatar": "fe2b7fa334817b0346d57416ad75e93b",
      "discriminator": "5319",
      "public_flags": 0,
      "bot": true,
      "banner": null,
      "accent_color": null,
      "global_name": null,
      "avatar_decoration_data": null
    },
    "summary": "",
    "bot_public": false,
    "bot_require_code_grant": false,
    "terms_of_service_url": "https://discord.com/terms",
    "privacy_policy_url": "https://discord.com/privacy",
    "verify_key": "e2aaf50fbe2fd9d025ac669035f5efb89099931690fba9dc28efb7eaade7f96d",
    "flags": 1179648,
    "max_participants": -1,
    "tags": ["Video Player", "Watch"],
    "hook": true,
    "is_monetized": false,
    "embedded_activity_config": {
      "activity_preview_video_asset_id": "1104184163201990836",
      "supported_platforms": ["web", "ios", "android"],
      "default_orientation_lock_state": 2,
      "tablet_default_orientation_lock_state": 1,
      "requires_age_gate": false,
      "premium_tier_requirement": null,
      "free_period_starts_at": null,
      "free_period_ends_at": null,
      "client_platform_config": {
        "ios": { "label_type": 0, "label_until": null, "release_phase": "global_launch" },
        "android": { "label_type": 0, "label_until": null, "release_phase": "global_launch" },
        "web": { "label_type": 0, "label_until": null, "release_phase": "global_launch" }
      },
      "shelf_rank": 3,
      "has_csp_exception": false,
      "displays_advertisements": false
    }
  },
  "approximate_member_count": 100,
  "approximate_presence_count": 99
}

Invite Metadata Object

Extra information about an invite, will extend the invite object.

Invite Metadata Structure

Field	Type	Description
uses? ¹	integer	Number of times this invite has been used
max_uses? ¹	integer	Max number of times this invite can be used
max_age?	integer	Duration (in seconds) after which the invite expires (default 0)
temporary? ²	boolean	Whether this invite only grants temporary membership (default false for unsupported invite types)
created_at	ISO8601 timestamp	When this invite was created

¹ This information is not tracked or returned for group DM invites. However, they always have a max_uses of 0.

² Temporary invites are only supported for guilds.

Example Invite with Metadata Object

{
  "type": 0,
  "code": "jvuBeT38",
  "inviter": {
    "id": "852892297661906993",
    "username": "alien",
    "avatar": "05145cc5646fbcba277b6d5ea2030610",
    "discriminator": "0",
    "public_flags": 4194432,
    "banner": null,
    "accent_color": null,
    "global_name": "Alien",
    "avatar_decoration_data": null
  },
  "max_age": 604800,
  "created_at": "2023-07-15T18:30:11.047000+00:00",
  "expires_at": "2023-07-22T18:30:11+00:00",
  "guild": {
    "id": "1046920999469330512",
    "name": "Alien Network",
    "splash": "b40e61f7730b8781b9a551964570e0cc",
    "banner": "a_98d07f130569f17e8352df80c3a2bc2b",
    "description": "Where the 👽s 👽 and sometimes very 👽 things happen 😨.",
    "icon": "66b0f4d96c145970fa9d96ada8afadf3",
    "features": [],
    "verification_level": 2,
    "vanity_url_code": "alien",
    "premium_subscription_count": 14,
    "nsfw": false,
    "nsfw_level": 0
  },
  "guild_id": "1046920999469330512",
  "channel": {
    "id": "1057241425793798144",
    "type": 2,
    "name": "alien noises"
  },
  "uses": 0,
  "max_uses": 0,
  "temporary": false
}

Invite Guild Object

The guild an invite is for.

Invite Guild Structure

Field	Type	Description
id	snowflake	The ID of the guild
name	string	The name of the guild (2-100 characters)
icon	?string	The guild's icon hash
description	?string	The description for the guild
banner	?string	The guild's banner hash
splash	?string	The guild's splash hash
verification_level	integer	The verification level required for the guild
features	array[string]	Enabled guild features
vanity_url_code	?string	The guild's vanity invite code
premium_subscription_count?	integer	The number of premium subscriptions (boosts) the guild currently has
nsfw (deprecated)	boolean	Whether the guild is considered NSFW (`EXPLICIT` or `AGE_RESTRICTED`)
nsfw_level	integer	The guild's NSFW level

Invite Stage Instance Object

A stage instance attached to an invite.

Invite Stage Instance Structure

Field	Type	Description
members	array[partial guild member object]	The members speaking in the stage
participant_count	integer	The number of users in the stage
speaker_count	integer	The number of users speaking in the stage
topic	string	The topic of the stage instance (1-120 characters)

Example Invite Stage Instance

{
  "topic": "The debate is over: diet is better than regular",
  "participant_count": 200,
  "speaker_count": 5,
  "members": [
    {
      "avatar": null,
      "communication_disabled_until": null,
      "flags": 0,
      "joined_at": "2022-10-11T12:31:03.882000+00:00",
      "nick": ":~]",
      "pending": false,
      "premium_since": null,
      "roles": ["1040221495437299782"],
      "user": {
        "id": "863406480111566858",
        "username": "leaduck",
        "global_name": "LeaDuck",
        "avatar": "bb450561133bac3da5c7e201db40af6c",
        "discriminator": "0",
        "public_flags": 256,
        "avatar_decoration_data": null
      }
    }
  ]
}

Endpoints

Get Invite

GET/invites/{invite.code}

Unauthenticated

Returns an invite object for the given code.

Query String Params

Field	Type	Description
with_counts?	boolean	Whether the invite should contain approximate member counts (and partial recipients for group DM invites) (default false)
guild_scheduled_event_id?	snowflake	The guild scheduled event to include with the invite

Accept Invite

POST/invites/{invite.code}

OAuth2

Accepts an invite to a guild, group DM, or DM. Returns an invite object on success. May fire a Guild Create, Guild Member Add, Guild Join Request Create, Channel Create, and/or Relationship Add Gateway event.

JSON Params

Field	Type	Description
session_id?	string	The session ID that is accepting the invite, required for guest invites

Delete Invite

DELETE/invites/{invite.code}

Audit Log Reason

Deletes an invite. Requires the MANAGE_CHANNELS permission on the channel this invite belongs to, or MANAGE_GUILD to remove any invite across the guild, if the invite is to a guild. Returns an invite object on success. May fire an Invite Delete Gateway event.

Get Guild Invites

GET/guilds/{guild.id}/invites

Returns a list of invite objects (with invite metadata) for the guild. Requires the MANAGE_GUILD permission.

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 and group DMs. Requires the MANAGE_CHANNELS permission if the channel is in a guild.

Create Channel Invite

POST/channels/{channel.id}/invites

Audit Log Reason

Creates a new invite object for the channel. Only usable for guild channels and group DMs. Requires the CREATE_INSTANT_INVITE permission if the channel is in a guild. Returns an invite object (with invite metadata). Fires an Invite Create Gateway event if the channel is in a guild.

JSON Params

Field	Type	Description
flags?	integer	The invite's flags (only `GUEST` can be set)
max_age? ¹	integer	Number of seconds before expiry, or 0 for never (0-604800, default 86400)
max_uses?	integer	Max number of uses or 0 for unlimited (0-100, default 0)
temporary?	boolean	Whether this invite only grants temporary membership (default false)
unique?	boolean	Whether to try to reuse a similar invite (useful for creating many unique one time use invites, default false)
validate?	?string	The invite code to validate and attempt to reuse; if nonexistant, a new invite will be created as usual
target_type?	integer	The type of target for this voice channel invite
target_user_id?	snowflake	The ID of the user whose stream to display for this invite, required if `target_type` is `STREAM`, the user must be streaming in the channel
target_application_id?	snowflake	The ID of the embedded application to open for this invite, required if `target_type` is `EMBEDDED_APPLICATION`, the application must have the `EMBEDDED` flag

¹ For group DMs, only max_age is supported, and it does not support 0.

Field	Type	Description
code?	string	The pre-generated friend invite code to create an invite from

Revoke User Invites

DELETE/users/@me/invites

Revokes all of the current user's friend invites. Returns a list of revoked friend invite objects (with invite metadata on success.

Invite Resource

Temporary Invites

Guest Invites

Invite Object

Invite Structure

Invite Type

Invite Target Type

Invite Flags

Example Invite Object

Invite Metadata Object

Invite Metadata Structure

Example Invite with Metadata Object

Invite Guild Object

Invite Guild Structure

Invite Stage Instance Object

Invite Stage Instance Structure

Example Invite Stage Instance

Endpoints

Get Invite

Query String Params

Accept Invite

JSON Params

Delete Invite

Get Guild Invites

Get Channel Invites

Create Channel Invite

JSON Params

Get User Invites

Create User Invite

JSON Params

Revoke User Invites