Telegram Publicou o Esquema OpenAPI para a Bot API

O Telegram disponibilizou a descrição da Bot API no formato OpenAPI: um único arquivo api.json lista todos os métodos, objetos, respostas e erros, bem como as requisições que o próprio Telegram envia ao bot via webhook. Isso é relevante para desenvolvedores de bots e autores de bibliotecas. Agora, um cliente em qualquer linguagem pode ser gerado a partir do arquivo oficial, em vez de ter que ser extraído de uma página HTML de documentação. O arquivo está hospedado em corefork.telegram.org, onde a versão atualizada da documentação está disponível, e descreve a versão atual da Bot API 10.3.

O que é este arquivo

OpenAPI (anteriormente conhecido como Swagger) é um formato padrão no qual uma interface HTTP é descrita como dados: endereços, parâmetros, tipos de campos e códigos de resposta. Com base nessa descrição, geradores constroem bibliotecas cliente, validadores verificam requisições e editores criam documentação interativa.

O arquivo pesa 1,83 MB e, em seu cabeçalho, constam "openapi": "3.2.0" e "version": "10.3". A revisão 3.2.0 é a mais recente do padrão, tendo sido publicada em 19 de setembro de 2025. Entre suas inovações, o esquema utiliza o campo $self com seu próprio endereço, servidores nomeados e uma seção mediaTypes separada para corpos de resposta repetitivos.

O que há dentro, de acordo com uma contagem direta do arquivo:

Oito dos 185 métodos não possuem parâmetros, por isso há 177 conjuntos de parâmetros. O download de arquivos é descrito como uma operação downloadFile separada, com seu próprio servidor api.telegram.org/file/bot{token}: na documentação HTML, isso era um parágrafo em prosa, não um método.

Coincide com a documentação?

O conjunto de métodos coincide completamente. Da página HTML core.telegram.org/bots/api, são extraídos 185 nomes de métodos; do esquema, 185 operações, e não há divergências entre as listas.

Com os objetos, a situação é mais complexa, pois atualmente existem duas versões da documentação. No domínio principal, 400 objetos são descritos. Em corefork.telegram.org/bots/api, são 429: 30 tipos de entrada a mais (InputRichText e suas variantes, InputInlineKeyboardMarkup, InputLocation e outros) e um a menos — RichBlockThinking, que desapareceu da lista de mudanças da Bot API 10.3 na versão atualizada. O esquema coincide com a versão corefork: todos os seus 429 objetos estão no arquivo.

Outros 19 esquemas existem apenas no arquivo. São construções de serviço que não aparecem como objetos separados na prosa: oito respostas de erro (BadRequest, Unauthorized, TooManyRequests e outros), as uniões ChatId, ReplyMarkup, FileInput, UploadInput, e sete variantes de entrada de objetos existentes, como InputMessageEntity e InputChatPermissions. A variante de entrada descreve o que o bot envia, e não o que recebe: campos que o servidor preenche automaticamente estão ausentes nela.

Como as uniões e arquivos são descritos

A parte mais difícil para quem antes analisava o HTML são os locais onde um campo aceita vários tipos. No esquema, eles são descritos de forma legível por máquina.

Uniões com discriminador. ChatMember é um oneOf de seis variantes, e o campo status seleciona a variante: creator leva a ChatMemberOwner, kicked leva a ChatMemberBanned. MessageOrigin, InputMedia, BotCommandScope, ReactionType e outros 17 tipos são estruturados da mesma forma. Um gerador, a partir dessa descrição, constrói um tipo-soma real, e não um objeto com todos os campos de uma vez.

Arquivos. InputFile é descrito como conteúdo binário com o tipo application/octet-stream. O campo de foto em sendPhoto não se refere diretamente a ele, mas a FileInput: que é um arquivo a ser enviado ou uma string não vazia — file_id ou URL. Para anexos em álbuns, existe UploadInput: um arquivo ou uma string no formato attach://<nome>. O corpo de sendPhoto é declarado como multipart/form-data, e todos os campos além dos parâmetros do método são permitidos, se forem arquivos. Isso descreve o mecanismo em que um arquivo para attach:// chega como uma parte separada do formulário. Campos aninhados como caption_entities dentro do formulário são marcados como JSON.

Respostas. Cada método responde com um envelope {"ok": true, "result": …}, e o tipo result é especificado para cada método separadamente. Os erros são categorizados por códigos: para sendPhoto, são 400, 401, 403, 421, 429 e 500.

O que mais o esquema descreve além da documentação

