Adesivos de guilda

Um adesivo (sticker) é uma imagem que uma guilda armazena para seus membros enviarem com uma mensagem. Ele pertence a exatamente uma guilda. Seu snowflake é único em todas as guildas. Obter metadados do adesivo resolve um adesivo sem que você seja membro da guilda dele.

Toda rota nomeia uma guilda em seu caminho. Uma guilda que possui UNAVAILABLE_FOR_EVERYONE rejeita a requisição com 403 MISSING_ACCESS antes que a operação seja executada. UNAVAILABLE_FOR_EVERYONE_BUT_STAFF faz o mesmo para uma conta sem a flag de equipe (staff) da instância. Em Clonar adesivo de guilda, o bloqueio cobre a guilda de destino e nunca a guilda de origem.

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

Uma guilda que não existe retorna 404 UNKNOWN_GUILD. Um solicitante que não é um membro atual de uma guilda existente retorna 403 MISSING_PERMISSIONS, então a existência da guilda é distinguível da adesão à guilda. Modificar adesivo de guilda retorna 404 UNKNOWN_STICKER para uma guilda que não existe.

Não há leitura de um único adesivo no escopo de uma guilda. Listar adesivos de guilda retorna toda a coleção em uma única resposta.

Objeto de adesivo de guilda

Um objeto de adesivo de guilda descreve um adesivo. Apenas seu nome, descrição e tags podem mudar. Substituir a imagem requer a criação de um novo adesivo.

Estrutura

Campo	Tipo	Descrição
id	snowflake	O ID do adesivo
name	string	O nome do adesivo (2-30 caracteres)
description¹	string	A descrição do adesivo, ou uma string vazia quando não tiver nenhuma
tags	array[string]	Tags do adesivo
animated²	boolean	Se a imagem armazenada é animada
user?³	objeto usuário parcial	A conta que enviou o adesivo

¹ Nunca nulo na transmissão. Um adesivo sem descrição tem uma string vazia

² Detectado a partir da imagem enviada na criação e copiado inalterado por Clonar adesivo de guilda

³ Presente apenas em Listar adesivos de guilda, onde é definido para todo solicitante e não requer permissão

Um adesivo é sempre um adesivo de guilda, e animated sozinho descreve seu formato. O objeto não tem tipo de adesivo, tipo de formato ou campo de disponibilidade.

Exemplo

{
  "id": "1501314428688998183",
  "name": "shipit",
  "description": "Ship it",
  "tags": ["ship", "deploy"],
  "animated": false
}

Tags do adesivo

As tags são um array de strings. Uma requisição de criação ou modificação aceita no máximo 10 entradas. O Decoding Chat apara (trims) cada entrada. O limite de 1 a 30 caracteres se aplica ao valor aparado. As entradas são armazenadas e retornadas na ordem enviada.

O array é opcional em toda requisição que o aceita e tem como padrão um array vazio, portanto, omiti-lo em Modificar adesivo de guilda limpa as tags armazenadas.

Objeto de criação de adesivo

O formato de item compartilhado por Criar adesivo de guilda e cada entrada de Criar adesivos de guilda em massa.

Estrutura

Campo	Tipo	Descrição
name¹	string	O nome do adesivo (2-30 caracteres)
description?²	?string	A descrição do adesivo (1-500 caracteres), ou null para nenhuma
tags?	array[string]	Tags do adesivo, cujo padrão é um array vazio
image³	string base64	Os dados da imagem, com no máximo 524288 bytes decodificados

¹ O valor é aparado antes de aplicar o limite, assim como ocorre para description e cada tag

² Um valor omitido e null são ambos armazenados como null e retornados como uma string vazia

³ Um prefixo de URL de dados é aceito e tudo até a primeira vírgula é removido antes da aplicação de qualquer limite

A parte codificada restante é limitada a 699052 caracteres, o que codifica uma imagem inteira de 524288 bytes, e um valor mais longo retorna o código de validação BASE64_LENGTH_INVALID no caminho image. Um valor que não seja base64 canônico com o preenchimento correto retorna INVALID_BASE64_FORMAT.

Os bytes decodificados são, no máximo, o valor configurado pelo operador chave de limite sticker_max_size, resolvido em relação ao conjunto completo de funcionalidades da guilda e cujo padrão é 524288. Uma imagem maior é rejeitada no caminho image com IMAGE_SIZE_EXCEEDS_LIMIT, cuja mensagem nomeia o teto resolvido. Uma imagem acima de 524289 bytes excede o limite de 699052 caracteres e retorna BASE64_LENGTH_INVALID, então um valor configurado acima de 524289 nunca se aplica.

