The Bot API is an HTTP-based interface created for developers keen on building bots for Telegram.
To learn how to create and set up a bot, please consult our Introduction to Bots »
You will find all changes to our Bot API on this page.
July 26, 2018
Bot API 4.0.
- Added support for Telegram Passport. See the official announcement on the blog and the manual for details.
- Added support for editing the media content of messages: added the method editMessageMedia and new types InputMediaAnimation, InputMediaAudio, and InputMediaDocument.
- Added the field thumb to the Audio object to contain the thumbnail of the album cover to which the music file belongs.
- Added support for attaching custom thumbnails to uploaded files. For animations, audios, videos and video notes, which are less than 10 MB in size, thumbnails are generated automatically.
tg:// URLs now can be used in inline keyboard url buttons and
text_link message entities.
- Added the method sendAnimation, which can be used instead of sendDocument to send animations, specifying their duration, width and height.
- Added the field animation to the Message object. For backward compatibility, when this field is set, the document field will be also set.
- Added two new MessageEntity types: cashtag and phone_number.
- Added support for Foursquare venues: added the new field foursquare_type to the objects Venue, InlineQueryResultVenue and InputVenueMessageContent, and the parameter foursquare_type to the sendVenue method.
- You can now create inline mentions of users, who have pressed your bot's callback buttons.
- You can now use the
Retry-After response header to configure the delay after which the Bot API will retry the request after an unsuccessful response from a webhook.
- If a webhook returns the HTTP error
410 Gone for all requests for more than 23 hours successively, it can be automatically removed.
- Added vCard support when sharing contacts: added the field vcard to the objects Contact, InlineQueryResultContact, InputContactMessageContent and the method sendContact.
February 13, 2018
Bot API 3.6.
- Supported text formatting in media captions. Specify the desired parse_mode (Markdown or HTML) when you provide a caption.
- In supergroups, if the bot receives a message that is a reply, it will also receive the message to which that message is replying – even if the original message is inaccessible due to the bot's privacy settings. (In other words, replying to any message in a supergroup with a message that mentions the bot or features a command for it acts as forwarding the original message to the bot).
- Added the new field connected_website to Message. The bot will receive a message with this field in a private chat when a user logs in on the bot's connected website using the Login Widget and allows sending messages from your bot.
- Added the new parameter supports_streaming to the sendVideo method and a field with the same name to the InputMediaVideo object.
November 17, 2017
Bot API 3.5.
October 11, 2017
Bot API 3.4.
August 23, 2017
Bot API 3.3.
- Bots can now mention users via inline mentions, without using usernames.
- getChat now also returns pinned messages in supergroups, if present. Added the new field pinned_message to the Chat object.
- Added the new fields author_signature and forward_signature to the Message object.
- Added the new field is_bot to the User object.
July 21, 2017
Bot API 3.2. Teach your bot to handle stickers and sticker sets.
June 30, 2017
Bot API 3.1. Build your own robotic police force for supergoups with these new methods for admin bots:
- Added new methods restrictChatMember and promoteChatMember to manage users and admins, added new parameter until_date to kickChatMember for temporary bans.
- Added new methods exportChatInviteLink, setChatPhoto, deleteChatPhoto, setChatTitle, setChatDescription, pinChatMessage and unpinChatMessage to manage groups and channels.
- Added the new fields photo, description and invite_link to the Chat object.
- Added the new fields until_date, can_be_edited, can_change_info, can_post_messages, can_edit_messages, can_delete_messages, can_invite_users, can_restrict_members, can_pin_messages, can_promote_members, can_send_messages, can_send_media_messages, can_send_other_messages and can_add_web_page_previews to the ChatMember object.
May 18, 2017
Introducing Bot API 3.0.
NEW Payment Platform
See Introduction to Bot Payments for a brief overview. If you're not a developer, you may like this user-friendly blog post better.
NEW Video Messages
- As of Telegram v.4.0, users can send short rounded video messages, using an interface similar to that of voice notes.
- Added the sendVideoNote method, the new field video_note to Message, the fields record_video_note or upload_video_note to sendChatAction.
NEW Multilingual Bots
- The User object now may have a language_code field that contains the IETF language tag of the user's language.
- Thanks to this, your bot can now offer localized responses to users that speak different languages.
More power to admin bots
- unbanChatMemeber now also works in channels!
- New method deleteMessage that allows the bot to delete its own messages, as well as messages posted by other in groups and channels where the bot is an administrator.
- Replaced the field new_chat_member in Message with new_chat_members (the old field will still be available for a while for compatibility purposes).
- Inline keyboards with switch_inline_query and switch_inline_query_current_chat can no longer be sent to channels because they are useless there.
- New fields gif_duration in InlineQueryResultGif and mpeg4_duration in InlineQueryResultMpeg4Gif.
December 4, 2016
Introducing Bot API 2.3.1, a nifty little update that will give you more control over how your bot gets its updates.
- Use the new field max_connections in setWebhook to optimize your bot's server load
- Use allowed_updates in setWebhook and getUpdates to selectively subscribe to updates of a certain type. Among other things, this allows you to stop getting updates about new posts in channels where your bot is an admin.
- deleteWebhook moved out of setWebhook to get a whole separate method for itself.
November 21, 2016
Bot API 2.3
- Modified bot privacy mode for the sake of consistency.
Your bot can now get updates about posts in channels. Added new fields channel_post and edited_channel_post to Update.
You can now update high scores to a lower value by using the new force parameter in setGameScore. Handy for punishing cheaters or fixing errors in your game's High Score table.
- Starting today, messages with high scores will be updated with new high scores by default. Use disable_edit_message in setGameScore if you don't want this.
- The edit_message parameter from setGameScore is no longer in use. For backward compatibility, it will be taken into account for a while, unless disable_edit_message is passed explicitly.
- Added the new field forward_from_message_id to Message.
- Added the new parameter cache_time to answerCallbackQuery. Will eventually work in Telegram apps — somewhere after version 3.14, maybe 3.15.
- Renamed hide_keyboard to remove_keyboard in ReplyKeyboardRemove for clarity. hide_keyboard will still work for a while for backward compatibility.
October 3, 2016
Bot API 2.2. Introducing a new Gaming Platform! See this introduction for a brief overview.
If you're not a developer, you may like this user-friendly blog post better.
- New field all_members_are_administrators in the Chat object.
- Certain server responses may now contain the new parameters field with expanded info on errors that occurred while processing your requests.
May 25, 2016
May 22, 2016
- Bot API 2.1. Added more tools for group administrator bots. Your bot can now get a list of administrators and members count in a group, check a user's current status (administrator, creator, left the group, kicked from the group), and leave a group.
- Added new methods: getChat, leaveChat, getChatAdministrators, getChatMember, getChatMembersCount.
- Added support for edited messages and new mentions from Telegram v.3.9. New fields: edited_message in Update, edit_date in Message, user in MessageEntity. New value text_mention for the type field in MessageEntity.
May 12, 2016
May 6, 2016
- Added the field emoji to the Sticker object. Your bot can now know the emoji a sticker corresponds to.
- Added the field forward_from_chat to the Message object for messages forwarded from channels.
April 9, 2016
Introducing Bot API 2.0. Check out this page for a review of this major update.
- Added support for all content types available on Telegram. 19 types of InlineQueryResult objects are now supported.
- Inline bots can now substitute all kinds of content with text. Added 4 types of InputMessageContent objects.
- Your inline bot can also ask users for permission to use their location. Added the new Botfather command
/setinlinegeo, added field location to the InlineQuery object, added fields location and inline_message_id to the ChosenInlineResult object.
- Added an easy way to switch between inline mode and a private chat with the bot – useful for settings, establishing external connections and teaching users how to use your bot in inline mode. Added parameters switch_pm_text and switch_pm_parameter to the method answerInlineQuery.
February 20, 2016
- Added the disable_notification parameter to all methods that send messages or any kind.
- Removed backward compatibility from the method sendAudio. Voice messages now must be sent using the method sendVoice. There is no more need to specify a non-empty title or performer while sending the audio by file_id.
January 20, 2016
- By the way, you can use both HTML-style and markdown-style formatting in your bot's messages to send bold, italic or fixed-width text and inline links. All official Telegram clients support this. See Formatting options for details.
January 14, 2016
- You can now collect feedback on which results provided by your inline bot get chosen by the users. Added the
setinlinefeedback command for Botfather, new type ChosenInlineResult, new field chosen_inline_result to the Update object.
January 4, 2016
- Added support for supergroups. The Type field in the Chat object can now contain ‘supergroup’.
- New optional fields added to the Message object: supergroup_chat_created, migrate_to_chat_id, migrate_from_chat_id and channel_chat_created.
October 8, 2015
- Added initial channel support for bots (no Telegram clients support this at the moment, please wait for updates):
- The Chat field in the Message is now of the new type Chat.
- You can now pass a channel username (in the format
@channelusername) in the place of chat_id in all methods (and instead of from_chat_id in forwardMessage). For this to work, the bot must be an administrator in the channel (and that‘s exactly what Telegram clients don’t support yet — adding bots as administrators coming soon).
September 18, 2015
- Bots can now download files and media sent by users.
- Added getFile and File.
September 7, 2015
- You can now pass parameters using application/json (please note that this doesn't work for file uploads: use multipart/form-data to upload files).
- Added very basic markdown support. New field parse_mode added to sendMessage. For the moment messages with markdown will be displayed correctly only in Telegram for Android. Other official apps will catch up soon.
August 29, 2015
- Added support for self-signed certificates: upload your certificate using the certificate parameter in the setWebhook method.
- You can now make new requests when responding to webhook updates.
August 15, 2015
- Added new type Voice and new method sendVoice for sending voice messages.
- Earlier Audio and sendAudio should now be used for sending music files. Telegram clients will show such files in the in-app music player. If you were using sendAudio for your bot to send voice messages, please use sendVoice instead.
- Added optional fields performer, title to the Audio object and sendAudio method.
- Added optional field voice to the Message object.
- The thumb field is now optional for Video, Sticker and Document objects
- The API now supports both video and photo captions. The caption field has been removed from the Video object and added to the Message object instead.
- caption and duration optional fields have been added to the sendVideo method.
- Fixed typo: user_id in the Contact object is now correctly labeled as Integer, not String
June 24, 2015
The bot platform was officially launched.
Back to the Bot API Manual »