Desenrolar

Desenrolar (unfurl) resolve uma URL na prévia que uma mensagem mostraria para ela. Essa prévia é um array de objetos embed, os mesmos objetos que a rota comum de mensagens anexa.

A rota é apenas para usuários. O Decoding Chat rejeita um token de bot e uma credencial bearer OAuth2 com 403 ACCESS_DENIED.

Site resolvers

A tabela abaixo lista cada resolvedor de site. Se um site produz uma prévia depende do site, e os resolvedores do Klipy e do YouTube também exigem uma chave de API configurada na instância. Outras URLs públicas podem produzir prévias a partir dos metadados de suas páginas ou conteúdo de mídia.

Site	Matched URL
Hacker News¹	`news.ycombinator.com` com um caminho começando em `/item`
Klipy²³	`klipy.com` e `www.klipy.com`
Tenor	`tenor.com`
xkcd	`xkcd.com`
YouTube²⁴	`youtube.com`, `www.youtube.com`, `m.youtube.com`, `music.youtube.com`, `youtube-nocookie.com`, `www.youtube-nocookie.com` e `youtu.be`
Wikipedia⁵	`wikipedia.org`, `www.wikipedia.org` e os hosts de idioma `en`, `de`, `fr`, `es`, `it`, `ja`, `ru` e `zh`, com um caminho começando em `/wiki/`
Bluesky⁶	`bsky.app`
FxTwitter⁷	`fxtwitter.com`, `fixupx.com`, `twittpr.com`, `xfixup.com` e qualquer subdomínio destes
Generic⁸	Todas as URLs

¹ O identificador do item é lido do parâmetro de consulta id, e uma URL que não tem nenhum não produz embed

² As URLs de prévia do Klipy e do YouTube usam sua forma canônica de provedor

³ Exige que a instância tenha uma chave de API do Klipy configurada e não produz nada sem uma

⁴ A URL possui um identificador de vídeo de 6 a 15 caracteres retirados de A-Za-z0-9_-, e a instância precisa de uma chave da API de Dados do YouTube configurada

⁵ Um host cujo subdomínio de idioma está fora do conjunto suportado não corresponde, e o título do artigo é retirado do caminho após /wiki/

⁶ Resolve a URL de uma postagem e a URL de um perfil. Qualquer outro caminho no host não produz embed

⁷ Apenas os domínios espelho. twitter.com e x.com não correspondem a este resolvedor e caem no genérico

⁸ Constrói um embed de mídia direto quando a resposta é uma imagem, vídeo ou recurso de áudio. Uma resposta final cujo status não seja 200 não produz embed

Um embed resolvido tem no máximo um embed aninhado em children, e um embed aninhado não tem children próprios.

Network policy

O Decoding Chat aplica sua política de rede antes de cada busca e novamente para cada alvo de redirecionamento. Ele recusa uma URL por qualquer um destes motivos:

A URL está vazia, excede 8192 caracteres ou contém um caractere de controle.
O esquema não é HTTP nem HTTPS.
A URL possui informações de usuário.
A porta é 0.
O host não é um nome de host público válido.
O host resolve para um loopback, privado, link-local ou outro endereço reservado.
O host não resolve para nenhum endereço.

A resolução tem um prazo de 12 segundos. Uma busca falha em um loop de redirecionamento, mais de cinco redirecionamentos ou um documento maior que 8 MiB.

Uma busca recusada ou com falha não falha a operação por si só. Quando o Decoding Chat não produz nenhum embed, a resposta é 200 com um array vazio.

Cache behaviour

Este endpoint não lê resultados em cache e resolve a URL novamente. Uma mensagem pode mostrar uma prévia em cache para a mesma URL ou receber sua prévia posteriormente em uma atualização de mensagem.

Resolve URL embeds

POST/v1/unfurl

Resolve a URL fornecida. Retorna um array de objetos embed, vazio quando nenhum resolvedor produz um. Apenas para usuário.

Nenhuma permissão se aplica.

JSON body

Field	Type	Description
url¹²³	string	URL HTTP ou HTTPS absoluta (1-2048 caracteres)

¹ Cortado antes de ter seu comprimento medido

² Um valor normalizado fora de 1 a 2048 caracteres tem o código de validação URL_LENGTH_INVALID, e qualquer outra rejeição neste limite tem INVALID_URL_FORMAT

³ O valor começa com http:// ou https://. O Decoding Chat rejeita um valor que tenha credenciais incorporadas, omita um host, use uma forma relativa ao protocolo ou termine seu host com um ponto final

Fora de uma instância de desenvolvimento, o Decoding Chat também rejeita uma URL que omite um domínio de nível superior.

A mídia explícita pode carregar CONTAINS_EXPLICIT_MEDIA em suas flags. A mídia do Klipy não é classificada. As prévias de mensagens em canais que permitem mídia explícita podem ter flags diferentes.

Response

Status	Body	Condition
200	array[objeto embed]	Resolução concluída, possivelmente sem embed
403	error response	O chamador é um bot ou apresenta uma credencial bearer e a solicitação retorna `ACCESS_DENIED`, ou a conta tem uma ação obrigatória pendente e a solicitação retorna `ACCOUNT_SUSPICIOUS_ACTIVITY`
502	error response	O serviço de resolução relata uma falha, ou responde com um payload que a API não pode ler, e a solicitação retorna `BAD_GATEWAY`
503	error response	Nenhum serviço de resolução está respondendo, ou o serviço rejeita a solicitação em seu limite de simultaneidade, e a solicitação retorna `SERVICE_UNAVAILABLE`
504	error response	O serviço de resolução não responde dentro de seu prazo de 12 segundos e a solicitação retorna `GATEWAY_TIMEOUT`

Side effects

A resolução pode buscar a URL e sua mídia vinculada. Ela não cria nenhuma mensagem.

Rate limit

10 solicitações por minuto para cada usuário autenticado, no bucket unfurl:debug. O Decoding Chat cobra o bucket antes de verificar a credencial e o vincula ao endereço do chamador quando nenhuma credencial válida está presente. Portanto, um chamador não autenticado o consome e recebe 429 RATE_LIMITED quando ele se esgota, não 401.