Instância

Descubra os endpoints de uma implantação, os recursos disponíveis e os limites, consulte a localização aproximada do cliente ou baixe o documento OpenAPI.

Obter descoberta de instância é o ponto de entrada da API. Um cliente que conhece apenas uma origin do Decoding Chat lê /.well-known/fluxer primeiro, e essa única resposta não autenticada tem todos os campos do objeto de descoberta de instância. Esses valores incluem as URLs base da API, a URL WebSocket do Gateway principal e a URL base do Media Proxy. Eles substituem os padrões de caminho do endpoint que uma implantação serviria da sua origin pública canônica.

Toda rota aqui é não autenticada. Uma credencial não altera nenhum corpo de resposta. Uma que resolve para uma conta move o bucket de rate limit do endereço IP do cliente para essa conta.

Cada uma das rotas responde com Access-Control-Allow-Origin: *, substituído pela Origin da requisição quando a política de requisições de origem cruzada da implantação permite aquela origin. A API Admin de Instância define o lado do operador da mesma configuração.

Objeto de descoberta de instância

O documento de descoberta é a descrição pública completa de uma implantação. Todo campo está sempre presente.

Estrutura

Campo	Tipo	Descrição
api_code_version¹	integer	A versão do código do servidor de API que esta implantação executa
endpoints	endpoints de instância object	Endpoints públicos de serviço desta implantação
captcha	configuração de CAPTCHA object	Configuração pública de CAPTCHA
features	recursos de instância object	Estado público de recursos da implantação
gif	provedor de GIF object	O provedor de GIF ativo e seu requisito de atribuição
sso	status de SSO object	Estado público de autenticação única
registration	política de registro object	Política pública de registro
community	política de comunidade object	Padrões da comunidade e política de mensagens diretas
services	disponibilidade de serviço object	Disponibilidade resolvida de integrações de terceiros
limits	configuração de limites object	Regras de limite ordenadas e nomes de traits que a implantação declara
push	configuração de push object	Identidade pública de Web Push
app_public	configuração pública de aplicação object	Configuração pública do cliente

¹ O valor é um inteiro simples que aumenta quando a API introduz uma mudança que um cliente deve observar, e o valor atual é 1

Objeto de endpoints de instância

Cada valor é uma URL absoluta fornecida pelo operador. Um valor pode ser uma origin simples ou uma origin com prefixo de caminho, pois uma implantação pode servir várias funções de uma única origin pública canônica. Um cliente que recebe dois endpoints que compartilham uma origin NÃO DEVE inferir host, esquema ou porta separados para nenhum deles.

Estrutura

Campo	Tipo	Descrição
api¹	string	URL base para requisições autenticadas à API
api_client¹	string	URL base para requisições da API do cliente
api_public	string	URL base para requisições públicas à API
gateway²	string	URL WebSocket do Gateway principal
media	string	URL base do Media Proxy, também usada como base do relay de upload de anexos
static_cdn³	string	URL base de assets estáticos
marketing	string	URL base do site de marketing
admin	string	URL base do aplicativo admin
invite	string	URL base de links de convite
gift	string	URL base de links de presente
webapp	string	URL base do aplicativo web

¹ Ambos os campos são o mesmo endpoint de API do cliente configurado, que o aplicativo web de primeira parte lê. api_public é o endpoint de API pública configurado separadamente, que um bot, biblioteca ou outro cliente de terceiros lê. Uma implantação pode apontar os dois para uma origin, e a instância hospedada pelo Decoding Chat não faz isso

² O valor é o endpoint Gateway configurado e seu esquema é ws ou wss conforme o operador configurou

³ Quando uma implantação configura um domínio de assets estáticos separado, o valor é https:// seguido daquele domínio, sem porta

Cada valor é a origin exata que a implantação anuncia, incluindo seu esquema e qualquer porta explícita, e uma implantação deliberadamente HTTP simples publica valores http e ws aqui.

O operador configura uma origin pública canônica com esquema exato http ou https, host e porta explícita opcional. O aplicativo web é servido nessa própria origin, e os outros endpoints padrão para um caminho sob ela:

