Telegram đã công bố lược đồ OpenAPI cho Bot API

Telegram đã phát hành mô tả Bot API dưới định dạng OpenAPI. Một tệp api.json liệt kê tất cả các phương thức, đối tượng, phản hồi và lỗi, cũng như các yêu cầu mà chính Telegram gửi đến bot qua webhook. Điều này có ý nghĩa quan trọng đối với các nhà phát triển bot và tác giả thư viện. Giờ đây, một client bằng bất kỳ ngôn ngữ nào cũng có thể được tạo ra từ tệp chính thức này, thay vì từ một trang tài liệu HTML đã được phân tích cú pháp. Tệp này nằm trên corefork.telegram.org, nơi phiên bản tài liệu cập nhật được phát hành, và mô tả phiên bản Bot API 10.3 hiện tại.

Tệp này là gì

OpenAPI (trước đây gọi là Swagger) là một định dạng tiêu chuẩn, trong đó giao diện HTTP được mô tả dưới dạng dữ liệu, bao gồm địa chỉ, tham số, kiểu trường và mã phản hồi. Dựa trên mô tả này, các trình tạo (code generator) có thể xây dựng thư viện client, các trình xác thực kiểm tra yêu cầu, và các trình soạn thảo tạo tài liệu tương tác.

Tệp có kích thước 1,83 MB, với các trường "openapi": "3.2.0" và "version": "10.3" ở phần đầu. Bản sửa đổi 3.2.0 là phiên bản mới nhất của tiêu chuẩn, được công bố vào ngày 19 tháng 9 năm 2025. Trong số các tính năng mới, lược đồ này sử dụng trường $self với địa chỉ riêng, các máy chủ được đặt tên và một phần mediaTypes riêng biệt cho các phần thân phản hồi lặp lại.

Nội dung bên trong, theo thống kê trực tiếp từ tệp:

Có tám phương thức trong số 185 không có tham số, do đó có 177 tập hợp tham số. Việc tải xuống tệp được mô tả là một hoạt động downloadFile riêng biệt với máy chủ api.telegram.org/file/bot{token} của riêng nó: trong tài liệu HTML, đây là một đoạn văn xuôi chứ không phải một phương thức.

Có khớp với tài liệu không

Tập hợp các phương thức khớp hoàn toàn. Từ trang HTML core.telegram.org/bots/api có thể trích xuất 185 tên phương thức, từ lược đồ cũng có 185 hoạt động, và không có sự khác biệt nào giữa các danh sách.

Với các đối tượng thì phức tạp hơn, vì hiện có hai phiên bản tài liệu. Trên miền chính, có 400 đối tượng được mô tả. Trên corefork.telegram.org/bots/api có 429: nhiều hơn 30 kiểu đầu vào (InputRichText và các biến thể của nó, InputInlineKeyboardMarkup, InputLocation và các loại khác) và ít hơn một đối tượng — RichBlockThinking, đã biến mất khỏi danh sách thay đổi của Bot API 10.3 trong phiên bản cập nhật. Lược đồ khớp với phiên bản corefork: tất cả 429 đối tượng của nó đều có trong tệp.

Có thêm 19 lược đồ chỉ có trong tệp. Đây là các cấu trúc dịch vụ không tồn tại dưới dạng các đối tượng riêng biệt trong văn xuôi: tám phản hồi lỗi (BadRequest, Unauthorized, TooManyRequests và các lỗi khác), các kiểu hợp nhất ChatId, ReplyMarkup, FileInput, UploadInput, và bảy biến thể đầu vào của các đối tượng hiện có như InputMessageEntity và InputChatPermissions. Biến thể đầu vào mô tả những gì bot gửi, chứ không phải những gì nó nhận: các trường mà máy chủ tự điền sẽ không có trong đó.

Các kiểu hợp nhất và tệp được mô tả như thế nào

Điều khó khăn nhất đối với những người trước đây đã phân tích HTML là những nơi mà một trường chấp nhận nhiều kiểu. Trong lược đồ, chúng được mô tả bằng máy.

Các kiểu hợp nhất với trường phân biệt (discriminator). ChatMember là một oneOf của sáu biến thể, và trường status chọn biến thể: creator dẫn đến ChatMemberOwner, kicked dẫn đến ChatMemberBanned. MessageOrigin, InputMedia, BotCommandScope, ReactionType và 17 kiểu khác cũng được cấu trúc tương tự. Một trình tạo (code generator) dựa trên mô tả này sẽ xây dựng một kiểu-tổng (sum type) thực sự, chứ không phải một đối tượng với tất cả các trường cùng một lúc.

Tệp. InputFile được mô tả là nội dung nhị phân với kiểu application/octet-stream. Trường ảnh trong sendPhoto không trực tiếp tham chiếu đến nó, mà tham chiếu đến FileInput: đây có thể là một tệp được tải lên, hoặc một chuỗi không rỗng — file_id hoặc URL. Đối với tệp đính kèm trong album, có UploadInput: tệp hoặc chuỗi có dạng attach://<tên>. Phần thân của sendPhoto được khai báo là multipart/form-data, và tất cả các trường ngoài tham số phương thức đều được phép, nếu đó là tệp. Đây là cách mô tả việc một tệp cho attach:// được gửi dưới dạng một phần riêng biệt của biểu mẫu. Các trường lồng nhau như caption_entities bên trong biểu mẫu được đánh dấu là JSON.

