Convites

Um convite é um código que permite a entrada de uma conta em uma guilda ou em uma mensagem direta em grupo.

Obter convite é a única rota aqui que não precisa de credencial. Modificar URL de convite personalizada da guilda configura a URL de convite personalizada de uma guilda, e a Descoberta define a entrada em uma guilda pública aprovada sem um convite.

Invite object

Um objeto de convite descreve um código e o destino no qual ele permite a entrada. O type seleciona a representação.

Structure

Field	Type	Description
code	string	O código exclusivo que identifica o convite
type	integer	Tipos de convite
guild?1	objeto partial guild	A guilda na qual o convite permite a entrada
channel?2	objeto partial invite channel	O canal da guilda ou mensagem direta em grupo que o convite tem como destino
inviter3	?objeto partial user	A conta que criou o convite, ou null
member_count?4	integer	A contagem de membros da guilda, ou a contagem exata de destinatários da mensagem direta em grupo
presence_count?4	integer	A contagem de membros online da guilda
expires_at5	?ISO8601 timestamp	O momento em que o convite para de resolver, ou null quando ele nunca expira
temporary6	boolean	Se a admissão por meio deste convite concede associação temporária

¹ Presente apenas quando type é 0, e aplica a mesma remoção de ativos com restrição de recurso que o objeto guild completo

² Presente quando type é 0 ou 1. Um convite de guilda sem um canal de destino armazenado resolve no primeiro canal de texto da guilda que a função padrão pode visualizar

³ Null quando o registro não armazena criador, o que é sempre o caso para uma URL de convite personalizada

⁴ As contagens da guilda são 0 quando indisponíveis

⁵ Computado a partir do momento de criação mais o tempo de vida armazenado, e null sempre que esse tempo de vida for 0

⁶ Não tem efeito em um convite de mensagem direta em grupo

Ramifique em type para saber quais campos chegam

Um convite de guilda sempre tem guild, channel, member_count e presence_count. Um convite de mensagem direta em grupo tem apenas channel e member_count.

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

Value	Name	Description
0	GUILD	Um convite que admite uma conta em uma guilda
1	GROUP_DM	Um convite que admite uma conta em uma mensagem direta em grupo

Invite metadata object

O objeto de metadados estende o convite com seu estado de criação e uso. Criar convite de canal, Listar convites de canal e Listar convites de guilda o retornam. Obter convite nunca faz isso.

Structure

Field	Type	Description
created_at	ISO8601 timestamp	O horário em que o registro do convite foi criado
uses1	integer	O número de admissões concluídas através do convite
max_uses2	integer	O máximo de admissões que o convite permite, onde 0 é ilimitado
max_age?3	integer	O tempo de vida armazenado em segundos, onde 0 nunca expira

¹ O contador avança apenas quando a admissão adiciona a conta, então aceitar um convite para um destino ao qual a conta já pertence deixa-o inalterado

² O valor é 0 para cada URL de convite personalizada e para qualquer convite criado sem um máximo explícito

³ Presente apenas quando type é 0, pois um convite de mensagem direta em grupo relata sua expiração apenas através de expires_at

Example

{
  "code": "aB3dEf7h",
  "type": 0,
  "created_at": "2026-08-04T11:22:19.000Z",
  "uses": 3,
  "max_uses": 25,
  "max_age": 86400,
  "temporary": false
}

Partial invite channel object

O canal parcial tem apenas identidade suficiente para descrever o destino antes da admissão.

Structure

Field	Type	Description
id	snowflake	O ID do canal
name1	?string	O nome do canal, ou null
type	integer	Tipos de canal
recipients?2	array[objeto partial invite recipient]	As contas na mensagem direta em grupo

¹ Um canal de guilda sempre armazena um nome, e uma mensagem direta em grupo que não armazena nome relata null

² Presente apenas em um convite de mensagem direta em grupo e lista todos os destinatários atuais, incluindo o criador do convite

Partial invite recipient object

Um destinatário parcial tem apenas o nome de usuário.

