TELEGRAM BOT API REFERENCE Core Methods, Types, Messaging, Files, Forum Topics, and Streaming Written February 27, 2026 This document is a comprehensive reference for the Telegram Bot API as of late February 2026 (Bot API 9.4, released February 9, 2026), covering authentication, receiving updates, sending and editing messages, uploading and downloading files, managing forum topics and threaded conversations in private chats, the streaming draft system, inline keyboards, callback queries, chat administration, and enough practical detail that a developer could begin building a bot without consulting any other source. The information here was compiled from Telegram's official Bot API documentation at core.telegram.org/bots/api. Types and methods are presented in logical groups rather than alphabetical order, with the most commonly needed material first. THE API ENDPOINT AND AUTHENTICATION Every bot is identified by a token issued by @BotFather when the bot is created. A token looks like 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11 and is the only credential required to authenticate. All requests go to: https://api.telegram.org/bot/METHOD_NAME For example: https://api.telegram.org/bot123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11/getMe Both GET and POST are supported. Parameters can be passed as a URL query string, as application/x-www-form-urlencoded, as application/json (except when uploading files), or as multipart/form-data (required for file uploads). All methods are case-insensitive. All queries must be UTF-8. Every response is a JSON object with a Boolean field "ok". If ok is true, the result is in the "result" field. If ok is false, the error is in the "description" field with an "error_code" integer. Some errors include a "parameters" field of type ResponseParameters containing either a migrate_to_chat_id (the group was upgraded to a supergroup with that ID) or retry_after (seconds to wait before retrying due to flood control). A minimal curl request: curl https://api.telegram.org/bot/sendMessage \ -H "Content-Type: application/json" \ -d '{"chat_id": 12345678, "text": "Hello from RMS."}' GETTING UPDATES There are two mutually exclusive ways to receive incoming updates: long polling via getUpdates, or webhooks via setWebhook. Updates are stored on Telegram's servers for up to 24 hours until the bot retrieves them. getUpdates Receives incoming updates via long polling. Returns an Array of Update objects. Parameter Type Required Description offset Integer Optional ID of the first update to return. Must be greater by one than the highest update_id previously received. Negative offsets retrieve from the end of the queue. All earlier updates are forgotten once offset is set. limit Integer Optional Number of updates to retrieve, 1-100. Defaults to 100. timeout Integer Optional Long polling timeout in seconds. Defaults to 0 (short polling, for testing only). Should be positive in production. allowed_updates Array of String Optional JSON-serialized list of update types to receive. Example: ["message", "callback_query"]. Default: all types except chat_member, message_reaction, and message_reaction_count. This method does not work if an outgoing webhook is set. After each response, recalculate offset to avoid duplicates. setWebhook Registers an HTTPS URL to receive updates via POST requests containing JSON-serialized Update objects. Returns True on success. Parameter Type Required Description url String Yes HTTPS URL. Empty string removes the webhook. certificate InputFile Optional Public key certificate for self-signed setups. ip_address String Optional Fixed IP for webhook requests instead of DNS. max_connections Integer Optional Simultaneous HTTPS connections, 1-100. Default 40. allowed_updates Array of String Optional Update types to receive (same as getUpdates). drop_pending_updates Boolean Optional True to discard all pending updates. secret_token String Optional 1-256 chars (A-Za-z0-9_-). Sent in the header X-Telegram-Bot-Api-Secret-Token on every request. Supported webhook ports: 443, 80, 88, 8443. deleteWebhook Removes webhook integration. Accepts optional drop_pending_updates Boolean. Returns True on success. getWebhookInfo Returns the current webhook status as a WebhookInfo object. No parameters. WebhookInfo fields: url String Webhook URL (empty if not set) has_custom_certificate Boolean True if custom certificate was provided pending_update_count Integer Updates awaiting delivery ip_address String Optional. Current webhook IP last_error_date Integer Optional. Unix time of last error last_error_message String Optional. Human-readable last error last_synchronization_error_date Integer Optional. Unix time of last sync error max_connections Integer Optional. Max simultaneous connections allowed_updates Array of String Optional. Subscribed update types THE UPDATE OBJECT Every incoming event is wrapped in an Update object. Exactly one of its optional fields will be present. Field Type Description update_id Integer Unique sequential identifier message Message New incoming message of any kind edited_message Message Edited message known to the bot channel_post Message New channel post edited_channel_post Message Edited channel post callback_query CallbackQuery Incoming callback query from inline keyboard my_chat_member ChatMemberUpdated Bot's status changed in a chat chat_member ChatMemberUpdated A member's status changed (requires opt-in) chat_join_request ChatJoinRequest Join request (bot needs can_invite_users) message_reaction MessageReactionUpdated Reaction changed (requires opt-in + admin) message_reaction_count MessageReactionCountUpdated Anonymous reactions changed (opt-in + admin) inline_query InlineQuery Incoming inline query chosen_inline_result ChosenInlineResult User chose an inline result shipping_query ShippingQuery Incoming shipping query pre_checkout_query PreCheckoutQuery Incoming pre-checkout query poll Poll Poll state update poll_answer PollAnswer User changed poll answer chat_boost ChatBoostUpdated Boost added/changed (bot must be admin) removed_chat_boost ChatBoostRemoved Boost removed (bot must be admin) To receive chat_member and message_reaction updates, you must explicitly include them in allowed_updates when calling getUpdates or setWebhook. CORE TYPES User Field Type Description id Integer Unique user/bot identifier (up to 52 bits) is_bot Boolean True if this is a bot first_name String First name last_name String Optional. Last name username String Optional. Username language_code String Optional. IETF language tag is_premium Boolean Optional. True if Telegram Premium user can_join_groups Boolean Optional. Returned only in getMe can_read_all_group_messages Boolean Optional. True if privacy mode disabled. getMe only. supports_inline_queries Boolean Optional. getMe only. has_topics_enabled Boolean Optional. True if threaded/forum mode enabled in private chats. getMe only. (Added in 9.3) allows_users_to_create_topics Boolean Optional. True if users can create/delete topics in private chats. getMe only. (Added in 9.4) The has_topics_enabled and allows_users_to_create_topics fields are only returned when calling getMe and are central to the threaded private chat system described later in this document. Chat Field Type Description id Integer Unique chat identifier (up to 52 bits) type String "private", "group", "supergroup", or "channel" title String Optional. For groups, supergroups, channels username String Optional. For private chats, supergroups, channels first_name String Optional. For private chats last_name String Optional. For private chats is_forum Boolean Optional. True if the supergroup has topics enabled is_direct_messages Boolean Optional. True if this is a channel DM chat Message The Message object is the central type in the Bot API. Every text message, photo, file, service notification, and forwarded message is represented as a Message. It has dozens of optional fields; only the most important for basic bot development are listed here. The complete list is in Telegram's documentation. Field Type Description message_id Integer Unique ID within this chat message_thread_id Integer Optional. Forum topic or thread ID (supergroups and private chats with topics enabled) from User Optional. Sender (empty for channel posts) sender_chat Chat Optional. Sender when sent on behalf of a chat date Integer Unix timestamp when sent chat Chat The chat this message belongs to text String Optional. UTF-8 text content entities Array of Optional. Special entities in the text (URLs, MessageEntity mentions, bot commands, formatting, etc.) reply_to_message Message Optional. The message being replied to edit_date Integer Optional. Unix time of last edit caption String Optional. Caption for media messages caption_entities Array of Optional. Entities in the caption MessageEntity is_topic_message Boolean Optional. True if sent to a forum topic Media fields (each optional, at most one present): photo Array of PhotoSize Photo in multiple sizes video Video Video file audio Audio Audio file (music) voice Voice Voice message video_note VideoNote Round video message document Document General file animation Animation GIF or silent video sticker Sticker Sticker Forwarding: forward_origin MessageOrigin Info about the original forwarded message Service messages (selected): new_chat_members Array of User Users added to group left_chat_member User User removed from group new_chat_title String Chat title changed forum_topic_created ForumTopicCreated Topic created forum_topic_edited ForumTopicEdited Topic renamed or icon changed forum_topic_closed ForumTopicClosed Topic closed forum_topic_reopened ForumTopicReopened Topic reopened pinned_message Message Message was pinned reply_markup InlineKeyboardMarkup Optional. Inline keyboard attached MessageEntity Field Type Description type String Entity type: "mention", "hashtag", "cashtag", "bot_command", "url", "email", "phone_number", "bold", "italic", "underline", "strikethrough", "spoiler", "blockquote", "expandable_blockquote", "code", "pre", "text_link", "text_mention", "custom_emoji" offset Integer Offset in UTF-16 code units length Integer Length in UTF-16 code units url String Optional. For "text_link" only user User Optional. For "text_mention" only language String Optional. For "pre" only (programming language) custom_emoji_id String Optional. For "custom_emoji" only FILE-RELATED TYPES PhotoSize Field Type Description file_id String Reusable file identifier for downloading or resending file_unique_id String Permanent unique ID (cannot be used to download) width Integer Photo width height Integer Photo height file_size Integer Optional. Size in bytes When a message contains a photo, the photo field is an Array of PhotoSize representing the same image at different resolutions. The last element is typically the largest. Document Field Type Description file_id String File identifier file_unique_id String Permanent unique ID thumbnail PhotoSize Optional. Thumbnail file_name String Optional. Original filename mime_type String Optional. MIME type file_size Integer Optional. Size in bytes (up to 52 bits) Audio Field Type Description file_id String File identifier file_unique_id String Permanent unique ID duration Integer Duration in seconds performer String Optional. Performer title String Optional. Title file_name String Optional. Original filename mime_type String Optional. MIME type file_size Integer Optional. Size in bytes thumbnail PhotoSize Optional. Album cover thumbnail Video Field Type Description file_id String File identifier file_unique_id String Permanent unique ID width Integer Width height Integer Height duration Integer Duration in seconds thumbnail PhotoSize Optional. Thumbnail file_name String Optional. Original filename mime_type String Optional. MIME type file_size Integer Optional. Size in bytes qualities Array of Optional. Available quality variants (9.4) VideoQuality Voice Field Type Description file_id String File identifier file_unique_id String Permanent unique ID duration Integer Duration in seconds mime_type String Optional. MIME type file_size Integer Optional. Size in bytes VideoNote Field Type Description file_id String File identifier file_unique_id String Permanent unique ID length Integer Diameter (width and height are equal) duration Integer Duration in seconds thumbnail PhotoSize Optional. Thumbnail file_size Integer Optional. Size in bytes Animation Field Type Description file_id String File identifier file_unique_id String Permanent unique ID width Integer Width height Integer Height duration Integer Duration in seconds thumbnail PhotoSize Optional. Thumbnail file_name String Optional. Original filename mime_type String Optional. MIME type file_size Integer Optional. Size in bytes File Returned by getFile. Contains the information needed to download the file. Field Type Description file_id String File identifier file_unique_id String Permanent unique ID file_size Integer Optional. Size in bytes file_path String Optional. Path for downloading Download URL: https://api.telegram.org/file/bot/ The link is valid for at least 1 hour. Maximum download size: 20 MB (use a local Bot API server for larger files). SENDING AND UPLOADING FILES There are three ways to send files: 1. By file_id: Pass an existing file_id as a String. The file already exists on Telegram's servers. This is the most efficient method and has no size limits. Example: sending a photo that was previously received. 2. By HTTP URL: Pass an HTTP URL as a String. Telegram will download the file. Maximum 5 MB for photos, 20 MB for other files. 3. By upload: Use multipart/form-data and attach the file. Maximum 10 MB for photos, 50 MB for other files. For the local Bot API server, the limit is 2000 MB. When uploading via multipart/form-data, the file field value should be the actual binary content. In InputMedia objects, use "attach://" to reference an uploaded file by the multipart field name. BOT IDENTITY getMe Returns the bot's own User object. No parameters. This is typically the first call a bot makes after starting up, both to verify the token works and to retrieve the bot's ID, username, and capabilities including has_topics_enabled and allows_users_to_create_topics. SENDING MESSAGES sendMessage Sends a text message. Returns the sent Message on success. Parameter Type Required Description chat_id Integer or String Yes Target chat ID or @username text String Yes Message text, 1-4096 characters message_thread_id Integer Optional Topic ID for forum/threaded chats parse_mode String Optional "MarkdownV2", "HTML", or "Markdown" entities Array of MessageEntity Optional Special entities (alternative to parse_mode) link_preview_options LinkPreviewOptions Optional Link preview settings disable_notification Boolean Optional Silent message protect_content Boolean Optional Prevent forwarding/saving reply_parameters ReplyParameters Optional Message to reply to reply_markup Keyboard or Markup Optional Keyboard (inline, reply, remove, force_reply) business_connection_id String Optional Business connection ID message_effect_id String Optional Message effect ID allow_paid_broadcast Boolean Optional Allow paid broadcast The reply_markup parameter accepts one of: InlineKeyboardMarkup, ReplyKeyboardMarkup, ReplyKeyboardRemove, or ForceReply. Example (curl with JSON): curl https://api.telegram.org/bot/sendMessage \ -H "Content-Type: application/json" \ -d '{ "chat_id": 12345678, "text": "Hello from RMS.", "parse_mode": "HTML", "reply_markup": { "inline_keyboard": [[ {"text": "Visit", "url": "https://example.com"} ]] } }' Example sending to a specific forum topic: curl https://api.telegram.org/bot/sendMessage \ -H "Content-Type: application/json" \ -d '{ "chat_id": 12345678, "message_thread_id": 42, "text": "This goes into topic 42." }' sendPhoto Sends a photo. Returns the sent Message. Parameter Type Required Description chat_id Integer or String Yes Target chat photo InputFile or String Yes Photo to send (upload, file_id, or URL) message_thread_id Integer Optional Topic ID caption String Optional Caption, 0-1024 characters parse_mode String Optional Caption parsing mode caption_entities Array of MessageEntity Optional Caption entities show_caption_above_media Boolean Optional Show caption above photo has_spoiler Boolean Optional Spoiler animation disable_notification Boolean Optional Silent protect_content Boolean Optional Prevent forwarding reply_parameters ReplyParameters Optional Reply target reply_markup Keyboard or Markup Optional Keyboard Example uploading a photo: curl https://api.telegram.org/bot/sendPhoto \ -F chat_id=12345678 \ -F photo=@/path/to/image.jpg \ -F caption="A photo from RMS" sendDocument Sends a general file. Returns the sent Message. Parameter Type Required Description chat_id Integer or String Yes Target chat document InputFile or String Yes File to send message_thread_id Integer Optional Topic ID thumbnail InputFile or String Optional Thumbnail (JPEG, <200KB, max 320px) caption String Optional Caption, 0-1024 characters parse_mode String Optional Caption parsing mode caption_entities Array of MessageEntity Optional Caption entities disable_content_type_detection Boolean Optional Disable auto MIME detection disable_notification Boolean Optional Silent protect_content Boolean Optional Prevent forwarding reply_parameters ReplyParameters Optional Reply target reply_markup Keyboard or Markup Optional Keyboard sendVideo Sends a video. Telegram clients support MP4 videos. Parameters follow the same pattern as sendPhoto and sendDocument, with additional fields: video InputFile or String Yes Video to send duration Integer Optional Duration in seconds width Integer Optional Video width height Integer Optional Video height thumbnail InputFile or String Optional Thumbnail cover InputFile or String Optional Video cover image start_timestamp Integer Optional Start position in seconds supports_streaming Boolean Optional Suitable for streaming has_spoiler Boolean Optional Spoiler animation Plus the standard chat_id, message_thread_id, caption, parse_mode, caption_entities, show_caption_above_media, disable_notification, protect_content, reply_parameters, and reply_markup. sendAudio Sends an audio file treated as music. Same pattern, with fields for duration, performer, and title in addition to the standard set. sendVoice Sends a voice message (.OGG encoded with OPUS). Same pattern, with duration field. sendVideoNote Sends a round video message. Same pattern, with duration and length (diameter) fields. sendAnimation Sends a GIF or silent H.264 video. Same pattern as sendVideo minus supports_streaming. sendMediaGroup Sends a group of 2-10 photos, videos, documents, or audios as an album. Returns an Array of Messages. Parameter Type Required Description chat_id Integer or String Yes Target chat media Array of InputMedia Yes 2-10 InputMediaPhoto, InputMediaVideo, InputMediaDocument, or InputMediaAudio message_thread_id Integer Optional Topic ID disable_notification Boolean Optional Silent protect_content Boolean Optional Prevent forwarding reply_parameters ReplyParameters Optional Reply target Documents and audio files can only be grouped with items of the same type. sendLocation Sends a point on the map. Returns the sent Message. Parameter Type Required Description chat_id Integer or String Yes Target chat latitude Float Yes Latitude longitude Float Yes Longitude message_thread_id Integer Optional Topic ID horizontal_accuracy Float Optional Uncertainty radius, 0-1500 meters live_period Integer Optional Live location duration, 60-86400 seconds, or 0x7FFFFFFF for indefinite heading Integer Optional Direction of movement, 1-360 degrees proximity_alert_radius Integer Optional Alert distance, meters disable_notification Boolean Optional Silent protect_content Boolean Optional Prevent forwarding reply_parameters ReplyParameters Optional Reply target reply_markup Keyboard or Markup Optional Keyboard sendContact Sends a phone contact. Parameter Type Required Description chat_id Integer or String Yes Target chat phone_number String Yes Contact's phone number first_name String Yes Contact's first name last_name String Optional Contact's last name vcard String Optional vCard data, 0-2048 bytes message_thread_id Integer Optional Topic ID (plus standard optional parameters) sendChatAction Sends a chat action (typing indicator, uploading photo, etc.). Returns True on success. The action disappears after 5 seconds or when a message is sent. Parameter Type Required Description chat_id Integer or String Yes Target chat action String Yes One of: "typing", "upload_photo", "record_video", "upload_video", "record_voice", "upload_voice", "upload_document", "choose_sticker", "find_location", "record_video_note", "upload_video_note" message_thread_id Integer Optional Topic ID (supported in private chats) FORWARDING AND COPYING forwardMessage Forwards an existing message. Returns the sent Message. Parameter Type Required Description chat_id Integer or String Yes Target chat from_chat_id Integer or String Yes Source chat message_id Integer Yes Message to forward message_thread_id Integer Optional Target topic ID disable_notification Boolean Optional Silent protect_content Boolean Optional Prevent further forwarding copyMessage Copies a message without the "Forwarded from" header. Returns MessageId on success. Accepts the same parameters as forwardMessage plus optional caption, parse_mode, caption_entities, show_caption_above_media, and reply_markup to override the original. EDITING AND DELETING MESSAGES editMessageText Edits the text of a message sent by the bot (or an inline message). Returns the edited Message on success. Parameter Type Required Description chat_id Integer or String Cond. Required if inline_message_id not used message_id Integer Cond. Required if inline_message_id not used inline_message_id String Cond. Required for inline messages text String Yes New text, 1-4096 characters parse_mode String Optional Parsing mode entities Array of MessageEntity Optional Text entities link_preview_options LinkPreviewOptions Optional Link preview settings reply_markup InlineKeyboardMarkup Optional New inline keyboard editMessageCaption Edits the caption of a message. Same conditional chat_id/message_id/inline_message_id pattern. Parameters: caption, parse_mode, caption_entities, show_caption_above_media, reply_markup. editMessageMedia Edits the media content of a message. The media parameter is an InputMedia object. Same conditional pattern. Also accepts reply_markup. editMessageReplyMarkup Edits only the inline keyboard of a message. Same conditional pattern. Only parameter beyond identifiers is reply_markup. deleteMessage Deletes a message. Returns True on success. Parameter Type Required Description chat_id Integer or String Yes Chat containing the message message_id Integer Yes Message to delete Bots can delete their own messages at any time, other users' messages in groups/supergroups if admin with can_delete_messages, and channel posts if admin with can_post_messages. Messages older than 48 hours cannot be deleted in private chats. deleteMessages Deletes multiple messages at once. Returns True on success. Parameter Type Required Description chat_id Integer or String Yes Chat containing the messages message_ids Array of Integer Yes 1-100 message IDs to delete DOWNLOADING FILES getFile Retrieves a File object for downloading. Pass a file_id. Parameter Type Required Description file_id String Yes File identifier from any file-bearing object Returns a File object with a file_path field. Construct the download URL as: https://api.telegram.org/file/bot/ The URL is valid for at least 1 hour. Maximum download size is 20 MB via the cloud API. For larger files, run a local Bot API server. CALLBACK QUERIES AND INLINE KEYBOARDS InlineKeyboardMarkup Field Type Description inline_keyboard Array of Array of InlineKeyboardButton Button rows InlineKeyboardButton Each button must have exactly one action field set (url, callback_data, web_app, login_url, switch_inline_query, switch_inline_query_current_chat, copy_text, callback_game, or pay). Field Type Description text String Button label url String Optional. URL to open callback_data String Optional. Data sent to bot (1-64 bytes) web_app WebAppInfo Optional. Web App to launch switch_inline_query String Optional. Prompts chat selection for inline switch_inline_query_current_chat String Optional. Inline query in current chat copy_text CopyTextButton Optional. Copies text to clipboard pay Boolean Optional. Pay button (must be first in first row) style String Optional. "danger" (red), "success" (green), "primary" (blue). Added in 9.4. icon_custom_emoji_id String Optional. Custom emoji before text. Added in 9.4. CallbackQuery Received when a user presses an inline keyboard button with callback_data. Field Type Description id String Unique query identifier from User Sender message MaybeInaccessibleMessage Optional. The message with the button inline_message_id String Optional. For inline mode messages chat_instance String Global chat identifier data String Optional. The callback_data from the button game_short_name String Optional. For game buttons answerCallbackQuery Sends an acknowledgment to a callback query. The Telegram client shows a loading spinner until this is called, so always call it even if you have nothing to display. Parameter Type Required Description callback_query_id String Yes ID from the CallbackQuery text String Optional Notification text (0-200 chars) show_alert Boolean Optional True to show an alert instead of a toast url String Optional URL to open (for game bots) cache_time Integer Optional Seconds to cache the result (default 0) REPLY KEYBOARDS ReplyKeyboardMarkup A custom keyboard shown below the message input field. Field Type Description keyboard Array of Array of KeyboardButton Button rows is_persistent Boolean Optional. Always show the keyboard resize_keyboard Boolean Optional. Fit keyboard to content one_time_keyboard Boolean Optional. Hide after one press input_field_placeholder String Optional. Placeholder text, 1-64 chars selective Boolean Optional. Show to specific users only KeyboardButton Field Type Description text String Button text (sent as message if no special field set) request_contact Boolean Optional. Send user's phone number request_location Boolean Optional. Send user's location request_poll KeyboardButtonPollType Optional. Create and send a poll web_app WebAppInfo Optional. Launch a Web App request_users KeyboardButtonRequestUsers Optional. Request user selection request_chat KeyboardButtonRequestChat Optional. Request chat selection style String Optional. "danger", "success", or "primary" (9.4) ReplyKeyboardRemove Removes the custom keyboard. Set remove_keyboard to True. Optional selective Boolean. ForceReply Shows the reply interface. Set force_reply to True. Optional input_field_placeholder String and selective Boolean. FORMATTING OPTIONS Three parse modes are available: HTML: Supported tags include , , , , , , , , , , , , , , , , , , . MarkdownV2: Uses *bold*, _italic_, __underline__, ~strikethrough~, ||spoiler||, `code`, ```pre```, ```language\npre```, [text](url), ![emoji](tg://emoji?id=...), >blockquote. Special characters must be escaped with a backslash: _ * [ ] ( ) ~ ` > # + - = | { } . ! Markdown (legacy): *bold*, _italic_, [text](url), `code`, ```pre```. Not recommended for new bots. REPLY PARAMETERS Field Type Description message_id Integer Message to reply to chat_id Integer or String Optional. Different chat for cross-chat replies allow_sending_without_reply Boolean Optional. Send even if original not found quote String Optional. Quoted text, 0-1024 chars quote_parse_mode String Optional. Parsing mode for quote quote_entities Array of MessageEntity Optional. Entities in quote quote_position Integer Optional. Quote position in UTF-16 units LINK PREVIEW OPTIONS Field Type Description is_disabled Boolean Optional. Disable link preview entirely url String Optional. URL to use for preview prefer_small_media Boolean Optional. Shrink media prefer_large_media Boolean Optional. Enlarge media show_above_text Boolean Optional. Show preview above message text FORUM TOPICS (THREADED MODE) Forum topics were originally designed for supergroups but have been extended to private bot chats as of Bot API 9.3 (December 31, 2025). When threaded mode is enabled for a bot via BotFather, each private chat with the bot can contain multiple named conversation threads. The user sees a sidebar or topic list and can switch between them. Each topic has its own message history and scroll position. To check whether threaded mode is enabled, call getMe and inspect the has_topics_enabled field on the returned User object. The allows_users_to_create_topics field indicates whether users are permitted to create and delete topics (controlled via a BotFather setting added in 9.4). Forum topic mode is a prerequisite for the streaming draft system (sendMessageDraft). Attempting to send drafts without threaded mode enabled returns the error TEXTDRAFT_PEER_INVALID. ForumTopic Field Type Description message_thread_id Integer Unique topic identifier name String Topic name icon_color Integer Icon color in RGB icon_custom_emoji_id String Optional. Custom emoji for the icon is_name_implicit Boolean Optional. True if name was auto-generated and the bot should rename it (added in 9.3) ForumTopicCreated (service message) Field Type Description name String Topic name icon_color Integer Icon color in RGB icon_custom_emoji_id String Optional. Custom emoji is_name_implicit Boolean Optional. True if auto-named (9.3) ForumTopicEdited (service message) Field Type Description name String Optional. New name, if changed icon_custom_emoji_id String Optional. New icon emoji, or empty string if removed createForumTopic Creates a topic in a supergroup or private chat. Returns a ForumTopic object. As of 9.4, bots can create topics in private chats (previously only supergroups). Parameter Type Required Description chat_id Integer or String Yes Target chat name String Yes Topic name, 1-128 characters icon_color Integer Optional One of 6 predefined RGB values: 7322096 (blue), 16766590 (yellow), 13338331 (violet), 9367192 (green), 16749490 (rose), 16478047 (red) icon_custom_emoji_id String Optional Custom emoji ID for the icon editForumTopic Edits a topic's name and/or icon. The bot must be an administrator with can_manage_topics rights (unless it created the topic). Parameter Type Required Description chat_id Integer or String Yes Chat containing the topic message_thread_id Integer Yes Topic to edit name String Optional New name, 0-128 chars (empty = unchanged) icon_custom_emoji_id String Optional New icon emoji (empty string = remove) Supported in private chats with topics enabled (9.3). closeForumTopic Closes a topic. No new messages can be sent to it until reopened. Parameter Type Required Description chat_id Integer or String Yes Chat message_thread_id Integer Yes Topic to close reopenForumTopic Reopens a closed topic. Parameter Type Required Description chat_id Integer or String Yes Chat message_thread_id Integer Yes Topic to reopen deleteForumTopic Permanently deletes a forum topic along with all its messages. Parameter Type Required Description chat_id Integer or String Yes Chat message_thread_id Integer Yes Topic to delete Supported in private chats with topics enabled (9.3). unpinAllForumTopicMessages Unpins all messages in a specific topic. Parameter Type Required Description chat_id Integer or String Yes Chat message_thread_id Integer Yes Topic Supported in private chats with topics enabled (9.3). getForumTopicIconStickers Returns an Array of Sticker objects representing the custom emoji stickers that can be used as forum topic icons. No parameters. STREAMING WITH sendMessageDraft Added in Bot API 9.3, sendMessageDraft allows a bot to stream partial message content to the user in real time, so the user sees the text building up character by character while the bot (or an LLM behind it) is still generating. This is the same user experience as ChatGPT's streaming output. Parameter Type Required Description chat_id Integer or String Yes Target chat (must be a private chat) draft_id String Yes Unique identifier for this draft session text String Yes Current text content of the draft Returns True on success. Threaded mode must be enabled for the bot (has_topics_enabled must be True). If threaded mode is not enabled, the call returns the error TEXTDRAFT_PEER_INVALID. The bot calls sendMessageDraft repeatedly as new text is generated, each time passing the full accumulated text so far with the same draft_id. The user's client displays the text as it grows. The text field has a maximum length of 4096 characters (the same as a regular message). When generation is complete, the bot calls sendMessage to finalize the message and replace the draft with a permanent message. The draft_id should be a unique string for each streaming session. If the bot starts a new draft with the same draft_id, it replaces the previous one. A typical streaming flow: 1. Bot receives a user message. 2. Bot calls sendMessageDraft with draft_id="abc123" and text="Thinking". 3. Bot calls sendMessageDraft with text="Thinking about". 4. Bot calls sendMessageDraft with text="Thinking about your question". 5. ... (continues building the text) 6. Bot calls sendMessage with the final complete text. For bots that need streaming but cannot use sendMessageDraft (pre-9.3 clients, or when draft mode is unavailable), the fallback approach is to call sendMessage once, then call editMessageText repeatedly at approximately 400ms intervals. Append a cursor character like a medium vertical bar (Unicode U+2758 or the block cursor U+258C) to indicate generation is in progress, and remove it on the final edit. CHAT INFORMATION AND ADMINISTRATION getChat Returns full chat information as a ChatFullInfo object. Pass chat_id (Integer or String). ChatFullInfo extends Chat with dozens of additional fields including description, invite_link, pinned_message, permissions, slow_mode_delay, linked_chat_id, photo, bio, and many others. For private chats with bots that have threaded mode, the object reflects the forum configuration. getChatMember Returns information about a chat member as a ChatMember object. Parameter Type Required Description chat_id Integer or String Yes Chat user_id Integer Yes User to look up The returned object is one of six types: ChatMemberOwner (status "creator"), ChatMemberAdministrator (status "administrator"), ChatMemberMember (status "member"), ChatMemberRestricted (status "restricted"), ChatMemberLeft (status "left"), or ChatMemberBanned (status "kicked"). getChatMemberCount Returns the number of members in a chat as an Integer. Pass chat_id. getChatAdministrators Returns an Array of ChatMember objects for all administrators. Pass chat_id. CHAT MEMBER STATUS TYPES ChatMemberOwner: status "creator", is_anonymous Boolean, custom_title String. ChatMemberAdministrator: status "administrator", full set of Boolean permission fields (can_manage_chat, can_delete_messages, can_restrict_members, can_promote_members, can_change_info, can_invite_users, can_post_messages, can_edit_messages, can_pin_messages, can_manage_topics, can_post_stories, can_edit_stories, can_delete_stories, can_manage_video_chats, can_manage_direct_messages), plus custom_title and can_be_edited. ChatMemberMember: status "member", optional until_date for subscription expiry. ChatMemberRestricted: status "restricted", is_member Boolean, granular can_send_* permissions, until_date. ChatMemberLeft: status "left". ChatMemberBanned: status "kicked", until_date (0 = forever). MANAGING BOT COMMANDS setMyCommands Sets the bot's command list. Returns True on success. Parameter Type Required Description commands Array of BotCommand Yes List of commands (max 100) scope BotCommandScope Optional Scope to apply commands to language_code String Optional Two-letter language code BotCommand: command (String, 1-32 chars, lowercase + digits + underscores) and description (String, 1-256 chars). getMyCommands Returns the current command list. Accepts optional scope and language_code. deleteMyCommands Deletes the command list for the given scope and language. Returns True. BOT COMMAND SCOPES BotCommandScopeDefault: All users, default fallback. BotCommandScopeAllPrivateChats: All private chats. BotCommandScopeAllGroupChats: All groups and supergroups. BotCommandScopeAllChatAdministrators: All group/supergroup admins. BotCommandScopeChat: Specific chat (requires chat_id). BotCommandScopeChatAdministrators: Admins of a specific chat (requires chat_id). BotCommandScopeChatMember: Specific user in a specific chat (requires chat_id and user_id). CHAT PERMISSIONS ChatPermissions describes what non-admin users can do. Each field is an optional Boolean: can_send_messages Text, contacts, locations, venues, invoices can_send_audios Audio files can_send_documents Documents can_send_photos Photos can_send_videos Videos can_send_video_notes Video notes can_send_voice_notes Voice notes can_send_polls Polls and checklists can_send_other_messages Animations, games, stickers, inline bots can_add_web_page_previews Link previews can_change_info Title, photo, settings can_invite_users Invite new users can_pin_messages Pin messages (groups/supergroups) can_manage_topics Create forum topics BOT PROFILE MANAGEMENT setMyProfilePhoto (9.4) Sets the bot's profile picture. Parameter Type Required Description photo InputFile Yes Photo to set as profile picture removeMyProfilePhoto (9.4) Removes the bot's profile picture. No parameters. setMyName Sets the bot's name. Parameter Type Required Description name String Optional New name, 0-64 characters language_code String Optional Language code getMyName Gets the bot's name. Optional language_code. Returns BotName. setMyDescription / getMyDescription Sets/gets the bot's description (shown on the bot's profile page). Optional description (0-512 chars) and language_code. Returns BotDescription. setMyShortDescription / getMyShortDescription Sets/gets the short description (shown on the start screen). Optional short_description (0-120 chars) and language_code. Returns BotShortDescription. setChatMenuButton / getChatMenuButton Sets/gets the menu button for a private chat. Optional chat_id and menu_button (MenuButtonCommands, MenuButtonWebApp, or MenuButtonDefault). PINNING MESSAGES pinChatMessage Parameter Type Required Description chat_id Integer or String Yes Chat message_id Integer Yes Message to pin disable_notification Boolean Optional Silent pin business_connection_id String Optional Business connection unpinChatMessage Parameter Type Required Description chat_id Integer or String Yes Chat message_id Integer Optional Specific message (unpins most recent if omitted) unpinAllChatMessages Unpins all messages in a chat. Pass chat_id. MANAGING CHAT MEMBERS banChatMember Parameter Type Required Description chat_id Integer or String Yes Chat user_id Integer Yes User to ban until_date Integer Optional Unix timestamp when ban expires (>366 days = forever) revoke_messages Boolean Optional Delete all messages from this user unbanChatMember Parameter Type Required Description chat_id Integer or String Yes Chat user_id Integer Yes User to unban only_if_banned Boolean Optional Only unban if currently banned restrictChatMember Parameter Type Required Description chat_id Integer or String Yes Chat user_id Integer Yes User to restrict permissions ChatPermissions Yes New permissions use_independent_chat_permissions Boolean Optional Per-type permissions until_date Integer Optional Restriction expiry (0 = forever) promoteChatMember Promotes or demotes a user. Pass chat_id, user_id, and any subset of the admin permission Booleans (can_manage_chat, can_delete_messages, can_restrict_members, can_promote_members, can_change_info, can_invite_users, can_post_stories, can_edit_stories, can_delete_stories, can_post_messages, can_edit_messages, can_pin_messages, can_manage_topics, can_manage_video_chats, can_manage_direct_messages, is_anonymous). setChatAdministratorCustomTitle Sets a custom title for an administrator. Parameter Type Required Description chat_id Integer or String Yes Chat user_id Integer Yes Admin user custom_title String Yes Title, 0-16 characters CHAT SETTINGS setChatTitle Parameter Type Required Description chat_id Integer or String Yes Chat title String Yes New title, 1-128 characters setChatDescription Parameter Type Required Description chat_id Integer or String Yes Chat description String Optional New description, 0-255 characters setChatPhoto / deleteChatPhoto Sets or deletes the chat photo. setChatPhoto takes chat_id and photo (InputFile). deleteChatPhoto takes only chat_id. setChatPermissions Sets default chat permissions. Parameter Type Required Description chat_id Integer or String Yes Chat permissions ChatPermissions Yes New permissions use_independent_chat_permissions Boolean Optional Per-type permissions INVITE LINKS createChatInviteLink Parameter Type Required Description chat_id Integer or String Yes Chat name String Optional Link name, 0-32 characters expire_date Integer Optional Unix timestamp when link expires member_limit Integer Optional Max members, 1-99999 creates_join_request Boolean Optional Require admin approval Returns ChatInviteLink. editChatInviteLink Same parameters as create, plus invite_link (String, required) to identify which link to edit. Returns ChatInviteLink. revokeChatInviteLink Revokes an invite link. Pass chat_id and invite_link. Returns the revoked ChatInviteLink. exportChatInviteLink Generates a new primary invite link, revoking the previous one. Pass chat_id. Returns the new link as a String. approveChatJoinRequest / declineChatJoinRequest Approves or declines a join request. Pass chat_id and user_id. Returns True. LEAVE AND RELATED leaveChat The bot leaves a group, supergroup, or channel. Pass chat_id. Returns True. logOut Logs the bot out from the cloud Bot API server. Use before switching to a local server. No parameters. close Closes the bot instance before moving it between local servers. No parameters. MISCELLANEOUS USEFUL METHODS getUserProfilePhotos Parameter Type Required Description user_id Integer Yes User whose photos to fetch offset Integer Optional Skip this many photos limit Integer Optional Number to return, 1-100, default 100 Returns UserProfilePhotos (total_count Integer, photos Array of Array of PhotoSize). getUserProfileAudios (9.4) Parameter Type Required Description user_id Integer Yes User offset Integer Optional Skip limit Integer Optional 1-100, default 100 Returns UserProfileAudios. RATE LIMITING AND CONSTRAINTS Telegram imposes rate limits that vary by context: Private chats: approximately 30 messages per second across all chats. Groups: 20 messages per minute per group. Bulk operations: 30 messages per second to different chats. editMessageText: subject to the same limits as sendMessage. When rate limited, the API returns error 429 with a retry_after value in the ResponseParameters object. Bots should implement exponential backoff. Text messages are limited to 4096 UTF-8 characters. Captions are limited to 1024 characters. Inline keyboard callback_data is limited to 64 bytes. USING A LOCAL BOT API SERVER The Bot API server source code is at github.com/tdlib/telegram-bot-api. Running locally enables: file downloads without size limits, uploads up to 2000 MB, file URI scheme for local files, HTTP webhook URLs, any local IP or port for webhooks, up to 100,000 max_webhook_connections, and absolute local file paths from getFile. SUMMARY OF BOT API VERSIONS COVERED Bot API 9.4 (February 9, 2026): Bots can create topics in private chats via createForumTopic. New BotFather setting controls whether users can create/delete topics. allows_users_to_create_topics field on User. Button styles ("danger", "success", "primary") and custom emoji on buttons. Bot profile photo management (setMyProfilePhoto, removeMyProfilePhoto). Video quality information. Bot API 9.3 (December 31, 2025): Topics in private chats. has_topics_enabled field on User. sendMessageDraft for streaming. message_thread_id support in private chats for all send methods, editForumTopic, deleteForumTopic, and unpinAllForumTopicMessages. is_name_implicit on ForumTopic and ForumTopicCreated. Bot API 9.2 (August 15, 2025): Checklists. Direct messages in channels. Suggested posts. can_manage_direct_messages admin right.