Emojis de guilda

Um emoji é uma imagem personalizada que pertence a uma guilda. Os membros o utilizam em mensagens e reações. Seu ID é um snowflake único em todas as guildas. Listar emojis da guilda é a única leitura com escopo de guilda, e Obter metadados do emoji resolve um único emoji sem ser membro da guilda dele.

Toda rota nomeia uma guilda em seu caminho (path). Quando essa guilda possui UNAVAILABLE_FOR_EVERYONE, o Decoding Chat rejeita a solicitação com 403 MISSING_ACCESS antes que a operação seja executada. O Decoding Chat faz o mesmo para uma guilda com UNAVAILABLE_FOR_EVERYONE_BUT_STAFF quando a conta não possui um sinalizador (flag) de equipe da instância.

Uma guilda que não existe retorna 404 UNKNOWN_GUILD. O Decoding Chat retorna 403 MISSING_PERMISSIONS a um solicitante que não é membro atual de uma guilda existente, portanto, a existência da guilda é distinguível da associação à guilda. Em Modificar emoji da guilda, um não-membro recebe o mesmo 403 MISSING_PERMISSIONS, e uma guilda que não existe retorna 404 UNKNOWN_EMOJI.

Nomes e imagens enviadas devem passar pela política de conteúdo da instância. Conteúdo bloqueado retorna 403 CONTENT_BLOCKED.

Objeto guild emoji

Apenas name pode ser alterado após a criação. A imagem armazenada é gravada uma vez na criação e nunca é substituída.

Estrutura

Campo	Tipo	Descrição
id	snowflake	O ID do emoji
name	string	O nome do emoji (2 a 32 caracteres)
animated¹	boolean	Se a imagem armazenada é animada
user?²	objeto partial user	A conta que enviou (upload) o emoji

¹ Detectado da imagem enviada na criação e copiado inalterado por Clonar emoji da guilda

² Presente apenas em Listar emojis da guilda, onde é definido para todos os solicitantes e não requer permissão

Exemplo

{
  "id": "1501314428688998182",
  "name": "party_parrot",
  "animated": true
}

Objeto emoji create

A imagem e o nome enviados para um novo emoji.

Estrutura

Campo	Tipo	Descrição
name¹	string	O nome do emoji (2 a 32 caracteres, letras ASCII, dígitos e sublinhado)
image² ³	string base64	A imagem a ser armazenada (no máximo o limite `emoji_max_size` resolvido em bytes decodificados, 524288 por padrão)

¹ O valor possui os espaços removidos (trimmed), e ambos os limites se aplicam ao valor sem espaços

² Um prefixo de URL de dados (data URL) é aceito e tudo até a primeira vírgula é removido antes que qualquer limite seja aplicado

³ O limite máximo decodificado é a chave de limite (limit key) emoji_max_size resolvida no escopo da guilda, 524288 bytes por padrão

A parte codificada restante é limitada a 699052 caracteres, a expansão base64 do padrão de 524288 bytes. Um valor maior retorna o código de validação BASE64_LENGTH_INVALID no caminho image. Um valor que não é base64 canônico com o preenchimento correto retorna INVALID_BASE64_FORMAT. Uma imagem acima do teto resolvido retorna IMAGE_SIZE_EXCEEDS_LIMIT no mesmo caminho, e maxSize é o teto aplicado.

O limite de 699052 caracteres não se move com a chave de limite, portanto, um teto resolvido acima de 524288 bytes não admite mais do que 524289 bytes decodificados.

Os formatos de upload aceitos são PNG, JPEG, WebP, GIF, APNG, AVIF, HEIC, HEIF, JXL e SVG. O Decoding Chat obtém o formato e o estado da animação da imagem decodificada. Um AVIF animado é rejeitado.

As dimensões em pixels não são forçadas. Uma imagem aceita é armazenada em suas dimensões originais e o contrato de ativo de imagem do Media Proxy seleciona o tamanho entregue.

Exemplo

{
  "name": "party_parrot",
  "image": "data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEAAAAALAAAAAABAAEAAAI="
}

Objeto emoji bulk create response

O resultado de uma criação em massa, contendo uma entrada para cada item enviado.

Estrutura

Campo	Tipo	Descrição
success	array[objeto guild emoji]	Os emojis que esta requisição criou
failed	array[objeto expression creation failure]	Os itens rejeitados após a validação de nível superior da requisição

Ambos os arrays estão presentes em toda resposta de sucesso, e qualquer um deles pode estar vazio. Um item aparece em exatamente um deles, portanto, o comprimento combinado é igual à contagem de itens enviados.