Endpoint	Caminho padrão
HTTP API	`/api`
Media Proxy	`/media`
Aplicativo admin	`/admin`
Site de marketing	`/marketing`
Links de convite	`/invite`
Links de presente	`/gift`
Gateway	`/gateway`

O esquema do Gateway é ws ou wss. Uma porta que equivale ao padrão para seu esquema é omitida.

Uma implantação pode configurar um domínio separado de assets estáticos, de convite e de presente, e pode substituir qualquer endpoint por um override exato.

Exemplo

{
  "api": "https://api.example.com",
  "api_client": "https://api.example.com",
  "api_public": "https://public.example.com",
  "gateway": "wss://gateway.example.com",
  "media": "https://media.example.com",
  "static_cdn": "https://cdn.example.com",
  "marketing": "https://example.com",
  "admin": "https://admin.example.com",
  "invite": "https://example.com/invite",
  "gift": "https://example.com/gift",
  "webapp": "https://app.example.com"
}

Objeto de configuração de CAPTCHA

Qual provedor de CAPTCHA esta implantação usa e as chaves de site que um cliente precisa para renderizar o desafio.

Estrutura

Campo	Tipo	Descrição
provider¹	string	O provedor de CAPTCHA selecionado
hcaptcha_site_key²	?string	A chave de site hCaptcha configurada, ou null quando nenhuma está configurada
turnstile_site_key²	?string	A chave de site Turnstile configurada, ou null quando nenhuma está configurada

¹ O valor é none quando a chave de site ou secreta do provedor configurado está ausente

² Apenas a chave que corresponde a provider é não null, portanto ambas são null enquanto provider é none

Provedores de CAPTCHA

Valor	Descrição
none	A implantação não exige CAPTCHA
hcaptcha	Desafios hCaptcha protegem as operações que o requerem
turnstile	Desafios Cloudflare Turnstile protegem as operações que o requerem

O handshake completo de desafio, incluindo os cabeçalhos de requisição X-Captcha-Token e X-Captcha-Type, é definido em Tratamento de CAPTCHA.

Objeto de recursos de instância

Switches em toda a implantação que um cliente lê antes de oferecer um recurso, além de indicar se a implantação se define como auto-hospedada.

Estrutura

Campo	Tipo	Descrição
voice_enabled	boolean	Se chamadas de voz e vídeo estão habilitadas
stripe_enabled	boolean	Se o faturamento via Stripe está habilitado
self_hosted	boolean	Se esta implantação se identifica como auto-hospedada
presigned_attachment_uploads	boolean	Se um cliente pode solicitar URLs de upload de anexo pré-assinadas
emails_enabled¹	boolean	Se a implantação envia e-mail

¹ O valor é true apenas quando o e-mail está ativado e o transporte está completamente configurado

Uma implantação que reporta emails_enabled como false não envia verificação, recuperação de senha ou mensagem de autorização por IP, e os fluxos que dependem disso ficam inutilizáveis.

Objeto de provedor de GIF

O provedor de GIF que esta implantação vinculou e se um cliente mostra sua marca de atribuição.

Estrutura

Campo	Tipo	Descrição
provider	string	Nome de máquina estável do provedor de GIF ativo
display_name	string	Nome legível do provedor que um cliente exibe
attribution_required¹	boolean	Se um cliente deve exibir a atribuição do provedor

¹ Um cliente que renderiza resultados de GIF exibe a marca de atribuição do provedor ao lado deles quando este valor é true

Os campos descrevem o provedor que uma implantação vinculou mesmo quando a disponibilidade de serviço reporta gif_enabled como false. Um cliente lê gif_enabled para decidir se oferece o seletor. Uma implantação que não vinculou nenhum provedor de GIF ainda publica os valores padrão klipy, Klipy e false.

Objeto de política de registro

Quem pode registrar uma conta nesta implantação.

Estrutura

Campo	Tipo	Descrição
mode	string	O modo de registro
admin_registration_urls_enabled¹	boolean	Se um código de URL de registro emitido por administrador é aceito

