Objetos

Os formatos JSON que a API devolve e o gateway envia. Os nomes dos campos são exatamente os do JSON.

Convenções:

• id é um snowflake em string (veja IDs).
• ms é um número: milissegundos desde a época Unix.
• ? depois do tipo quer dizer que o valor pode ser null.
• Campos marcados opcional às vezes nem aparecem no JSON (em vez de virem null).

Usuário (PublicUser)

O que qualquer um vê de uma conta, pessoa ou bot. Aparece como autor de mensagens, dentro de membros, em READY.user e no evento USER_UPDATE.

campo	tipo	descrição
id	id	Id da conta.
username	string	Nome de usuário único, em minúsculas (2 a 32: letras, números, _ e .).
display_name	string	Nome de exibição (1 a 32 caracteres).
avatar	string?	Imagem do avatar: /api/media/... ou URL de GIF. Veja Imagens.
bot	boolean	true para bots (aparece com a etiqueta BOT).

Perfil (Profile)

Devolvido por GET /users/{id}/profile e PATCH /users/@me. O usuário vem aninhado em user.

campo	tipo	descrição
user	PublicUser	A conta.
bio	string?	"Sobre mim", até 190 caracteres (pode ter quebras de linha).
banner	string?	Imagem do banner, no mesmo formato de avatar.
accent	string?	Cor "#rrggbb" mostrada quando não há banner.

Bot (Bot)

Como o dono (e a página de convite) vê um bot. Os campos de PublicUser vêm no mesmo nível.

campo	tipo	descrição
id, username, display_name, avatar, bot		Como em PublicUser.
public	boolean	Se qualquer pessoa que gerencia um servidor pode adicioná-lo pelo link de convite.
bio	string?	"Sobre mim" do bot.
owner_id	id	Quem criou o bot.
guild_count	number	Em quantos servidores ele está.
token	string	Só na criação e ao gerar um token novo. Guarde: não aparece de novo.
owner	PublicUser	Só em GET /bots/{bot_id}.

Servidor (Guild)

campo	tipo	descrição
id	id	Id do servidor. É também o id do cargo @everyone.
name	string	Nome (2 a 100 caracteres).
icon	string?	Ícone, no mesmo formato de avatar.
owner_id	id	O dono. Sempre administrador; não pode sair nem ser removido.

Servidor completo (GuildFull)

Chega em READY.guilds e no evento GUILD_CREATE. Tem os campos de Guild no mesmo nível e mais:

campo	tipo	descrição
channels	Channel[]	Os canais que você pode ver. Postagens de fórum só vêm se tiveram atividade nos últimos 7 dias; as outras se buscam com GET /channels/{id}/posts.
members	Member[]	Todos os membros.
presences	string[]	Ids dos membros online neste momento.
roles	Role[]	Todos os cargos, incluindo @everyone.
emojis	Emoji[]	Os emojis do servidor.

Canal (Channel)

Canais de texto, salas de voz, categorias, fóruns, postagens de fórum e conversas privadas (DMs) são todos canais.

Tipos de canal

type	nome	o que é
0	CHANNEL_TEXT	Canal de texto.
1	CHANNEL_DM	Conversa privada entre duas contas.
2	CHANNEL_VOICE	Sala de voz. Não tem mensagens.
4	CHANNEL_CATEGORY	Categoria (seção) que agrupa canais.
11	CHANNEL_POST	Postagem dentro de um fórum: um canal próprio, com título e autor. Tem mensagens.
15	CHANNEL_FORUM	Fórum: guarda postagens em vez de mensagens.

Campos

campo	tipo	descrição
id	id	Id do canal.
guild_id	id?	Servidor do canal; null em DMs.
type	number	Um dos tipos.
name	string	Nome (1 a 100). Canais de texto e fóruns ficam em minúsculas, com hífens no lugar de espaços. Em DMs é "". Numa postagem, é o título.
topic	string?	Tópico, até 1024 caracteres.
position	number	Ordem entre os canais do mesmo tipo dentro da mesma categoria.
parent_id	id?	Categoria do canal; numa postagem, o fórum dela.
last_message_id	id?	Última mensagem. Num fórum, muda também quando há resposta numa postagem.
rate_limit_per_user	number	Modo lento, em segundos (0 = desligado; máximo 21600).
owner_id	id	opcional. Autor de uma postagem.
pinned	boolean	opcional (só aparece quando true). Postagem fixada.
locked	boolean	opcional (só aparece quando true). Postagem trancada: só a moderação responde.
message_count	number	opcional (não aparece quando é 0). Quantas mensagens o canal tem.
applied_tags	id[]	opcional (não aparece quando vazio). Tags de uma postagem, tiradas de available_tags do fórum.
voice_server	string	opcional. Servidor de voz escolhido para a sala (veja Voz). Sem ele, a sala usa o padrão.
available_tags	ForumTag[]	opcional. Tags de um fórum.
recipients	PublicUser[]	opcional. Numa DM: a outra pessoa (você não aparece).
permission_overwrites	Overwrite[]	opcional. Em canais de servidor: as permissões próprias do canal. Uma postagem traz as do fórum dela.