Structure

Field	Type	Description
username	string	O nome de usuário do destinatário

Example

{
  "username": "example"
}

Custom invite URLs

Modificar URL de convite personalizada da guilda cria ou substitui um código de convite personalizado. Tem tipo 0, inviter e expires_at null, e max_uses e max_age iguais a 0. Seu canal é o primeiro canal de texto da guilda em ordem de canais que a função padrão pode ver.

Os códigos de convite personalizados não diferenciam maiúsculas de minúsculas. Limpar ou substituir um código faz com que o link antigo pare de resolver imediatamente.

Aceitar convite registra a junção como uma admissão de URL de convite personalizada e não atribui nenhum convidador e nenhum código de convite de origem. Listar convites de canal e Listar convites de guilda excluem URLs de convite personalizadas e Excluir convite as recusa.

Get invite

GET/v1/invites/{invite_code}Unauthenticated

Lê um convite. Retorna um objeto convite em caso de sucesso.

Um cabeçalho Authorization que não pode ser resolvido é ignorado, e a rota retorna a mesma representação para todos os chamadores. A leitura não consome nenhum uso.

Códigos de Criar convite de canal diferenciam maiúsculas de minúsculas. Códigos de convite personalizados não diferenciam maiúsculas de minúsculas.

Todo portão de admissão é executado no momento da aceitação

Uma resposta 200 significa que o código do convite existe e nenhuma das condições 404 na tabela de respostas abaixo se aplica. Aceitar convite verifica proibições, o recurso de convites desativados da guilda, usos esgotados, a presença ativa exigida por um convite temporário e se o destino está cheio.

A pesquisa não garante a admissão

Convites expirados não são mais resolvidos. Um convite esgotado ainda pode ser resolvido até que uma tentativa de aceitação o remova.

Path parameters

Field	Type	Description
invite_code1	string	O código de convite para resolver (1 a 256 caracteres)

¹ Normalizado antes da pesquisa removendo o avanço de formulário (form feed) e caracteres de substituição da direita para a esquerda e aparando, e um valor vazio ou acima de 256 caracteres depois disso retorna o código de campo STRING_LENGTH_INVALID

Response

Status	Body	Condition
200	objeto invite	Convite resolvido
404	error response	Nenhum registro tem o código, um convite de guilda não nomeia nenhuma guilda, um convite de mensagem direta em grupo não nomeia nenhum canal ou destinatário não resolvível, ou um convite de guilda sem canal de destino armazenado não expõe nenhum canal visível, cada um retornando UNKNOWN_INVITE
404	error response	O canal de destino armazenado não existe mais e a solicitação retorna UNKNOWN_CHANNEL
404	error response	A guilda nomeada não existe mais e a solicitação retorna UNKNOWN_GUILD

Rate limit

100 solicitações por 10 segundos para cada identidade e código de convite, no bucket invite:read::invite_code. A identidade é a conta autenticada quando uma credencial é resolvida, e, caso contrário, a chave derivada para o endereço IP do cliente.

Accept invite

POST/v1/invites/{invite_code}

Aceita um convite e admite a conta autenticada em seu destino. Retorna um objeto convite em caso de sucesso.

Uma admissão de guilda emite eventos Gateway Guild Create, Guild Member Add, User Settings Update, User Guild Settings Update e Message Create. Uma admissão de mensagem direta em grupo emite os eventos de Gateway Channel Create, Channel Recipient Add e Message Create.

Limitations

• Apenas para usuário, então um token de bot é rejeitado com 403 ACCESS_DENIED.
• O chamador não precisa de nenhuma permissão.

Convites esgotados param de funcionar

Aceitar um convite esgotado retorna 404 UNKNOWN_INVITE e faz com que o código pare de resolver. URLs de convite personalizadas não têm limite de uso.

Path parameters

Field	Type	Description
invite_code	string	O código de convite a aceitar (1 a 256 caracteres)

Response