Os formatos de upload aceitos são PNG, JPEG, APNG, GIF, WebP, AVIF e SVG. O Decoding Chat retira o formato da imagem decodificada. Um AVIF animado é rejeitado. O Decoding Chat detecta o estado de animação a partir da imagem, portanto, este objeto não tem um campo de animação.

As dimensões de pixel e a duração da animação não são aplicadas. Uma imagem aceita é armazenada com suas dimensões originais. O contrato de ativo de imagem Media Proxy seleciona o tamanho entregue.

Exemplo

{
  "name": "shipit",
  "description": "Ship it",
  "tags": ["ship", "deploy"],
  "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAAAAAA6fptVAAAACklEQVR4nGMAAQAABQABDQottAAAAABJRU5ErkJggg=="
}

Objeto de resposta de criação em massa de adesivos

O resultado de uma chamada de Criar adesivos de guilda em massa, dividido entre os itens que foram criados e os itens que foram rejeitados.

Estrutura

Campo	Tipo	Descrição
success	array[objeto adesivo de guilda]	Os adesivos que foram criados
failed	array[objeto falha de criação de adesivo]	Os itens rejeitados após a validação da requisição no nível superior

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

Exemplo

{
  "success": [],
  "failed": [{"name": "shipit", "error": "The image is too large."}]
}

Objeto de falha de criação de adesivo

Um item rejeitado de uma chamada de criação em massa, nomeado e explicado no texto de exibição.

Estrutura

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

¹ O objeto não tem um índice, portanto dois itens enviados que compartilham um nome não podem ser distinguidos

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

Não há nenhum código legível por máquina, então um cliente que precisa se ramificar de acordo com o motivo envia aquele item de novo através de Criar adesivo de guilda, que retorna um código de erro.

Listar adesivos de guilda

GET/v1/guilds/{guild_id}/stickers

Bot

Retorna todo objeto de adesivo de guilda da guilda, cada um com o user. Requer adesão à guilda e nenhuma permissão.

Uma resposta possui a coleção completa. A operação não é paginada. Um adesivo cujo enviador não possa ser resolvido é omitido, então o array pode ser menor do que o número de adesivos armazenados.

Parâmetros de caminho

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

Resposta

Status	Corpo	Condição
200	array[objeto adesivo de guilda]	Os adesivos foram retornados
403¹	resposta de erro	A guilda está indisponível ou o solicitante não é um membro
404	resposta de erro	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 ID de guilda e usuário autenticado, no bucket guild:sticker:list::guild_id.

Criar adesivo de guilda

POST/v1/guilds/{guild_id}/stickers

Bot Audit reason

Cria um adesivo a partir dos dados de imagem enviados e retorna o seu objeto de adesivo de guilda sem user. Requer adesão à guilda e CREATE_EXPRESSIONS. Emite um evento de Gateway Atualização de Adesivos de Guilda.

O limite de slots é o valor configurado pelo operador em max_guild_stickers resolvido em relação ao conjunto completo de recursos da guilda, cujo padrão é 500. Uma guilda com UNLIMITED_STICKERS contorna essa configuração e recebe um limite fixo de 999999.

Parâmetros de caminho

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

Corpo JSON

O corpo é um objeto de criação de adesivo.

Resposta

Status	Corpo	Condição
200	objeto adesivo de guilda	O adesivo foi criado
400¹	resposta de erro	A guilda atingiu seu limite de slots para adesivos ou a imagem é inválida
403²	resposta de erro	A guilda está indisponível, o solicitante não é um membro ou carece de `CREATE_EXPRESSIONS`, ou o texto/imagem enviado foi bloqueado
404	resposta de erro	A guilda não existe e a requisição retorna `UNKNOWN_GUILD`

¹ O código de erro é MAX_STICKERS para o limite de slot, com o limite resolvido em suas variáveis de mensagem. Uma falha de imagem é INVALID_FORM_BODY com BASE64_LENGTH_INVALID para uma codificação com tamanho excessivo, 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 é MISSING_ACCESS para uma guilda indisponível, MISSING_PERMISSIONS para uma falha de permissão ou de adesão, e CONTENT_BLOCKED quando o nome, descrição ou uma tag corresponde a uma lista de bloqueio ou a imagem decodificada corresponde ao hash de um arquivo banido