¹ Quando true, Registrar uma conta aceita registration_url_code; um código válido admite registro mesmo enquanto mode é closed, e o requisito de aprovação próprio do código substitui o que o modo definiria

Modos de registro

Valor	Descrição
open	Qualquer pessoa pode se registrar e recebe uma sessão imediatamente
approval	O registro é bem-sucedido, mas a conta aguarda aprovação do administrador antes de poder entrar
closed	O registro público é recusado

Objeto de política de comunidade

Se esta implantação funciona como uma única comunidade e se mensagens diretas existem nela.

Estrutura

Campo	Tipo	Descrição
single_community	boolean	Se esta implantação funciona como uma única comunidade que toda conta ingressa
single_community_guild_id¹	?snowflake	O ID do servidor que toda conta ingressa no modo de comunidade única, ou null
direct_messages_disabled	boolean	Se mensagens diretas e pedidos de amizade estão desabilitados para toda a implantação

¹ O identificador é publicado apenas enquanto single_community é true e a implantação designou um servidor de comunidade

Objeto de disponibilidade de serviço

Cada campo indica se uma integração opcional está disponível nesta implantação.

Estrutura

Campo	Tipo	Descrição
gif_enabled	boolean	Se o seletor de GIF está disponível
youtube_enabled	boolean	Se o enriquecimento de links do YouTube está disponível
bluesky_enabled	boolean	Se conexões Bluesky estão disponíveis

Objeto de configuração de push

A identidade pública de Web Push desta implantação.

Estrutura

Campo	Tipo	Descrição
public_vapid_key¹	?string	A chave pública VAPID de Web Push da implantação, ou null

¹ Null quando a implantação não configurou nenhuma identidade de Web Push

Objeto de configuração de limites

As regras ordenadas que um cliente avalia para determinar os limites aplicáveis a uma conta ou servidor.

Estrutura

Campo	Tipo	Descrição
version	integer	A versão do formato de wire, sempre `2`
traitDefinitions¹	array[string]	Os nomes de traits que esta implantação declara
rules	array[regra de limite object]	As regras a avaliar
defaultsHash²	string	Um hash dos valores padrão de limite embutidos no release

¹ Uma configuração hospedada padrão publica o único nome premium, que é computado a partir do estado premium da conta

² O valor é computado apenas a partir dos valores padrão do release, portanto um operador editando uma regra não o altera. Ele muda quando um release altera os padrões, o que invalida uma resolução que um cliente armazenou em cache com os valores anteriores

Cada regra publica apenas as chaves cujos valores diferem dos padrões do release. Os próprios padrões não são publicados neste documento, portanto um cliente DEVE manter sua própria cópia deles. Antes de resolver qualquer coisa, um cliente DEVE também reconstruir cada regra em um mapa de limite completo, tomando o valor padrão de cada chave de limite e sobrepondo os overrides daquela regra.

O cliente começa com o valor padrão de cada chave. Avalia as regras do menos específico ao mais específico, onde a especificidade é o número total de nomes de trait e de recurso de servidor nos filtros de uma regra. Duas regras de igual especificidade mantêm sua ordem publicada. Uma regra corresponde quando todo trait que ela nomeia está presente no contexto de avaliação e todo recurso de servidor que ela nomeia está presente.

Uma regra que não nomeia nenhum trait nem recurso de servidor substitui o valor atual de cada chave que tem. Uma que nomeia pelo menos um eleva o valor atual ao seu próprio valor quando este é maior. Como uma regra reconstruída tem cada chave, uma regra não filtrada retorna cada chave que não substituiu ao padrão. Uma regra filtrada correspondente eleva cada chave que não substituiu ao menos ao padrão.

Os contextos de avaliação estão listados abaixo. Um cliente lê o escopo da chave e os filtros da regra para decidir quais chaves uma avaliação aplica. O registro de chaves de limite declara o escopo de cada chave.