O webhook é descrito como uma operação receiveUpdate separada. O Telegram envia a atualização e pode assinar a requisição com o cabeçalho X-Telegram-Bot-Api-Secret-Token ou com autenticação básica da URL; ambos os métodos são declarados como esquemas de segurança. Em resposta ao webhook, o bot pode invocar um método imediatamente, e no esquema isso é uma união de todos os métodos permitidos com o campo method. Métodos cujo nome começa com get, bem como setWebhook, deleteWebhook, close e logOut, não podem ser invocados dessa forma.

23 ligações (links) descrevem para onde o resultado de uma operação é transmitido. O file_id de uma animação de uma mensagem pode ser passado para sendAnimation, e o file_path de getFile pode ser dividido por uma barra em duas partes do endereço downloadFile. Para a divisão, o Telegram criou sua própria extensão x-split-parameters — o único campo não padrão em todo o arquivo.

O que considerar ao gerar um cliente

Na página atualizada do corefork, apareceram três seções que ainda não estão no domínio principal. Todas as três sezem respeito às divergências entre o esquema e o comportamento do servidor.

Identificadores de 64 bits — strings. Os identificadores de emojis personalizados, presentes, requisições de callback e requisições inline da Bot API são retornados como strings, e devem ser passados também como strings. No esquema, por exemplo, CallbackQuery.id, Sticker.custom_emoji_id e Gift.id têm o tipo string. Os identificadores numéricos de usuários e chats permanecem inteiros no formato int64, embora, de acordo com a documentação, não tenham mais de 52 bits significativos.

O limite de comprimento do texto é calculado após a análise da marcação. O maxLength do texto da mensagem é 4096, mas o servidor conta os caracteres já sem a marcação HTML ou Markdown. O validador do esquema os conta na string como está. Um texto de 4100 caracteres com tags será aceito pelo servidor, mas um validador estrito o rejeitará, portanto, para campos que são enviados com parse_mode, a verificação de comprimento pelo esquema deve ser desativada.

Os erros estão em um arquivo separado. Ao lado do esquema, apareceu errors.json: para cada erro, há uma lista de métodos que podem retorná-lo. No arquivo, a versão é 10.3, a camada MTProto 227 e 945 descrições de erros: 901 com código 400, 31 com código 500, 12 com código 403 e um com 429. Separadamente, 343 erros MTProto são mapeados. A documentação ressalta que os textos dos erros podem mudar a qualquer momento, portanto, a lista serve como referência, mas não para comparação de strings no código.

A versão 3.2 do padrão foi lançada há um ano. É melhor verificar se um gerador específico suporta mediaTypes nos componentes e suas outras inovações antes de migrar uma biblioteca de trabalho para o esquema.

Onde o arquivo está e desde quando

O esquema é fornecido apenas por corefork.telegram.org. O campo $self dentro dele aponta para core.telegram.org/bots/api.json, mas em 13 de outubro, este endereço exibe a página "Page not found", assim como o endereço errors.json no domínio principal. A documentação HTML principal ainda não menciona o esquema.

Não há data de publicação na resposta do servidor: ele não retorna o cabeçalho Last-Modified, o arquivo é armazenado em cache por cinco minutos e está fechado para indexação pelo cabeçalho X-Robots-Tag: noindex. A primeira cópia no arquivo da web data de 9 de outubro de 2026, 10:16 UTC.

No cabeçalho do esquema, é dito que tanto a documentação quanto o esquema são gerados por um gerador que é publicado junto com o código-fonte do servidor da Bot API. Em 13 de outubro, o link leva a uma pasta inexistente: no repositório tdlib/telegram-bot-api, não há um diretório generator. O último commit lá data de 25 de agosto, um dia antes a versão do servidor subiu para 10.3.

O que era usado antes

Não havia um esquema oficial legível por máquina para a Bot API antes, e a comunidade o montava a partir da página HTML. O exemplo mais conhecido é telegram-bot-api-spec: um script analisa a documentação diariamente e publica um JSON com métodos, campos e subtipos. Em sua versão atual, a Bot API 10.3, 185 métodos e 400 objetos. Parsers e geradores semelhantes existem em tg-bot-api, e um arquivo de esquemas para versões antigas é armazenado em telegram-bot-api-versions.

A análise do HTML dependia da prosa: a palavra "Optional" no início da descrição de um campo, o uso de "or" entre os tipos e a ordem das tabelas. Uma alteração na formatação da documentação poderia quebrar esse parser, mesmo sem nenhuma mudança no próprio API. O arquivo oficial transfere essa responsabilidade para o Telegram: os discriminadores de uniões, a obrigatoriedade dos campos, os limites de comprimento e os códigos de erro agora são especificados no esquema, em vez de serem inferidos do texto.