Efeitos colaterais

Criar um adesivo consome um slot de adesivo da guilda, emite Atualização de Adesivos de Guilda com a coleção completa e registra uma entrada de auditoria STICKER_CREATE com o motivo fornecido.

Limite de taxa

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

Criar adesivos de guilda em massa

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

Bot Audit reason

Tenta criar entre 1 e 50 adesivos em uma única requisição e retorna um objeto resposta de criação em massa de adesivos. Emite um evento de Gateway Atualização de Adesivos de Guilda para o lote inteiro.

O solicitante precisa ser membro da guilda e ter CREATE_EXPRESSIONS. O Decoding Chat processa os itens estritamente na ordem enviada e trata cada um de forma independente. Um item falha quando não restar mais nenhum slot de adesivo na guilda. Um item posterior ainda pode ter sucesso depois que um item anterior tiver falhado por outro motivo.

Parâmetros de caminho

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

Corpo JSON

Campo	Tipo	Descrição
stickers	array[objeto criação de adesivo]	Os itens a serem criados, na ordem em que são processados (1-50)

Resposta

Status	Corpo	Condição
200	objeto resposta de criação em massa de adesivos	Todo item validado foi tentado
400¹	resposta de erro	O corpo de nível superior, contagem de itens, formato de item, metadados de item ou limite da imagem codificada são inválidos
403²	resposta de erro	A guilda está indisponível, o solicitante não é um membro ou carece de `CREATE_EXPRESSIONS`, ou uma string enviada foi bloqueada
404	resposta de erro	A guilda não existe e a requisição retorna `UNKNOWN_GUILD`

¹ Uma imagem codificada com tamanho excessivo, um nome fora da faixa ou uma tag fora de seu limite rejeitam toda a requisição antes que qualquer item seja criado

² O código de erro é MISSING_ACCESS para uma guilda indisponível, MISSING_PERMISSIONS para falha de permissão ou de adesão, e CONTENT_BLOCKED para uma string bloqueada

Uma imagem decodificada que tenha tamanho excessivo, seja indecodificável, esteja em um formato não aceito ou corresponda ao hash de um arquivo banido falha apenas aquele item.

Efeitos colaterais

Cada item bem-sucedido consome um slot de adesivo de guilda e registra uma entrada de auditoria STICKER_CREATE com o motivo fornecido.

O Decoding Chat emite um Atualização de Adesivos de Guilda após o lote quando ao menos um item for bem-sucedido, contendo a coleção completa de adesivos da guilda. Um lote no qual nenhum item foi bem-sucedido não emite nada.

Limite de taxa

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

Clonar adesivo de guilda

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

Bot Audit reason

Copia um adesivo existente para a guilda de destino e retorna o novo objeto adesivo de guilda sem user. Emite um evento de Gateway Atualização de Adesivos de Guilda na guilda de destino.

O solicitante precisa ser membro da guilda de destino e ter CREATE_EXPRESSIONS nela. Adesão à guilda de origem não é requerida. A guilda de origem deve ter CLONE_STICKER_ENABLED, a qual uma guilda possui somente depois de se inscrever para tal.

O nome, descrição, tags, estado de animação e imagem são copiados inalterados.

Obter metadados do adesivo informa se uma origem permite a clonagem sem tentar a operação.

Parâmetros de caminho

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

Corpo JSON

Campo	Tipo	Descrição
source_sticker_id	snowflake	O ID do adesivo a ser copiado, que pode pertencer a qualquer guilda

Resposta

Status	Corpo	Condição
200	objeto adesivo de guilda	O adesivo foi clonado
400¹	resposta de erro	A guilda de destino atingiu seu limite de slots de adesivo
403²	resposta de erro	A guilda de origem está ausente ou não permite clonagem, a guilda de destino está indisponível, ou o solicitante não é um membro da guilda de destino ou carece de `CREATE_EXPRESSIONS` nela
404³	resposta de erro	O adesivo de origem ou a guilda de destino não existem

¹ O código de erro é MAX_STICKERS

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

³ O código de erro é UNKNOWN_STICKER para o adesivo 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 consegue distingui-la de uma guilda de origem que não permite clonagem.

Efeitos colaterais

A cópia consome um slot de adesivo na guilda de destino e nomeia o solicitante como enviador. Emite Atualização de Adesivos de Guilda na guilda de destino e registra uma entrada de auditoria STICKER_CREATE. A origem permanece inalterada.