Escopo	Avaliação do usuário	Avaliação do servidor
user	Aplicada	Aplicada apenas quando a regra não tem filtro de recurso de servidor
guild	Não aplicada	Aplicada quando a regra tem filtro de recurso de servidor, ou quando a regra não tem filtro de trait
both	Aplicada	Aplicada

Nada valida o filtro traits de uma regra contra traitDefinitions, portanto uma regra pode filtrar por um nome que aquela coleção omite. Uma implantação auto-hospedada cujo modo premium é everyone publica uma coleção vazia e não tem nenhuma regra que filtre por premium.

Objeto de regra de limite

Uma regra da configuração de limites, com os filtros que a selecionam e os valores que ela define.

Estrutura

Campo	Tipo	Descrição
id	string	O identificador estável da regra
filters?	filtros de limite object	As traits e recursos de servidor que selecionam a regra, omitido quando a regra sempre corresponde
overrides¹	map[string, integer]	Valores inteiros com chave por chave de limite

¹ Uma entrada cujo valor é negativo ou não é um número finito é ignorada quando a regra é aplicada

Exemplo

{
  "id": "premium",
  "filters": {"traits": ["premium"]},
  "overrides": {
    "max_message_length": 4000,
    "max_guild_emojis": 250
  }
}

Objeto de filtros de limite

As traits e recursos de servidor que uma regra de limite requer antes de corresponder.

Estrutura

Campo	Tipo	Descrição
traits?	array[string]	Nomes de traits que devem estar todos presentes para a regra corresponder
guildFeatures?	array[string]	Nomes de recursos de servidor que devem estar todos presentes para a regra corresponder

Uma coleção vazia ou omitida não impõe condição. Uma regra cujo objeto de filtros não tem nenhuma das coleções sempre corresponde, e substitui o valor atual de cada chave exatamente como uma regra que omite filters.

Chaves de limite

Cada chave nomeia um limite. Uma chave cujo nome começa com feature_ é um gate de recurso cujo valor é 0 quando o recurso está indisponível e 1 quando está disponível. O valor de toda outra chave é um limite na unidade nomeada por sua descrição.

Valor	Descrição
avatar_max_size	Tamanho máximo de arquivo para uploads de avatar em bytes, no escopo user
emoji_max_size	Tamanho máximo de arquivo para uploads de emoji em bytes, no escopo guild
feature_animated_avatar	Permitir uploads de avatar animado, no escopo user
feature_animated_banner	Permitir uploads de banner animado, no escopo user
feature_custom_discriminator	Permitir seleção de discriminador personalizado, no escopo user
feature_custom_notification_sounds	Permitir sons de notificação personalizados, no escopo user
feature_early_access	Acesso a recursos beta, no escopo user
feature_global_expressions	Usar expressões em todos os servidores, no escopo user
feature_higher_video_quality	Acesso a maior qualidade de transmissão de vídeo, no escopo user
feature_per_guild_profiles	Perfil diferente por servidor, no escopo user
feature_voice_entrance_sounds	Reproduzir som ao entrar em canal de voz, no escopo user
max_attachment_file_size	Tamanho máximo de cada arquivo de anexo em bytes, no escopo user e guild
max_attachments_per_message	Número máximo de anexos de arquivo por mensagem, no escopo user e guild
max_bio_length	Máximo de caracteres em uma biografia de usuário, no escopo user
max_bookmarks	Máximo de mensagens marcadas, no escopo user
max_channels_per_category	Máximo de canais por categoria, no escopo guild
max_custom_backgrounds	Máximo de fundos de perfil personalizados, no escopo user
max_embeds_per_message	Número máximo de embeds por mensagem, no escopo user e guild
max_favorite_meme_tags	Máximo de tags de meme a rastrear, no escopo user
max_favorite_memes	Máximo de memes marcados como favoritos, no escopo user
max_group_dm_recipients	Máximo de membros por mensagem direta em grupo, no escopo user
max_group_dms_per_user	Máximo de mensagens diretas em grupo que um usuário pode possuir, no escopo user
max_guild_channels	Máximo de canais por servidor, no escopo guild
max_guild_emojis	Máximo total de emojis por servidor, no escopo guild
max_guild_emojis_animated¹	Alias de compatibilidade para clientes mais antigos, no escopo guild
max_guild_emojis_animated_more¹	Alias de compatibilidade para clientes mais antigos, no escopo guild
max_guild_emojis_static¹	Alias de compatibilidade para clientes mais antigos, no escopo guild
max_guild_emojis_static_more¹	Alias de compatibilidade para clientes mais antigos, no escopo guild
max_guild_invites	Máximo de convites ativos por servidor, no escopo guild
max_guild_members	Máximo de membros por servidor, no escopo guild
max_guild_roles	Máximo de cargos por servidor, no escopo guild
max_guild_stickers	Máximo de stickers por servidor, no escopo guild
max_guild_stickers_more²	Alias de compatibilidade para clientes mais antigos, no escopo guild
max_guilds	Número máximo de servidores que um usuário pode entrar, no escopo user
max_message_length	Número máximo de caracteres por mensagem, no escopo user e guild
max_private_channels_per_user	Máximo de canais de mensagem direta por usuário, no escopo user
max_reactions_per_message	Máximo de reações distintas por mensagem, no escopo guild
max_relationships	Máximo de relacionamentos de amigos e bloqueados, no escopo user
max_users_per_message_reaction	Máximo de usuários que podem usar a mesma reação em uma mensagem, no escopo guild
max_voice_message_duration	Duração máxima de mensagem de voz em segundos, no escopo user e guild
max_webhooks_per_channel	Máximo de webhooks por canal, no escopo guild
max_webhooks_per_guild	Máximo de webhooks por servidor, no escopo guild
sticker_max_size	Tamanho máximo de arquivo para uploads de sticker em bytes, no escopo guild