Status	Body	Condition
200	objeto invite	A conta foi admitida, ou já era membro do destino
400	error response	Um convite temporário da guilda é aceito sem uma presença ativa e a solicitação retorna TEMPORARY_INVITE_REQUIRES_PRESENCE
400	error response	Uma conta não reivindicada aceita um convite de mensagem direta em grupo e a solicitação retorna UNCLAIMED_ACCOUNT_CANNOT_JOIN_GROUP_DMS
400	error response	Um convite do tipo 1 nomeia um canal privado que não é uma mensagem direta em grupo e o chamador não é um destinatário, e a solicitação retorna INVALID_CHANNEL_TYPE
400	error response	O chamador já atingiu o número máximo de guildas e a solicitação retorna MAX_GUILDS
400	error response	O destino está cheio e a solicitação retorna MAX_GUILD_MEMBERS ou MAX_GROUP_DM_RECIPIENTS
403	error response	O chamador é um bot ou apresenta uma credencial bearer e a solicitação retorna ACCESS_DENIED
403	error response	A guilda possui o recurso de convites desativados e a solicitação retorna INVITES_DISABLED
403	error response	Convites instantâneos estão temporariamente desativados para a guilda e a solicitação retorna FEATURE_TEMPORARILY_DISABLED
403	error response	O chamador está banido por conta ou endereço de e-mail e a solicitação retorna USER_BANNED_FROM_GUILD
403	error response	O chamador está banido por endereço de rede e a solicitação retorna USER_IP_BANNED_FROM_GUILD
403	error response	Um requisito de verificação de telefone adiado torna-se devido e a solicitação retorna ACCOUNT_SUSPICIOUS_ACTIVITY
404	error response	A guilda nomeada não existe mais e a solicitação retorna UNKNOWN_GUILD
404	error response	O canal de destino não existe mais e a solicitação retorna UNKNOWN_CHANNEL
404	error response	O código resolve para nenhum registro, o registro está esgotado, um convite de guilda não nomeia guilda, ou um convite de mensagem direta em grupo não nomeia nenhum canal ou um canal que não existe mais, cada um retornando UNKNOWN_INVITE

Side effects

Quando a conta já está no destino, a rota retorna 200 com o objeto de convite. Ela não consome nenhum uso e não emite Dispatch. Uma nova admissão consome um uso e remove o convite quando seu limite é atingido. Uma admissão falha não consome uso. Se o canal do convite foi excluído, a conta ainda pode ingressar e consumir um uso, mesmo que a resposta seja 404 UNKNOWN_CHANNEL.

Uma admissão de guilda cria a associação, registra se o ingresso usou uma URL de convite personalizada ou um convite instantâneo e adiciona a guilda às configurações do chamador e layout de pastas. Um convite temporário marca a adesão como temporária.

A conta ingressante recebe Guild Create. Guild Member Add abrange toda a guilda e alcança todas as sessões conectadas à guilda, sujeito aos portões de filtragem de eventos, que o retém de uma sessão de usuário passiva em uma guilda com mais de 250 membros. A conta ingressante recebe User Settings Update quando o ingresso altera suas configurações armazenadas e User Guild Settings Update quando a configuração default_hide_muted_channels está habilitada. A menos que os system_channel_flags da guilda tenham SUPPRESS_JOIN_NOTIFICATIONS ou a guilda não tenha nenhum canal de sistema, a operação cria uma mensagem de sistema de ingresso e entrega Message Create.

Uma admissão de mensagem direta em grupo adiciona o chamador como um destinatário e cria uma mensagem de sistema de adição de destinatário. A conta ingressante recebe Channel Create, os destinatários que o grupo já possuía recebem Channel Recipient Add e todo destinatário recebe Message Create.

Nenhum caminho de admissão registra uma entrada de auditoria da guilda.

Rate limit

10 solicitações por 10 segundos para cada usuário autenticado, no bucket invite:accept, que não é particionado por código de convite.

Delete invite

DELETE/v1/invites/{invite_code}BotAudit reasonMFA