Limite de taxa

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

Modificar adesivo de guilda

PATCH/v1/guilds/{guild_id}/stickers/{sticker_id}

Bot Audit reason

Substitui os metadados do adesivo e retorna o objeto adesivo de guilda sem user. Emite um evento de Gateway Atualização de Adesivos de Guilda.

Limitações

O enviador pode modificar seu próprio adesivo com CREATE_EXPRESSIONS, e qualquer outro solicitante precisa de MANAGE_EXPRESSIONS.
Nenhuma permissão está sujeita ao nível de MFA da guilda.
A imagem armazenada não pode ser substituída, logo, uma mudança de imagem requer a criação de um novo adesivo.

Um adesivo que não pertence à guilda no caminho retorna 404 UNKNOWN_STICKER.

Parâmetros de caminho

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

Corpo JSON

Campo	Tipo	Descrição
name	string	O nome do adesivo (2-30 caracteres)
description?¹	?string	A descrição do adesivo (1-500 caracteres), ou null para limpá-la
tags?²	array[string]	Tags do adesivo, cujo padrão é um array vazio

¹ Um valor omitido e null são ambos armazenados como null e retornados como uma string vazia

² Um array omitido é escrito como um array vazio

Resposta

Status	Corpo	Condição
200	objeto adesivo de guilda	Os metadados foram processados
403¹	resposta de erro	A guilda está indisponível, o solicitante não é o enviador com `CREATE_EXPRESSIONS` nem um membro com `MANAGE_EXPRESSIONS`, ou o texto enviado foi bloqueado
404	resposta de erro	O adesivo não existe naquela guilda e a requisição retorna `UNKNOWN_STICKER`

¹ O código de erro é MISSING_ACCESS para uma guilda indisponível, MISSING_PERMISSIONS para uma falha de permissão ou adesão, e CONTENT_BLOCKED para um nome, descrição ou tag bloqueada

Um não membro que nomeia um adesivo existente recebe MISSING_PERMISSIONS.

Efeitos colaterais

A operação escreve os metadados fornecidos, emite Atualização de Adesivos de Guilda com a coleção completa de adesivos da guilda e então registra uma entrada de auditoria STICKER_UPDATE. Valores enviados que correspondem aos armazenados ainda emitem o Dispatch e não registram nenhuma entrada de auditoria.

Limite de taxa

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

Excluir adesivo de guilda

DELETE/v1/guilds/{guild_id}/stickers/{sticker_id}

Bot Audit reason

Exclui o registro do adesivo e retorna 204 com um corpo vazio. Emite um evento de Gateway Atualização de Adesivos de Guilda.

Limitações

O enviador pode excluir seu próprio adesivo com CREATE_EXPRESSIONS, e qualquer outro solicitante precisa de MANAGE_EXPRESSIONS.
Definir purge requer que a guilda possua EXPRESSION_PURGE_ALLOWED.

Parâmetros de caminho

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

Parâmetros de consulta

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

¹ Lido como true apenas quando for exatamente true, True ou 1 após aparar. Todo outro valor, incluindo TRUE e yes, é lido como false

Resposta

Status	Corpo	Condição
204	vazio	O adesivo foi excluído
403¹	resposta de erro	A guilda está indisponível ou não pode purgar ativos de expressão, ou o solicitante não é o enviador com `CREATE_EXPRESSIONS` nem um membro com `MANAGE_EXPRESSIONS`
404²	resposta de erro	A guilda ou o adesivo não existem

¹ 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 permissão ou adesão

² O código de erro é UNKNOWN_GUILD para a guilda e UNKNOWN_STICKER para o adesivo

Efeitos colaterais

A operação remove o adesivo da guilda, devolve seu slot, emite Atualização de Adesivos de Guilda com a coleção restante de adesivos da guilda e, em seguida, grava uma entrada de auditoria STICKER_DELETE.

Com purge, a imagem pode permanecer disponível brevemente após o 204. Mensagens existentes que referenciam o adesivo não são alteradas.

Limite de taxa

10 requisições a cada 30 segundos para cada ID de guilda e usuário autenticado, no bucket guild:sticker:delete::guild_id. A rota cobra uma segunda franquia de 300 requisições por dia para cada ID de guilda e usuário autenticado, no bucket guild:sticker:delete:daily::guild_id.