¹ Os limites de emoji são aplicados como um total compartilhado contra max_guild_emojis, e os aliases existem apenas para clientes mais antigos. O padrão de cada alias é igual ao padrão de max_guild_emojis

² Os limites de sticker são aplicados como um total compartilhado contra max_guild_stickers

Onde uma regra define max_guild_emojis, max_guild_stickers ou um dos aliases de compatibilidade, ela republica aquela chave em seus próprios overrides mesmo quando o valor corresponde ao padrão.

Objeto de configuração pública de aplicação

Identidade visual, estado de configuração, documentos legais e campos de registro que um cliente lê antes de um acesso de conta.

Estrutura

Campo	Tipo	Descrição
branding	identidade visual pública object	Identidade pública da instância
setup	estado público de configuração object	Estado de configuração inicial
legal	configuração legal pública object	URLs de documentos legais de registro
registration	campos públicos de registro object	Política de coleta de campos de registro

Objeto de identidade visual pública

A identidade da instância que um cliente renderiza: seu nome, imagens, cor de tema e links de página de status.

Estrutura

Campo	Tipo	Descrição
product_name	string	O nome da instância configurado que um cliente exibe
icon_url	?string	URL completo do ícone da aplicação, ou null
symbol_url	?string	URL do símbolo compacto da aplicação, ou null
logo_url	?string	URL do logotipo da aplicação, ou null
wordmark_url	?string	URL da logomarca da aplicação, ou null
favicon_url	?string	URL do favicon do navegador, ou null
theme_color	?string	Cor de tema do navegador, ou null
status_page_url	?string	URL da página de status pública, ou null
status_page_incident_history_url	?string	URL do histórico de incidentes da página de status, ou null

Objeto de estado público de configuração

Se a implantação concluiu sua configuração inicial e onde um operador vai para continuá-la.

Estrutura

Campo	Tipo	Descrição
configured	boolean	Se a configuração inicial da implantação está completa
admin_url¹	?string	A URL do aplicativo admin usada para continuar a configuração, ou null

¹ O valor é o endpoint admin configurado da implantação, e é null quando nenhum endpoint admin está configurado

Objeto de configuração legal pública

As URLs públicas que um cliente vincula no formulário de registro.