Tag de fórum (ForumTag)

campo	tipo	descrição
id	id	Id da tag.
name	string	Nome, 1 a 20 caracteres.
emoji	string?	Emoji mostrado com a tag.
moderated	boolean	Se só a moderação (Gerenciar mensagens) pode pôr ou tirar a tag.

Postagem listada (Post)

O que GET /channels/{forum_id}/posts devolve: os campos de Channel no mesmo nível, e mais:

campo	tipo	descrição
starter	Message?	A primeira mensagem da postagem.

Permissão de canal (Overwrite)

Bits liberados e negados num canal para um cargo ou um membro. Veja Permissões de canal.

campo	tipo	descrição
id	id	Id do cargo ou do membro. O id do servidor é o cargo @everyone.
type	number	0 = cargo, 1 = membro.
allow	number	Bits liberados.
deny	number	Bits negados.

Membro (Member)

Uma conta dentro de um servidor. O usuário vem aninhado em user.

campo	tipo	descrição
guild_id	id	O servidor.
user	PublicUser	A conta.
nick	string?	Apelido neste servidor (até 32).
is_admin	boolean	Se é ADM (administrador por marcação, além dos cargos). O dono sempre é.
joined_at	ms	Quando entrou.
roles	id[]	Cargos do membro. @everyone não aparece aqui; todos têm.

Cargo (Role)

campo	tipo	descrição
id	id	Id do cargo. O cargo cujo id é o do servidor é @everyone.
guild_id	id	O servidor.
name	string	Nome, 1 a 32.
color	number?	Cor 0xRRGGBB, ou null sem cor.
position	number	Altura na lista: @everyone é 0; quanto maior, mais alto.
permissions	number	Bits de permissão.
hoist	boolean	Se os membros com o cargo aparecem separados na lista de membros.

Emoji (Emoji)

campo	tipo	descrição
id	id	Id do emoji.
guild_id	id	O servidor.
name	string	Nome, 2 a 32 letras, números ou _.
url	string	Imagem (/api/media/...).
animated	boolean	Se é um GIF.

Nas mensagens, escreva <:nome:id> (ou <a:nome:id> se animado). Nas reações, nome:id.

Mensagem (Message)

campo	tipo	descrição
id	id	Id da mensagem.
channel_id	id	O canal. Não há guild_id: descubra pelo canal.
author	PublicUser	Quem mandou.
content	string	Texto, até 4000 caracteres. Pode ser vazio se houver anexos. Menções são <@id> dentro do texto.
timestamp	ms	Quando foi enviada (é o momento do id).
edited_timestamp	ms?	Última edição.
reply_to	MessageRef?	A mensagem que esta responde.
attachments	Attachment[]	Arquivos (até 10).
reactions	ReactionCount[]	Reações, na ordem em que apareceram.
nonce	string?	O nonce enviado por quem mandou (até 64 caracteres), para reconhecer a própria mensagem quando ela chegar pelo gateway.
embeds	Embed[]	Prévias de links. Chegam vazias no MESSAGE_CREATE e são preenchidas logo depois, por um MESSAGE_UPDATE. Mensagens com cartões não ganham prévias.
cards	Card[]	opcional. Cartões de um bot.
components	Button[][]	opcional. Fileiras de botões de um bot.
interaction	InteractionRef	opcional. O comando ou clique que esta mensagem (de um bot) responde.
ephemeral	boolean	opcional (só aparece quando true). Só quem usou o comando vê, e não fica guardada.

Cartão (Card)

Mandado por bots; veja Comandos, cartões e botões.

campo	tipo	descrição
title	string	opcional. Até 256.
description	string	opcional. Markdown, até 4096.
url	string	opcional. Link do título.
color	number	opcional. Cor da borda, 0xRRGGBB.
author	objeto	opcional. { name, url?, icon_url? }.
fields	objeto[]	opcional. Até 25 { name, value, inline }.
image	objeto	opcional. { url }, imagem grande.
thumbnail	objeto	opcional. { url }, imagem pequena ao lado.
footer	objeto	opcional. { text, icon_url? }.
timestamp	ms	opcional. Mostrado no rodapé.

