Invites

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

¹ Only included when fetched from the Get Invite endpoint with with_counts set to true. Also included when fetched from the Accept Invite endpoint on non-previewable guilds.

² Only included when fetched from the Accept Invite endpoint. Note that new_member is erroneously set to true for non-guild invites and is missing when accepting an invite to a non-previewable guild.

³ Only included when fetched from the Get Invite endpoint with with_permissions set to true.

⁴ Only included when fetched from the Get Guild Invites endpoint.

⁵ Partial role objects contain id, name, position, color, colors, icon, and unicode_emoji

Invite Type

Invite Target Type

¹ 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

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,
    "primary_guild": 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,
    "is_monetized": false,
    "is_verified": false,
    "is_discoverable": false,
    "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,
      "primary_guild": 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,
    "storefront_available": 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,
      "legacy_responsive_aspect_ratio": 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,
  "is_nickname_changeable": true
}

Invite Metadata Object

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

Invite Metadata Structure

¹ 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,
    "primary_guild": 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",
    "nsfw_level": 0,
    "nsfw": false,
    "premium_subscription_count": 14,
    "premium_tier": 3
  },
  "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

Invite Target Users Job Object

The status of the target users file processing job for an invite.

Invite Target Users Job Structure

Invite Target Users Job Status

Endpoints

Returns an invite object for the given code.

Query String Params

Returns the user IDs of friends in the target guild. Always returns an empty array for group DMs and friend invites.

Response Body

Returns the IDs of the users allowed to see and accept the given invite. Invite must have a target users file associated with it. Requires the MANAGE_GUILD or VIEW_AUDIT_LOG permission if the requestor is not the inviter. Return a CSV file with the header user_id and each user ID passed to invite create on its own line.

Replaces the target users file associated with the given invite. Processing is done asynchronously. Invite must have been created with a target users file. Requires the MANAGE_GUILD permission if the requestor is not the inviter. Returns a 204 empty response on success.

Form Params

¹ See Uploading Files for details.

Returns an invite target users job object for the given invite. Invite must have a target users file associated with it. Requires the MANAGE_GUILD or VIEW_AUDIT_LOG permission if the requestor is not the inviter.

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

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.

Returns a list of invite objects for the guild. Requires the MANAGE_GUILD or VIEW_AUDIT_LOG permission. Invite metadata is included if the user has the MANAGE_GUILD permission.

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.

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/Form Params

¹ Creating an invite with the APPLICATION_BYPASS flag requires the KICK_MEMBERS permission.

² For group DMs, max_age is the only supported parameter, and it accepts a value from 1 to 604800 (7 days).

³ Processing is done asynchronously. See Uploading Files for details.

⁴ Requires the MANAGE_ROLES permission. Cannot grant roles that are equal to or higher than the creator's highest role.

Returns a list of friend invite objects (with invite metadata) for the current user.

Creates a new friend invite. Returns a friend invite object (with invite metadata) on success.

JSON Params

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