Estrutura

Campo	Tipo	Descrição
terms_url	?string	URL pública dos termos de serviço, ou null
privacy_url	?string	URL pública da política de privacidade, ou null

Objeto de campos públicos de registro

Quais campos extras o registro público coleta.

Estrutura

Campo	Tipo	Descrição
collect_date_of_birth	boolean	Se o registro público coleta e valida uma data de nascimento

Objeto de geolocalização

A localização aproximada que o Decoding Chat resolveu para a requisição, junto com as regiões onde conteúdo adulto é restrito por verificação de idade ou está indisponível.

Estrutura

Campo	Tipo	Descrição
countryCode¹ ²	?string	O código de país ISO 3166-1 alpha-2 detectado, ou null
regionCode¹ ²	?string	O código de subdivisão ISO 3166-2 dentro do país detectado, ou null
latitude¹ ³	?string	A latitude aproximada, ou null
longitude¹ ³	?string	A longitude aproximada, ou null
ageRestrictedGeos	array[entrada geo object]	Localizações onde conteúdo adulto requer verificação de idade
ageBlockedGeos	array[entrada geo object]	Localizações onde conteúdo adulto está indisponível

¹ Todos os campos detectados são null quando a localização é desconhecida. Uma localização conhecida ainda pode omitir o código de subdivisão ou as coordenadas

² O valor é em maiúsculas

³ O valor é uma string decimal

As coleções geo são fixadas pelo release, portanto são idênticas em toda resposta. Um cliente resolve seu próprio país e subdivisão a partir dos campos detectados e então seleciona a entrada correspondente ele mesmo.

Exemplo

{
  "countryCode": "GB",
  "regionCode": "ENG",
  "latitude": "51.5074",
  "longitude": "-0.1278",
  "ageRestrictedGeos": [{"countryCode": "US", "regionCode": "TX"}],
  "ageBlockedGeos": []
}

Objeto de entrada geo

Uma entrada geo nomeia um país inteiro quando seu regionCode é null e nomeia uma subdivisão caso contrário.

Estrutura

Campo	Tipo	Descrição
countryCode	string	O código de país ISO 3166-1 alpha-2
regionCode	?string	O código de subdivisão ISO 3166-2 dentro do país, ou null quando a entrada cobre o país inteiro

Obter descoberta de instância

GET/.well-known/fluxer

Unauthenticated

Retorna o objeto de descoberta de instância descrevendo esta implantação.

O caminho não tem prefixo /v1.

Resposta

Status	Corpo	Condição
200	descoberta de instância object	O documento de descoberta foi retornado

Rate limit

60 requisições por minuto para cada usuário autenticado, ou para cada endereço IP do cliente quando a requisição não tem credencial, no bucket instance:info. Obter documento OpenAPI compartilha este bucket.

Obter geolocalização do cliente

GET/v1/ip

Unauthenticated

Retorna o objeto de geolocalização para o endereço do cliente da requisição.

Uma consulta que não resolve nada ainda retorna 200 com countryCode, regionCode, latitude e longitude todos null. Trate isso como localização desconhecida.

Resposta

Status	Corpo	Condição
200	geolocalização object	A localização foi resolvida, total, parcialmente ou não

Rate limit

30 requisições por minuto para cada usuário autenticado, ou para cada endereço IP do cliente quando a requisição não tem credencial, no bucket ip:geo_lookup.

Obter documento OpenAPI

GET/v1/openapi.json

Unauthenticated

Retorna o documento OpenAPI 3.1 da implantação como JSON com Content-Type: application/json; charset=utf-8.

O documento não tem ETag. Sua URL de servidor é o endpoint api_client da implantação seguido de /v1. Cada caminho é relativo a essa URL.

Resposta

Status	Corpo	Condição
200	documento OpenAPI 3.1	O documento foi retornado

Rate limit

60 requisições por minuto para cada usuário autenticado, ou para cada endereço IP do cliente quando a requisição não tem credencial, no bucket instance:info. A cota é compartilhada com Obter descoberta de instância.