A free and open source instant messaging and VoIP chat app built for friends, groups, and communities.
---
# SPDX-License-Identifier: AGPL-3.0-or-later
title: Invites
description: Invite objects and the routes for getting, accepting, creating, listing and deleting invites.
---
import RouteHeader from '@/components/RouteHeader.astro';
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](#custom-invite-urls).
## Invite object
### Structure
| Field | Type | Description |
| --- | --- | --- |
| code | string | The unique code of the invite |
| type | integer | [Invite type](#invite-types) |
| guild? | [partial guild](/http-api/guilds/#partial-guild-object) object | The guild the invite joins |
| channel? | [partial invite channel](#partial-invite-channel-object) object | The channel the invite targets |
| inviter<sup>1</sup> | ?[partial user](/http-api/users/#partial-user-object) 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 |
| temporary<sup>2</sup> | boolean | Whether joining through this invite gives temporary membership |
<sup>1</sup> Null for a custom invite URL
<sup>2</sup> 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
```json
{
"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
| Value | Name | Description |
| --- | --- | --- |
| 0 | GUILD | Joins a guild |
| 1 | GROUP_DM | Joins a group direct message |
## Invite metadata object
The metadata object extends the [invite object](#invite-object) with creation and usage details. [Create channel invite](#create-channel-invite), [List channel invites](#list-channel-invites) and [List guild invites](#list-guild-invites) return it.
### 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
The `channel` field of an [invite object](#invite-object).
### Structure
| Field | Type | Description |
| --- | --- | --- |
| id | snowflake | The ID of the channel |
| name | ?string | The name of the channel |
| type | integer | [Channel type](/http-api/channels/#channel-types) |
| recipients?<sup>1</sup> | array[[partial invite recipient](#partial-invite-recipient-object) object] | The accounts in the group direct message |
<sup>1</sup> Only on a group direct message invite
## Partial invite recipient object
An entry in `recipients` on a group direct message invite.
### Structure
| Field | Type | Description |
| --- | --- | --- |
| username | string | The username of the recipient |
## 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](#list-channel-invites) and [List guild invites](#list-guild-invites) leave it out, and [Delete invite](#delete-invite) returns `UNKNOWN_INVITE` for it. To read the code, use [Get guild custom invite URL](/http-api/guilds/#get-guild-custom-invite-url).
## Get invite
<RouteHeader method="GET" path="/v1/invites/{invite_code}" unauthenticated />
Returns an [invite object](#invite-object) without using up the invite. Codes from [Create channel invite](#create-channel-invite) are case-sensitive.
### Path parameters
| Field | Type | Description |
| --- | --- | --- |
| invite_code | string | The invite code (1-256 characters) |
### Response
| Status | Body | Condition |
| --- | --- | --- |
| 200 | [invite](#invite-object) object | The invite was returned |
| 404 | [error response](/http-api/#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
<RouteHeader method="POST" path="/v1/invites/{invite_code}" />
Joins the authenticated account to the target of the invite and returns an [invite object](#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
| Status | Body | Condition |
| --- | --- | --- |
| 200 | [invite](#invite-object) object | The account joined or was already in the target |
| 400 | [error response](/http-api/#error-response) | `TEMPORARY_INVITE_REQUIRES_PRESENCE` when a temporary invite is accepted with no active presence |
| 400 | [error response](/http-api/#error-response) | `UNCLAIMED_ACCOUNT_CANNOT_JOIN_GROUP_DMS` when an unclaimed account joins a group direct message |
| 400 | [error response](/http-api/#error-response) | `INVALID_CHANNEL_TYPE` when a type `1` invite targets a private channel that is not a group direct message |
| 400 | [error response](/http-api/#error-response) | `MAX_GUILDS` when the account is in the maximum number of guilds |
| 400 | [error response](/http-api/#error-response) | `MAX_GUILD_MEMBERS` or `MAX_GROUP_DM_RECIPIENTS` when the target is full |
| 403 | [error response](/http-api/#error-response) | `NSFW_CONTENT_AGE_RESTRICTED` when the guild or channel is age restricted and the age check fails |
| 403 | [error response](/http-api/#error-response) | `INVITES_DISABLED` when the guild has paused invites |
| 403 | [error response](/http-api/#error-response) | `FEATURE_TEMPORARILY_DISABLED` when `INSTANT_INVITES` is set in the guild's [disabled operations](/http-api/guilds/#disabled-guild-operations) |
| 403 | [error response](/http-api/#error-response) | `USER_BANNED_FROM_GUILD` or `USER_IP_BANNED_FROM_GUILD` when the account or its network address is banned |
| 403 | [error response](/http-api/#error-response) | `ACCOUNT_LIMITED` when the account is [limited](/http-api/users/#account-limitation) and not already in the target |
| 404 | [error response](/http-api/#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](/gateway/events/#guild-create) and [Guild Member Add](/gateway/events/#guild-member-add), and a group direct message join sends [Channel Create](/gateway/events/#channel-create) and [Channel Recipient Add](/gateway/events/#channel-recipient-add).
The rate limit is 10 requests per 10 seconds, on the `invite:accept` bucket.
## Visit invite guild
<RouteHeader method="POST" path="/v1/invites/{invite_code}/visit" />
Starts a [visit](/http-api/guilds/#visiting-guilds) to the guild of a guild invite and returns a [guild visit start object](/http-api/guilds/#guild-visit-start-object). Only user accounts can call it, and a user account without the `guild_visits` [experiment assignment](/http-api/experiments/#guild-visits-assignment-object) 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](/gateway/commands/#session-flags) get [Guild Create](/gateway/events/#guild-create) with `visiting: true`.
### Response
| Status | Body | Condition |
| --- | --- | --- |
| 200 | [guild visit start](/http-api/guilds/#guild-visit-start-object) object | The visit started or was already open, or the caller is a member |
| 403 | [error response](/http-api/#error-response) | `GUILD_VISITS_DISABLED` when the guild does not accept visitors |
| 403 | [error response](/http-api/#error-response) | `GUILD_VISIT_AGE_RESTRICTED` when the guild is for adults and the caller may not see it |
| 403 | [error response](/http-api/#error-response) | `INVITES_DISABLED` when the guild has paused invites |
| 403 | [error response](/http-api/#error-response) | `FEATURE_TEMPORARILY_DISABLED` when `INSTANT_INVITES` is set in the guild's [disabled operations](/http-api/guilds/#disabled-guild-operations) |
| 403 | [error response](/http-api/#error-response) | `USER_BANNED_FROM_GUILD` or `USER_IP_BANNED_FROM_GUILD` when the caller is banned |
| 403 | [error response](/http-api/#error-response) | `ACCOUNT_LIMITED` when the account is [limited](/http-api/users/#account-limitation) |
| 403 | [error response](/http-api/#error-response) | `DATE_OF_BIRTH_REQUIRED` or `ACCOUNT_BELOW_MINIMUM_AGE` when the age check fails |
| 404 | [error response](/http-api/#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
<RouteHeader method="DELETE" path="/v1/invites/{invite_code}" bot auditReason mfa />
Deletes an invite. For a guild invite, the creator can delete it and anyone else needs [MANAGE_GUILD](/http-api/permissions/). For a group direct message invite, you need to own the group. Sends [Invite Delete](/gateway/events/#invite-delete), and a guild invite also records an [INVITE_DELETE audit action](/http-api/guild-audit-logs/#audit-actions).
### Response
| Status | Body | Condition |
| --- | --- | --- |
| 204 | empty | The invite was deleted |
| 400 | [error response](/http-api/#error-response) | `TWO_FACTOR_REQUIRED` when the guild needs [multi-factor authentication](/http-api/guilds/#mfa-levels) you lack |
| 404 | [error response](/http-api/#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
<RouteHeader method="POST" path="/v1/channels/{channel_id}/invites" bot auditReason />
Creates an invite for a channel and returns an [invite metadata object](#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](/gateway/events/#invite-create) for a new invite, and a guild invite also records an [INVITE_CREATE audit action](/http-api/guild-audit-logs/#audit-actions).
A guild channel makes a guild invite, and a group direct message makes a group direct message invite.
### 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)<sup>1</sup> |
| temporary? | ?boolean | Whether joining gives temporary membership (default false)<sup>2</sup> |
<sup>1</sup> When false, an existing invite with the same creator, channel, `max_uses`, `max_age` and `temporary` is returned
<sup>2</sup> Has no effect on a private channel
### Response
| Status | Body | Condition |
| --- | --- | --- |
| 200 | [invite metadata](#invite-metadata-object) object | The invite was created or an existing one was returned |
| 400 | [error response](/http-api/#error-response) | `MAX_INVITES` when the guild has `max_guild_invites` invites (default 1,000), counting its custom invite URL |
| 400 | [error response](/http-api/#error-response) | `INVALID_CHANNEL_TYPE` when the channel is a thread, forum channel or media channel |
| 403 | [error response](/http-api/#error-response) | `FEATURE_TEMPORARILY_DISABLED` when instant invites are paused for the guild |
| 403 | [error response](/http-api/#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
<RouteHeader method="GET" path="/v1/channels/{channel_id}/invites" bot mfa />
Returns the channel's [invite metadata objects](#invite-metadata-object), 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
| Status | Body | Condition |
| --- | --- | --- |
| 200 | array[[invite metadata](#invite-metadata-object) object] | The invites were returned |
| 400 | [error response](/http-api/#error-response) | `TWO_FACTOR_REQUIRED` when the guild needs [multi-factor authentication](/http-api/guilds/#mfa-levels) you lack |
| 403 | [error response](/http-api/#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
<RouteHeader method="GET" path="/v1/guilds/{guild_id}/invites" bot mfa />
Returns the [invite metadata objects](#invite-metadata-object) for every channel in the guild, newest first, with no pagination. You need [MANAGE_GUILD](/http-api/permissions/).
### Response
| Status | Body | Condition |
| --- | --- | --- |
| 200 | array[[invite metadata](#invite-metadata-object) object] | The invites were returned |
| 400 | [error response](/http-api/#error-response) | `TWO_FACTOR_REQUIRED` when the guild needs [multi-factor authentication](/http-api/guilds/#mfa-levels) you lack |
The rate limit is 40 requests per 10 seconds, on the `invite:list::guild_id` bucket.