Os links de imagem voltam trocados por /api/embeds/image?...: o servidor busca as imagens.

Botão (Button)

campo	tipo	descrição
style	string	primary, secondary, success, danger ou link.
label	string	opcional. Até 80.
emoji	string	opcional.
custom_id	string	Todos menos link. Até 100, único na mensagem.
url	string	Só link.
disabled	boolean	opcional.

Interação (InteractionRef)

campo	tipo	descrição
id	id	A interação.
name	string	opcional. O comando usado; não aparece num clique de botão.
user	PublicUser	Quem usou.

Comando (Command)

campo	tipo	descrição
name	string	1 a 32 letras minúsculas, números, _ ou -.
description	string	1 a 100.
options	objeto[]	Até 25 { name, description, type, required, choices?, min_value?, max_value? }; type é string, integer, number, boolean, user, channel ou role; choices são até 25 { name, value }.

Resposta (MessageRef)

campo	tipo	descrição
id	id	Id da mensagem respondida.
author	PublicUser?	O autor dela; null se ela foi apagada.
content	string?	Os primeiros 200 caracteres dela; null se foi apagada.

Anexo (Attachment)

campo	tipo	descrição
id	id	Id do anexo.
filename	string	Nome do arquivo (limpo: letras, números, ., - e _, até 100).
content_type	string	Tipo MIME.
size	number	Tamanho em bytes.
url	string	/api/attachments/{id}. Precisa de token para baixar.
thumbnail	string?	/api/attachments/{id}/thumb, quando é um vídeo com miniatura.
width	number?	Largura informada por quem enviou.
height	number?	Altura informada por quem enviou.

Reação (ReactionCount)

campo	tipo	descrição
emoji	string	Um emoji Unicode ("👍") ou um emoji de servidor como nome:id.
count	number	Quantas contas reagiram com ele.
me	boolean	Se quem pediu a mensagem está entre elas.

Prévia de link (Embed)

Feita pelo servidor para até 3 links da mensagem. Só url sempre aparece.

campo	tipo	descrição
url	string	O link.
site_name	string	opcional. Nome do site.
title	string	opcional. Título.
description	string	opcional. Descrição.
author	string	opcional. Quem publicou (um canal do YouTube, por exemplo).
color	string	opcional. Cor do site, "#rrggbb".
image	objeto	opcional. { url, width?, height?, large }; url passa por /api/embeds/image; large diz se a imagem vai grande, embaixo do texto.
video	objeto	opcional. { provider, id }: um player que o app pode abrir (por exemplo YouTube).

Convite (Invite)

campo	tipo	descrição
code	string	Código de 8 caracteres. O link é https://zynko.org/invite/{code}.
guild_id	id	O servidor.
creator_id	id	Quem criou.
uses	number	Quantas vezes foi usado.
max_uses	number?	Limite de usos; null = sem limite.
expires_at	ms?	Quando expira; null = nunca.

GET /invites/{code} devolve uma prévia: { code, guild: Guild, guild_id, member_count }.

Banimento (Ban)

campo	tipo	descrição
user	PublicUser	Quem foi banido.
created_at	ms	Quando.

Estado de voz (VoiceState)

Quem está em qual sala de voz (ou chamada numa DM). Chega em READY.voice_states e no evento VOICE_STATE_UPDATE.

campo	tipo	descrição
user_id	id	A conta.
guild_id	id?	O servidor; null numa chamada de DM.
channel_id	id?	A sala. null quando a conta saiu da voz.
self_mute	boolean	Microfone desligado.
self_deaf	boolean	Som desligado.
self_stream	boolean	Compartilhando a tela.
self_video	boolean	Câmera ligada.
session_id	string	A conexão do gateway que está na voz (o session_id do READY dela).

Estado de leitura (ReadState)

Até onde a conta já leu cada canal. Chega em READY.read_states.

campo	tipo	descrição
channel_id	id	O canal.
last_read_id	id	A última mensagem lida.

Relação (Relationship)

Amizades, pedidos e bloqueios. Bots não fazem amizades, mas podem bloquear.

campo	tipo	descrição
type	number	1 amigo, 2 bloqueado, 3 pedido recebido, 4 pedido enviado.
since	ms	Desde quando.
user	PublicUser	A outra conta.
online	boolean	Se está online (só para amigos; senão false).