Exclui permanentemente um convite e retorna 204 com corpo vazio. Emite um evento Gateway Invite Delete.

Limitations

• Um convite de guilda requer adesão à guilda.
• O criador do convite o exclui sem reter MANAGE_GUILD, e qualquer outro membro precisa dessa permissão.
• Um convite de mensagem direta em grupo requer que o chamador seja um destinatário atual e o proprietário do grupo.

MANAGE_GUILD é uma permissão elevada, então um chamador que não é o dono da guilda nem está inscrito na autenticação multifator recebe 400 TWO_FACTOR_REQUIRED em uma guilda cujo nível MFA seja elevado.

A não adesão e a permissão ausente retornam o mesmo 403

Um não membro e um membro sem a permissão recebem 403 MISSING_PERMISSIONS. Uma guilda que não existe mais retorna 404 UNKNOWN_GUILD.

A exclusão é imediata e irrecuperável

O código do convite pode ser alocado novamente no futuro e todo link pendente com esse código para de resolver imediatamente.

Path parameters

Field	Type	Description
invite_code	string	O código de convite a ser excluído (1 a 256 caracteres)

Response

Status	Body	Condition
204	empty	Convite foi excluído
400	error response	O chamador não é o criador e a guilda exige autenticação multifatorial elevada que o chamador não tem, e a solicitação retorna TWO_FACTOR_REQUIRED
403	error response	O chamador apresenta uma credencial bearer e a solicitação retorna ACCESS_DENIED, ou o chamador não é membro da guilda, não é nem o criador nem possui o MANAGE_GUILD, ou não possui a mensagem direta em grupo, cada um retornando MISSING_PERMISSIONS
404	error response	A guilda nomeada não existe mais e a solicitação retorna UNKNOWN_GUILD
404	error response	Nenhum registro possui o código, o registro é a URL de convite personalizada atual da guilda, ou um convite de guilda não nomeia nenhum destino, cada um retornando UNKNOWN_INVITE
404	error response	A mensagem direta em grupo não existe mais ou o chamador não é um dos seus destinatários e a solicitação retorna UNKNOWN_CHANNEL

Side effects

Um convite de guilda registra uma ação de auditoria INVITE_DELETE direcionada ao código do convite, com o canal, o criador, usos máximos, tempo de vida útil e flag temporária como metadados, o registro removido como conjunto de alterações e o motivo fornecido. O Decoding Chat registra uma falha ao escrever essa entrada e ainda conclui a solicitação. O cabeçalho X-Audit-Log-Reason é lido, mas nunca registrado para um convite de mensagem direta em grupo.

Sessões com VIEW_AUDIT_LOG recebem Guild Audit Log Entry Create. Invite Delete tem apenas code, channel_id e guild_id. A guilda o entrega para as sessões que detêm MANAGE_CHANNELS no canal nomeado por channel_id, conforme a filtragem de eventos determina. Uma sessão passiva em uma guilda com mais de 250 membros é suprimida após esse filtro. Um convite de mensagem direta em grupo não cria entrada de auditoria e entrega Invite Delete às sessões de cada destinatário atual, onde nenhum portão passivo se aplica.

Rate limit

20 solicitações por 10 segundos para cada usuário autenticado e código de convite, no bucket invite:delete::invite_code.

Create channel invite

POST/v1/channels/{channel_id}/invitesBotAudit reason

Cria um convite para um canal, ou retorna um convite equivalente existente. Retorna um objeto metadados de convite em caso de sucesso. Emite um evento de Gateway Invite Create quando um novo registro é criado.

Limitations

• Um canal da guilda requer ser membro da guilda, ter VIEW_CHANNEL e CREATE_INSTANT_INVITE naquele canal exato.
• Um canal de guilda com restrição de idade também requer uma conta com verificação de idade.
• Um canal privado requer que o chamador seja um destinatário atual, e nenhuma propriedade é requerida.

Esta operação não exige autenticação multifatorial elevada.

Afiliação de guilda determina o tipo de convite

