Telegram publica el esquema OpenAPI para la Bot API

Telegram ha publicado la descripción de la Bot API en formato OpenAPI: un único archivo api.json enumera todos los métodos, objetos, respuestas y errores, así como las solicitudes que el propio Telegram envía al bot a través del webhook. Esto es relevante para desarrolladores de bots y autores de bibliotecas. Ahora se puede generar un cliente en cualquier lenguaje a partir del archivo oficial, en lugar de tener que parsear la página HTML de la documentación. El archivo se encuentra en corefork.telegram.org, donde se ha publicado la versión actualizada de la documentación, y describe la versión actual de la Bot API 10.3.

Qué es este archivo

OpenAPI (anteriormente conocido como Swagger) es un formato estándar en el que una interfaz HTTP se describe como datos: direcciones, parámetros, tipos de campos, códigos de respuesta. A partir de esta descripción, los generadores construyen bibliotecas cliente, los validadores comprueban las solicitudes y los editores dibujan documentación interactiva.

El archivo pesa 1,83 MB, y en su cabecera figuran "openapi": "3.2.0" y "version": "10.3". La revisión 3.2.0 es la más reciente del estándar, publicada el 19 de septiembre de 2025. Entre sus novedades, el esquema utiliza el campo $self con su propia dirección, servidores nombrados y una sección mediaTypes separada para cuerpos de respuesta repetidos.

Contenido, según un recuento directo del archivo:

Ocho de los 185 métodos no tienen parámetros, por lo que hay 177 conjuntos de parámetros. La descarga de archivos se describe como una operación downloadFile separada con su propio servidor api.telegram.org/file/bot{token}: en la documentación HTML, esto era un párrafo de prosa, no un método.

¿Coincide con la documentación?

El conjunto de métodos coincide completamente. De la página HTML core.telegram.org/bots/api se extraen 185 nombres de métodos, y del esquema, 185 operaciones; no hay discrepancias entre las listas.

Con los objetos es más complicado, porque actualmente hay dos versiones de la documentación. En el dominio principal se describen 400 objetos. En corefork.telegram.org/bots/api hay 429: 30 tipos de entrada más (InputRichText y sus variantes, InputInlineKeyboardMarkup, InputLocation y otros) y uno menos — RichBlockThinking, que en la versión actualizada desapareció de la lista de cambios de la Bot API 10.3. El esquema coincide con la versión de corefork: todos sus 429 objetos están en el archivo.

Además, hay 19 esquemas que solo están en el archivo. Son construcciones de servicio que no aparecen como objetos separados en la prosa: ocho respuestas de error (BadRequest, Unauthorized, TooManyRequests y otros), las uniones ChatId, ReplyMarkup, FileInput, UploadInput, y siete variantes de entrada de objetos existentes como InputMessageEntity e InputChatPermissions. La variante de entrada describe lo que el bot envía, no lo que recibe: los campos que el servidor rellena por sí mismo están ausentes en ella.

Cómo se describen las uniones y los archivos

Lo más difícil para quienes antes analizaban HTML son los lugares donde un mismo campo acepta varios tipos. En el esquema, se describen de forma legible por máquina.

Uniones con discriminador. ChatMember es un oneOf de seis variantes, y el campo status elige la variante: creator lleva a ChatMemberOwner, kicked a ChatMemberBanned. De la misma manera están estructurados MessageOrigin, InputMedia, BotCommandScope, ReactionType y otros 17 tipos. Un generador, a partir de esta descripción, construye un tipo-suma real, no un objeto con todos los campos a la vez.

Archivos. InputFile se describe como contenido binario con el tipo application/octet-stream. El campo de la foto en sendPhoto no se refiere directamente a él, sino a FileInput: esto es un archivo a subir o una cadena no vacía — file_id o URL. Para adjuntos en álbumes existe UploadInput: un archivo o una cadena del tipo attach://<nombre>. El cuerpo de sendPhoto se declara como multipart/form-data, y todos los campos adicionales a los parámetros del método están permitidos si son archivos. Así se describe la técnica en la que un archivo para attach:// llega como una parte separada del formulario. Los campos anidados como caption_entities dentro del formulario se marcan como JSON.

Respuestas. Cada método responde con un envoltorio {"ok": true, "result": …}, y el tipo de result se especifica para cada método por separado. Los errores se desglosan por códigos: para sendPhoto son 400, 401, 403, 421, 429 y 500.

Qué más describe el esquema además de la documentación