Exemplo

{
  "success": [{"id": "1501314428688998182", "name": "party_parrot", "animated": true}],
  "failed": [{"name": "too_big", "error": "The image is too large."}]
}

Objeto expression creation failure

Um item que uma criação em massa rejeitou, identificado apenas pelo nome que o solicitante enviou.

Estrutura

Campo	Tipo	Descrição
name¹	string	O nome ecoado do item enviado
error²	string	A mensagem de falha renderizada para o item

¹ O objeto não possui índice, de modo que não é possível distinguir dois itens enviados compartilhando o mesmo nome

² Renderizado no idioma (locale) da conta autenticada, então seu valor muda de acordo com a localidade do solicitante

A falha contém texto de exibição, não um código legível por máquina. Tente enviar novamente um item por meio de Criar emoji da guilda se um erro estruturado for necessário.

Listar emojis da guilda

GET/v1/guilds/{guild_id}/emojis

Bot

Retorna todo objeto guild emoji da guilda, cada um com user. Requer ser membro da guilda e nenhuma permissão específica.

O Decoding Chat retorna a coleção completa em uma resposta, e a operação não possui parâmetros de paginação. Um emoji cujo uploader não puder ser resolvido é omitido, portanto, o array pode ser menor que o número de emojis armazenados.

Parâmetros de rota

Campo	Tipo	Descrição
guild_id	snowflake	O ID da guilda

Resposta

Status	Corpo	Condição
200	array[objeto guild emoji]	Os emojis foram retornados
403¹	error response	A guilda está indisponível, ou o solicitante não é membro
404	error response	A guilda não existe e a requisição retorna `UNKNOWN_GUILD`

¹ O código de erro é MISSING_ACCESS para uma guilda indisponível e MISSING_PERMISSIONS para um não-membro

Limite de taxa

60 requisições a cada 10 segundos para cada usuário autenticado e ID de guilda, no bucket guild:emojis:list::guild_id.

Criar emoji da guilda

POST/v1/guilds/{guild_id}/emojis

Bot Audit reason

Cria um emoji a partir dos dados de imagem enviados e retorna seu objeto guild emoji sem user. Requer associação à guilda e CREATE_EXPRESSIONS. Emite um evento de Gateway Guild Emojis Update.

O limite de slots é o valor max_guild_emojis das limit keys configurado pelo operador e resolvido contra o conjunto completo de recursos da guilda, cujo padrão é 500. Uma guilda com UNLIMITED_EMOJI ignora essa configuração e recebe um limite fixo de 999999.

Parâmetros de rota

Campo	Tipo	Descrição
guild_id	snowflake	O ID da guilda

Corpo JSON

O corpo é um objeto emoji create.

Resposta

Status	Corpo	Condição
200	objeto guild emoji	O emoji foi criado
400¹	error response	A guilda atingiu seu limite de slots de emoji, ou a imagem é indecodificável, excedeu o tamanho ou está em um formato não aceito
403²	error response	O nome está bloqueado, a guilda está indisponível, o solicitante não é membro ou não tem `CREATE_EXPRESSIONS`, ou o hash da imagem está banido
404	error response	A guilda não existe e a requisição retorna `UNKNOWN_GUILD`

¹ O código de erro é MAX_EMOJIS para o limite de slots, com o limite resolvido em suas variáveis de mensagem, e INVALID_FORM_BODY para uma falha de imagem, com BASE64_LENGTH_INVALID para uma codificação excessivamente grande, IMAGE_SIZE_EXCEEDS_LIMIT para bytes decodificados acima do teto resolvido, ou INVALID_IMAGE_FORMAT para uma imagem indecodificável ou não aceita no caminho image

² O código de erro é CONTENT_BLOCKED para um nome bloqueado e para um hash de imagem banido, MISSING_ACCESS para uma guilda indisponível e MISSING_PERMISSIONS para uma falha de associação ou permissão

Efeitos colaterais

A criação de um emoji consome um slot de emoji da guilda, emite Guild Emojis Update com a coleção completa e registra uma entrada de auditoria EMOJI_CREATE com o motivo fornecido.

Limite de taxa

10 requisições a cada 30 segundos para cada usuário autenticado e ID de guilda, no bucket guild:emoji:create::guild_id.

Criar emojis da guilda em massa

POST/v1/guilds/{guild_id}/emojis/bulk

Bot Audit reason

Tenta criar entre 1 e 50 emojis em uma requisição e retorna um objeto emoji bulk create response. Requer associação à guilda e CREATE_EXPRESSIONS. Emite um evento de Gateway Guild Emojis Update para o lote todo.