Phản hồi. Mỗi phương thức trả về một phong bì {"ok": true, "result": …}, và kiểu result được chỉ định riêng cho từng phương thức. Các lỗi được phân loại theo mã: đối với sendPhoto là 400, 401, 403, 421, 429 và 500.

Những điều cần lưu ý khi tạo client

Trên trang corefork cập nhật, đã xuất hiện ba phần mà hiện chưa có trên miền chính. Cả ba đều liên quan đến sự khác biệt giữa lược đồ và hành vi của máy chủ.

ID 64-bit — là chuỗi. ID của emoji tùy chỉnh, quà tặng, yêu cầu callback và yêu cầu inline được Bot API trả về dưới dạng chuỗi, và bạn cũng cần truyền chúng dưới dạng chuỗi. Trong lược đồ, ví dụ, CallbackQuery.id, Sticker.custom_emoji_id và Gift.id có kiểu string. ID số của người dùng và cuộc trò chuyện vẫn là số nguyên định dạng int64, mặc dù theo tài liệu, chúng không có quá 52 bit có nghĩa.

Giới hạn độ dài văn bản được tính sau khi phân tích cú pháp đánh dấu. maxLength của văn bản tin nhắn là 4096, nhưng máy chủ tính các ký tự mà không có đánh dấu HTML hoặc Markdown. Trình xác thực lược đồ tính chúng theo chuỗi như hiện có. Một văn bản 4100 ký tự có thẻ sẽ được máy chủ chấp nhận, nhưng trình xác thực nghiêm ngặt sẽ từ chối, vì vậy đối với các trường được gửi với parse_mode, nên tắt kiểm tra độ dài theo lược đồ.

Các lỗi nằm trong một tệp riêng. Bên cạnh lược đồ, đã xuất hiện errors.json: đối với mỗi lỗi — danh sách các phương thức có thể trả về lỗi đó. Trong tệp là phiên bản 10.3, lớp MTProto 227 và 945 mô tả lỗi: 901 với mã 400, 31 với mã 500, 12 với mã 403 và một với 429. 343 lỗi MTProto được ánh xạ riêng. Tài liệu lưu ý rằng văn bản lỗi có thể thay đổi bất cứ lúc nào, vì vậy danh sách này phù hợp để tham khảo, nhưng không dùng để so sánh chuỗi trong mã.

Phiên bản 3.2 của tiêu chuẩn đã ra mắt một năm trước. Tốt hơn hết là nên kiểm tra xem một trình tạo cụ thể có hỗ trợ mediaTypes trong các thành phần và các tính năng mới khác của nó hay không, trước khi chuyển một thư viện đang hoạt động sang lược đồ này.

Tệp nằm ở đâu và từ khi nào

Lược đồ chỉ được cung cấp từ corefork.telegram.org. Trường $self bên trong nó trỏ đến core.telegram.org/bots/api.json, nhưng vào ngày 13 tháng 10, địa chỉ này hiển thị trang "Page not found", tương tự như địa chỉ errors.json trên miền chính. Tài liệu HTML chính hiện chưa đề cập đến lược đồ này.

Không có ngày xuất bản trong phản hồi của máy chủ: nó không trả về tiêu đề Last-Modified, tệp được lưu vào bộ nhớ cache trong năm phút và bị chặn lập chỉ mục bởi tiêu đề X-Robots-Tag: noindex. Bản sao đầu tiên trong kho lưu trữ web có ngày 9 tháng 10 năm 2026, 10:16 UTC.

Ở phần đầu lược đồ có ghi rằng cả tài liệu và lược đồ đều được tạo bởi một trình tạo (code generator) được phát hành cùng với mã nguồn của máy chủ Bot API. Vào ngày 13 tháng 10, liên kết này dẫn đến một thư mục không tồn tại: trong kho lưu trữ tdlib/telegram-bot-api không có thư mục generator. Lần commit cuối cùng ở đó là vào ngày 25 tháng 8, một ngày trước đó phiên bản máy chủ đã nâng cấp lên 10.3.

Những gì đã được sử dụng trước đây

Trước đây, Bot API không có lược đồ chính thức có thể đọc bằng máy, và cộng đồng đã tự xây dựng nó từ trang HTML. Ví dụ nổi tiếng nhất là telegram-bot-api-spec: một script hàng ngày phân tích tài liệu và xuất ra JSON với các phương thức, trường và kiểu con. Trong phiên bản hiện tại của nó, Bot API 10.3 có 185 phương thức và 400 đối tượng. Các trình phân tích cú pháp và trình tạo tương tự có trong tg-bot-api, và một kho lưu trữ các lược đồ theo các phiên bản cũ được lưu trữ trong telegram-bot-api-versions.

Việc phân tích cú pháp HTML dựa vào văn xuôi: từ "Optional" ở đầu mô tả trường, các từ "or" giữa các kiểu dữ liệu, và thứ tự của các bảng. Việc chỉnh sửa bố cục tài liệu có thể làm hỏng trình phân tích cú pháp như vậy mà không cần bất kỳ thay đổi nào trong chính API. Tệp chính thức chuyển công việc này sang phía Telegram: các discriminator của các kiểu hợp nhất, tính bắt buộc của các trường, giới hạn độ dài và mã lỗi giờ đây được định nghĩa trong lược đồ, chứ không phải suy ra từ văn bản.