El webhook se describe como una operación receiveUpdate separada. Telegram envía la actualización y puede firmar la solicitud con el encabezado X-Telegram-Bot-Api-Secret-Token o con autenticación básica desde la URL; ambos métodos se declaran como esquemas de seguridad. Como respuesta al webhook, el bot puede invocar un método directamente, y en el esquema esto es una unión de todos los métodos permitidos con el campo method. Los métodos cuyo nombre comienza con get, así como setWebhook, deleteWebhook, close y logOut, no se pueden invocar de esta manera.

23 enlaces (links) describen a dónde se transfiere el resultado de una operación. El file_id de una animación de un mensaje se puede pasar a sendAnimation, y el file_path de getFile se puede dividir por la barra diagonal en dos partes de la dirección downloadFile. Para la división, Telegram ha creado su propia extensión x-split-parameters, el único campo no estándar en todo el archivo.

Qué considerar al generar un cliente

En la página actualizada de corefork han aparecido tres secciones que aún no están en el dominio principal. Las tres se refieren a las discrepancias entre el esquema y el comportamiento del servidor.

Identificadores de 64 bits — cadenas. Los identificadores de emojis personalizados, regalos, solicitudes de callback y solicitudes inline, la Bot API los devuelve como cadenas, y también deben pasarse como cadenas. En el esquema, por ejemplo, CallbackQuery.id, Sticker.custom_emoji_id y Gift.id tienen el tipo string. Los identificadores numéricos de usuarios y chats siguen siendo enteros en formato int64, aunque según la documentación no tienen más de 52 bits significativos.

El límite de longitud del texto se calcula después de analizar el marcado. maxLength del texto del mensaje es 4096, pero el servidor cuenta los caracteres ya sin el marcado HTML o Markdown. El validador del esquema los cuenta tal cual en la cadena. Un texto de 4100 caracteres con etiquetas será aceptado por el servidor, pero un validador estricto lo rechazará, por lo que para los campos que se envían con parse_mode, la verificación de longitud según el esquema debería desactivarse.

Los errores se encuentran en un archivo separado. Junto al esquema ha aparecido errors.json: para cada error, una lista de los métodos que pueden devolverlo. El archivo es de la versión 10.3, capa MTProto 227 y 945 descripciones de errores: 901 con código 400, 31 con código 500, 12 con código 403 y uno con 429. Se mapean por separado 343 errores de MTProto. La documentación advierte que los textos de error pueden cambiar en cualquier momento, por lo que la lista sirve de referencia, pero no para comparar cadenas en el código.

La versión 3.2 del estándar salió hace un año. Es mejor verificar si un generador específico soporta mediaTypes en los componentes y el resto de sus novedades antes de migrar una biblioteca de trabajo al esquema.

Dónde se encuentra el archivo y desde cuándo

El esquema solo se sirve desde corefork.telegram.org. El campo $self dentro de él apunta a core.telegram.org/bots/api.json, pero el 13 de octubre, esa dirección muestra una página de "Page not found", al igual que la dirección errors.json en el dominio principal. La documentación HTML principal aún no menciona el esquema.

No hay fecha de publicación en la respuesta del servidor: no devuelve el encabezado Last-Modified, el archivo se cachea durante cinco minutos y está cerrado a la indexación por el encabezado X-Robots-Tag: noindex. La primera copia en el archivo web está fechada el 9 de octubre de 2026, 10:16 UTC.

En la cabecera del esquema se indica que tanto la documentación como el esquema se generan con un generador publicado junto con el código fuente del servidor de la Bot API. A 13 de octubre, el enlace lleva a una carpeta inexistente: en el repositorio tdlib/telegram-bot-api no hay un directorio generator. El último commit allí está fechado el 25 de agosto, un día antes la versión del servidor subió a 10.3.

Qué se usaba antes

Anteriormente, la Bot API no tenía un esquema oficial legible por máquina, y la comunidad lo construía por sí misma a partir de la página HTML. El ejemplo más conocido es telegram-bot-api-spec: un script analiza la documentación cada día y publica un JSON con métodos, campos y subtipos. En su versión actual, la Bot API 10.3, 185 métodos y 400 objetos. Parsers y generadores similares se encuentran en tg-bot-api, y un archivo de esquemas de versiones antiguas se guarda en telegram-bot-api-versions.

El análisis HTML se basaba en la prosa: en la palabra «Optional» al inicio de la descripción de un campo, en las palabras «or» entre tipos y en el orden de las tablas. Una modificación en el formato de la documentación podría romper dicho analizador sin que hubiera un solo cambio en la propia API. El archivo oficial traslada esta tarea a Telegram: los discriminadores de los tipos unión, la obligatoriedad de los campos, los límites de longitud y los códigos de error ahora se definen en el esquema, en lugar de inferirse del texto.