O Decoding Chat processa os itens estritamente na ordem em que foram enviados e trata cada um de forma independente. Quando a guilda está cheia, todos os itens restantes falham por conta do limite. Um item posterior ainda pode ser bem-sucedido depois que um item anterior falhou por qualquer outro motivo.

Uma imagem indecodificável, um formato não aceito e um hash banido fazem com que um item falhe, mas deixam o restante do lote prosseguir.

Parâmetros de rota

Campo	Tipo	Descrição
guild_id	snowflake	O ID da guilda

Corpo JSON

Campo	Tipo	Descrição
emojis	array[objeto emoji create]	Os itens a serem criados, tentados na ordem fornecida (1 a 50)

Resposta

Status	Corpo	Condição
200	objeto emoji bulk create response	Todo item validado foi tentado
400¹	error response	O corpo da requisição principal, a contagem de itens, a forma do item, o nome do item ou o limite da imagem codificada são inválidos
403²	error response	Um nome de item está bloqueado, a guilda está indisponível, ou o solicitante não é membro ou não possui `CREATE_EXPRESSIONS`
404	error response	A guilda não existe e a requisição retorna `UNKNOWN_GUILD`

¹ A validação de limite rejeita toda a solicitação, portanto, uma imagem codificada grande demais em um item falha antes de qualquer item ser criado

² O código de erro é CONTENT_BLOCKED para um nome de item bloqueado, MISSING_ACCESS para uma guilda indisponível e MISSING_PERMISSIONS para falha de associação ou permissão

Um nome bloqueado rejeita toda a requisição sem criar nenhum emoji.

Efeitos colaterais

Cada item bem-sucedido consome um slot de emoji da guilda e registra uma entrada de auditoria EMOJI_CREATE com o motivo fornecido. Se algum item for bem-sucedido, um Guild Emojis Update contém a coleção completa de emojis da guilda.

Limite de taxa

6 requisições por minuto para cada usuário autenticado e ID de guilda, no bucket guild:emoji:bulk_create::guild_id.

Clonar emoji da guilda

POST/v1/guilds/{guild_id}/emojis/clone

Bot Audit reason

Copia um emoji existente para a guilda de destino e retorna o novo objeto guild emoji sem user. Requer ser membro da guilda de destino e ter CREATE_EXPRESSIONS lá. Emite um evento de Gateway Guild Emojis Update na guilda de destino.

O nome, o estado da animação e a imagem são copiados inalterados. A associação à guilda de origem não é necessária. A guilda de origem deve ter CLONE_EMOJI_ENABLED.

Obter metadados do emoji informa se uma origem permite a clonagem.

Parâmetros de rota

Campo	Tipo	Descrição
guild_id	snowflake	O ID da guilda de destino

Corpo JSON

Campo	Tipo	Descrição
source_emoji_id	snowflake	O ID do emoji a ser copiado, o qual pode pertencer a qualquer guilda

Resposta

Status	Corpo	Condição
200	objeto guild emoji	O emoji foi clonado
400¹	error response	A guilda de destino atingiu seu limite de slots de emoji
403²	error response	A guilda de origem não existe ou não permite clonagem, a guilda de destino está indisponível, ou o solicitante não é membro da guilda de destino ou não tem `CREATE_EXPRESSIONS` lá
404³	error response	O emoji de origem ou a guilda de destino não existe

¹ O código de erro é MAX_EMOJIS

² O código de erro é MISSING_ACCESS quando a guilda de origem está ausente ou não possui CLONE_EMOJI_ENABLED e quando a guilda de destino está indisponível, e MISSING_PERMISSIONS para uma falha de associação ou permissão no destino

³ O código de erro é UNKNOWN_EMOJI para o emoji de origem e UNKNOWN_GUILD para a guilda de destino

Uma guilda de origem que não existe mais retorna 403 MISSING_ACCESS, logo um solicitante não pode distingui-la de uma guilda de origem que não permite clonagem.

Efeitos colaterais

A cópia consome um slot de emoji da guilda de destino e nomeia o solicitante como uploader. Ela emite Guild Emojis Update na guilda de destino e registra uma entrada de auditoria EMOJI_CREATE. A origem permanece inalterada.

Limite de taxa

10 requisições a cada 30 segundos para cada usuário autenticado e ID da guilda de destino, no bucket guild:emoji:clone::guild_id.

Modificar emoji da guilda

PATCH/v1/guilds/{guild_id}/emojis/{emoji_id}

Bot Audit reason