Um canal que pertence a uma guilda cria um convite de guilda. Qualquer outro canal que o chamador pode resolver cria um convite de tipo 1, incluindo uma mensagem direta e o canal de anotações pessoais. Desses convites de tipo 1, apenas aquele cujo canal é uma mensagem direta em grupo admite uma conta através de Aceitar convite.

Path parameters

Field	Type	Description
channel_id	snowflake	O ID do canal de guilda ou canal privado

JSON body

Todo campo é opcional e anulável, e um valor omitido ou nulo adota o padrão indicado.

Field	Type	Description
max_uses?1	?integer	O número máximo de admissões (0-100, padrão 0, onde 0 é ilimitado)
max_age?1	?integer	O tempo de vida em segundos (0-604800, padrão 0, onde 0 nunca expira)
unique?2	?boolean	Se deve criar um novo convite mesmo quando um equivalente já existir (padrão false)
temporary?3	?boolean	Se a admissão concede afiliação temporária (padrão false)

¹ Um valor negativo, um max_uses acima de 100 ou um max_age acima de 604.800 segundos é rejeitado com 400 INVALID_FORM_BODY nesse campo

² Quando false ou omitido a operação retorna um convite existente cujo criador, canal de destino, usos máximos, tempo de vida e flag temporária correspondem à solicitação exatamente. Uma URL de convite personalizada nunca corresponde

³ Não tem efeito em um convite de canal privado

Response

Status	Body	Condition
200	objeto metadados de convite	Convite foi criado, ou um convite existente equivalente foi retornado
400	error response	A guilda já tem seu número máximo de convites e a solicitação retorna MAX_INVITES
403	error response	Chamador apresenta uma credencial bearer e a solicitação retorna ACCESS_DENIED
403	error response	A guilda não está disponível para o chamador e a solicitação retorna MISSING_ACCESS
403	error response	Os convites instantâneos estão desativados temporariamente para a guilda e a solicitação retorna FEATURE_TEMPORARILY_DISABLED
403	error response	O chamador não é membro da guilda ou não possui VIEW_CHANNEL ou CREATE_INSTANT_INVITE e a solicitação retorna MISSING_PERMISSIONS
403	error response	O canal possui restrição de idade e a conta não tem a idade verificada e a solicitação retorna NSFW_CONTENT_AGE_RESTRICTED
404	error response	Canal não existe, tem exclusão pendente, ou o chamador não é destinatário do canal privado, cada um retornando UNKNOWN_CHANNEL, ou a guilda do canal não existe mais e a solicitação retorna UNKNOWN_GUILD

Side effects

Retornar um convite equivalente existente não altera nada, não registra entrada de auditoria e não emite Dispatch.

Criar um convite aloca um código de oito caracteres aleatório retirado do alfabeto alfanumérico com letras maiúsculas e minúsculas. Um convite de guilda registra uma ação de auditoria INVITE_CREATE voltada ao código do convite, com o canal, criador, usos máximos, tempo de vida e flag temporária como metadados e a razão fornecida, e depois entrega Guild Audit Log Entry Create a sessões que possuem VIEW_AUDIT_LOG. O Decoding Chat registra uma falha ao gravar essa entrada e ainda assim completa a solicitação. O cabeçalho X-Audit-Log-Reason é lido, mas nunca registrado para um canal privado.

A guilda entrega Invite Create para as sessões que detêm MANAGE_CHANNELS no canal do convite, sujeito a filtragem de eventos. Um convite de canal privado não grava entrada de auditoria e entrega o evento às sessões de todo destinatário atual.

O limite de convites de guilda é seu limite configurado max_guild_invites, que por padrão é 1.000. Isso inclui convites em todos os canais e a URL de convite personalizada.

Rate limit

20 solicitações por minuto para cada usuário autenticado e ID de canal, no bucket invite:create::channel_id.

List channel invites

GET/v1/channels/{channel_id}/invitesBotMFA

Retorna os convites padrão de um canal como uma array de objetos metadados de convite, ordenados pelo tempo de criação decrescente.