Renomeia um emoji e retorna seu objeto guild emoji sem user. Emite um evento de Gateway Guild Emojis Update.

Limitações

O uploader pode renomear seu próprio emoji com CREATE_EXPRESSIONS.
Qualquer outro solicitante requer MANAGE_EXPRESSIONS.

Nenhuma das permissões está sujeita ao nível de MFA da guilda.

Um emoji que não pertence à guilda no caminho retorna 404 UNKNOWN_EMOJI.

Parâmetros de rota

Campo	Tipo	Descrição
guild_id	snowflake	O ID da guilda
emoji_id	snowflake	O ID do emoji

Corpo JSON

Campo	Tipo	Descrição
name	string	O novo nome do emoji (2 a 32 caracteres, letras ASCII, dígitos e sublinhado)

Resposta

Status	Corpo	Condição
200	objeto guild emoji	O nome foi definido, incluindo um nome igual ao atual
400¹	error response	O parâmetro de rota ou o nome é inválido
403²	error response	O nome está bloqueado, a guilda está indisponível, ou o solicitante não é o uploader com `CREATE_EXPRESSIONS` nem um membro com `MANAGE_EXPRESSIONS`
404	error response	O emoji não existe nessa guilda e a requisição retorna `UNKNOWN_EMOJI`

¹ O código de erro é INVALID_FORM_BODY com INVALID_SNOWFLAKE_FORMAT ou SNOWFLAKE_OUT_OF_RANGE para um parâmetro de rota, STRING_LENGTH_INVALID para um nome fora de 2 a 32 caracteres após normalização, e INVALID_FORMAT para um caractere não permitido

² O código de erro é CONTENT_BLOCKED para um nome bloqueado, MISSING_ACCESS para uma guilda indisponível e MISSING_PERMISSIONS para uma falha de permissão

Efeitos colaterais

A operação define o nome solicitado, emite Guild Emojis Update com a coleção completa de emojis da guilda e, em seguida, escreve uma entrada de auditoria EMOJI_UPDATE. Um nome enviado que é igual ao nome atual ainda emite o Despacho (Dispatch) e não registra nenhuma entrada de auditoria.

Limite de taxa

20 requisições a cada 10 segundos para cada usuário autenticado e ID de guilda, no bucket guild:emoji:update::guild_id.

Excluir emoji da guilda

DELETE/v1/guilds/{guild_id}/emojis/{emoji_id}

Bot Audit reason

Exclui o registro do emoji e retorna 204 com um corpo vazio. Emite um evento de Gateway Guild Emojis Update.

Limitações

O uploader pode excluir seu próprio emoji com CREATE_EXPRESSIONS.
Qualquer outro solicitante requer MANAGE_EXPRESSIONS.

Nenhuma das permissões está sujeita ao nível de MFA da guilda.

Parâmetros de rota

Campo	Tipo	Descrição
guild_id	snowflake	O ID da guilda
emoji_id	snowflake	O ID do emoji

Parâmetros de consulta (Query parameters)

Campo	Tipo	Descrição
purge?¹	boolean	Se a imagem armazenada deve ser excluída permanentemente (padrão false)

¹ Lido como verdadeiro apenas quando for exatamente true, True ou 1 após os espaços serem removidos (trim). Qualquer outro valor, incluindo TRUE e yes, é lido como falso

Resposta

Status	Corpo	Condição
204	vazio	O registro do emoji foi excluído
403¹	error response	A guilda está indisponível ou não pode expurgar ativos de expressão (expression assets), ou o solicitante não é o uploader com `CREATE_EXPRESSIONS` nem um membro com `MANAGE_EXPRESSIONS`
404²	error response	A guilda ou o emoji não existe

¹ O código de erro é MISSING_ACCESS para uma guilda indisponível e quando purge é true e a guilda não tem EXPRESSION_PURGE_ALLOWED, e MISSING_PERMISSIONS para uma falha de associação ou permissão

² O código de erro é UNKNOWN_GUILD para a guilda e UNKNOWN_EMOJI para o emoji

Efeitos colaterais

A exclusão libera um slot de emoji da guilda, emite Guild Emojis Update com a coleção restante e registra uma entrada de auditoria EMOJI_DELETE. As mensagens existentes que fazem referência ao emoji permanecem inalteradas.

Limite de taxa

10 requisições a cada 30 segundos para cada usuário autenticado e ID de guilda, no bucket guild:emoji:delete::guild_id. A rota também utiliza do bucket guild:emoji:delete:daily::guild_id de 300 requisições por dia para cada usuário autenticado e ID de guilda.