Limitations

• Um canal de guilda exige afiliação à guilda, VIEW_CHANNEL naquele canal e MANAGE_CHANNELS na guilda.
• Um canal de guilda com restrição de idade exige também uma conta com a idade verificada.
• Uma mensagem direta em grupo exige que o chamador seja um destinatário atual e seu proprietário.

MANAGE_CHANNELS é uma permissão elevada, portanto, um chamador que não é proprietário da guilda nem possui autenticação de dois fatores configurada recebe 400 TWO_FACTOR_REQUIRED em uma guilda cujo nível de MFA seja elevado.

A operação não tem paginação. Cada registro correspondente é retornado em uma única resposta, limitado pelo teto de convites da guilda descrito por Create channel invite. A resposta exclui o registro de URL de convite personalizada.

Path parameters

Field	Type	Description
channel_id	snowflake	O ID do canal de guilda ou mensagem direta em grupo

Response

Status	Body	Condition
200	array[objeto metadados de convite]	Convites foram retornados, e o array é vazio quando o canal não possui nenhum
400	error response	A guilda requer autenticação multifatorial elevada que o chamador não tem e a solicitação retorna TWO_FACTOR_REQUIRED
403	error response	Chamador apresenta uma credencial bearer e a solicitação retorna ACCESS_DENIED
403	error response	A guilda não está disponível para o chamador e a solicitação retorna MISSING_ACCESS
403	error response	O chamador não é um membro da guilda, não tem VIEW_CHANNEL ou MANAGE_CHANNELS, ou não é dono da mensagem direta em grupo e a solicitação retorna MISSING_PERMISSIONS
403	error response	O canal tem restrição de idade e a conta não tem verificação de idade e a solicitação retorna NSFW_CONTENT_AGE_RESTRICTED
404	error response	Canal não existe, está pendente de deleção, o chamador não é um destinatário do canal privado ou o canal privado não é uma mensagem direta em grupo, cada um retornando UNKNOWN_CHANNEL, ou a guilda do canal não existe mais e a solicitação retorna UNKNOWN_GUILD

Rate limit

40 solicitações por 10 segundos para cada usuário autenticado e ID de canal, no bucket invite:list::channel_id.

List guild invites

GET/v1/guilds/{guild_id}/invitesBotMFA

Retorna os convites padrão de uma guilda em todos os seus canais como uma array de objetos metadados de convite, ordenados pelo tempo de criação decrescente. Requer associação à guilda e MANAGE_GUILD.

MANAGE_GUILD é uma permissão elevada, portanto, um chamador que não é proprietário da guilda nem possui autenticação de dois fatores configurada recebe 400 TWO_FACTOR_REQUIRED em uma guilda cujo nível de MFA seja elevado.

A operação não tem paginação. Cada registro correspondente é retornado em uma única resposta, limitado pelo teto de convites da guilda descrito em Create channel invite. A resposta exclui o registro de URL de convite personalizada, para que um cliente leia o código do convite personalizado atual através de Get guild custom invite URL.

Path parameters

Field	Type	Description
guild_id	snowflake	O ID da guilda

Response

Status	Body	Condition
200	array[objeto metadados de convite]	Convites foram retornados, e o array é vazio quando a guilda não possui nenhum
400	error response	A guilda requer autenticação multifatorial elevada que o chamador não tem e a solicitação retorna TWO_FACTOR_REQUIRED
403	error response	Chamador apresenta uma credencial bearer e a solicitação retorna ACCESS_DENIED
403	error response	A guilda não está disponível para o chamador e a solicitação retorna MISSING_ACCESS
403	error response	O chamador não é um membro da guilda ou não possui MANAGE_GUILD e a solicitação retorna MISSING_PERMISSIONS
404	error response	Guilda não existe e a solicitação retorna UNKNOWN_GUILD

Rate limit

40 solicitações por 10 segundos para cada usuário autenticado e ID da guilda, no bucket invite:list::guild_id.