There are two mutually exclusive ways of receiving updates for your bot – the getUpdates method on one hand and webhooks on the other. Incoming updates are stored on the server until the bot receives them either way, but they will not be kept longer than 24 hours.

Regardless of which option you choose, you will receive JSON-serialized Update objects as a result.

Update

This object represents an incoming update.
At most one of the optional parameters can be present in any given update.

Field Type Description
update_id Integer The update’s unique identifier. Update identifiers start from a certain positive number and increase sequentially. This ID becomes especially handy if you’re using webhooks, since it allows you to ignore repeated updates or to restore the correct update sequence, should they get out of order. If there are no new updates for at least a week, then identifier of the next update will be chosen randomly instead of sequentially.
message Message Optional. New incoming message of any kind – text, photo, sticker, etc.
edited_message Message Optional. New version of a message that is known to the bot and was edited
channel_post Message Optional. New incoming channel post of any kind – text, photo, sticker, etc.
edited_channel_post Message Optional. New version of a channel post that is known to the bot and was edited
inline_query InlineQuery Optional. New incoming inline query
chosen_inline_result ChosenInlineResult Optional. The result of an inline query that was chosen by a user and sent to their chat partner. Please see our documentation on the feedback collecting for details on how to enable these updates for your bot.
callback_query CallbackQuery Optional. New incoming callback query
shipping_query ShippingQuery Optional. New incoming shipping query. Only for invoices with flexible price
pre_checkout_query PreCheckoutQuery Optional. New incoming pre-checkout query. Contains full information about checkout
poll Poll Optional. New poll state. Bots receive only updates about stopped polls and polls, which are sent by the bot
poll_answer PollAnswer Optional. A user changed their answer in a non-anonymous poll. Bots receive new votes only in polls that were sent by the bot itself.
my_chat_member ChatMemberUpdated Optional. The bot’s chat member status was updated in a chat. For private chats, this update is received only when the bot is blocked or unblocked by the user.
chat_member ChatMemberUpdated Optional. A chat member’s status was updated in a chat. The bot must be an administrator in the chat and must explicitly specify "chat_member" in the list of allowed_updates to receive these updates.
chat_join_request ChatJoinRequest Optional. A request to join the chat has been sent. The bot must have the can_invite_users administrator right in the chat to receive these updates.

getUpdates

Use this method to receive incoming updates using long polling (wiki). Returns an Array of Update objects.

Parameter Type Required Description
offset Integer Optional Identifier of the first update to be returned. Must be greater by one than the highest among the identifiers of previously received updates. By default, updates starting with the earliest unconfirmed update are returned. An update is considered confirmed as soon as getUpdates is called with an offset higher than its update_id. The negative offset can be specified to retrieve updates starting from -offset update from the end of the updates queue. All previous updates will be forgotten.
limit Integer Optional Limits the number of updates to be retrieved. Values between 1-100 are accepted. Defaults to 100.
timeout Integer Optional Timeout in seconds for long polling. Defaults to 0, i.e. usual short polling. Should be positive, short polling should be used for testing purposes only.
allowed_updates Array of String Optional A JSON-serialized list of the update types you want your bot to receive. For example, specify ["message", "edited_channel_post", "callback_query"] to only receive updates of these types. See Update for a complete list of available update types. Specify an empty list to receive all update types except chat_member (default). If not specified, the previous setting will be used.

Please note that this parameter doesn’t affect updates created before the call to the getUpdates, so unwanted updates may be received for a short period of time.

Notes
1. This method will not work if an outgoing webhook is set up.
2. In order to avoid getting duplicate updates, recalculate offset after each server response.

setWebhook

Use this method to specify a URL and receive incoming updates via an outgoing webhook. Whenever there is an update for the bot, we will send an HTTPS POST request to the specified URL, containing a JSON-serialized Update. In case of an unsuccessful request, we will give up after a reasonable amount of attempts. Returns True on success.

If you’d like to make sure that the webhook was set by you, you can specify secret data in the parameter secret_token. If specified, the request will contain a header “X-Telegram-Bot-Api-Secret-Token” with the secret token as content.

Parameter Type Required Description
url String Yes HTTPS URL to send updates to. Use an empty string to remove webhook integration
certificate InputFile Optional Upload your public key certificate so that the root certificate in use can be checked. See our self-signed guide for details.
ip_address String Optional The fixed IP address which will be used to send webhook requests instead of the IP address resolved through DNS
max_connections Integer Optional The maximum allowed number of simultaneous HTTPS connections to the webhook for update delivery, 1-100. Defaults to 40. Use lower values to limit the load on your bot’s server, and higher values to increase your bot’s throughput.
allowed_updates Array of String Optional A JSON-serialized list of the update types you want your bot to receive. For example, specify ["message", "edited_channel_post", "callback_query"] to only receive updates of these types. See Update for a complete list of available update types. Specify an empty list to receive all update types except chat_member (default). If not specified, the previous setting will be used.
Please note that this parameter doesn’t affect updates created before the call to the setWebhook, so unwanted updates may be received for a short period of time.
drop_pending_updates Boolean Optional Pass True to drop all pending updates
secret_token String Optional A secret token to be sent in a header “X-Telegram-Bot-Api-Secret-Token” in every webhook request, 1-256 characters. Only characters A-Za-z0-9_ and - are allowed. The header is useful to ensure that the request comes from a webhook set by you.

Notes
1. You will not be able to receive updates using getUpdates for as long as an outgoing webhook is set up.
2. To use a self-signed certificate, you need to upload your public key certificate using certificate parameter. Please upload as InputFile, sending a String will not work.
3. Ports currently supported for webhooks443, 80, 88, 8443.

If you’re having any trouble setting up webhooks, please check out this amazing guide to webhooks.

deleteWebhook

Use this method to remove webhook integration if you decide to switch back to getUpdates. Returns True on success.

Parameter Type Required Description
drop_pending_updates Boolean Optional Pass True to drop all pending updates

getWebhookInfo

Use this method to get current webhook status. Requires no parameters. On success, returns a WebhookInfo object. If the bot is using getUpdates, will return an object with the url field empty.

WebhookInfo

Describes the current status of a webhook.

Field Type Description
url String Webhook URL, may be empty if webhook is not set up
has_custom_certificate Boolean True, if a custom certificate was provided for webhook certificate checks
pending_update_count Integer Number of updates awaiting delivery
ip_address String Optional. Currently used webhook IP address
last_error_date Integer Optional. Unix time for the most recent error that happened when trying to deliver an update via webhook
last_error_message String Optional. Error message in human-readable format for the most recent error that happened when trying to deliver an update via webhook
last_synchronization_error_date Integer Optional. Unix time of the most recent error that happened when trying to synchronize available updates with Telegram datacenters
max_connections Integer Optional. The maximum allowed number of simultaneous HTTPS connections to the webhook for update delivery
allowed_updates Array of String Optional. A list of update types the bot is subscribed to. Defaults to all update types except chat_member

Available types

All types used in the Bot API responses are represented as JSON-objects.

It is safe to use 32-bit signed integers for storing all Integer fields unless otherwise noted.

Optional fields may be not returned when irrelevant.

User

This object represents a Telegram user or bot.

Field Type Description
id Integer Unique identifier for this user or bot. This number may have more than 32 significant bits and some programming languages may have difficulty/silent defects in interpreting it. But it has at most 52 significant bits, so a 64-bit integer or double-precision float type are safe for storing this identifier.
is_bot Boolean True, if this user is a bot
first_name String User’s or bot’s first name
last_name String Optional. User’s or bot’s last name
username String Optional. User’s or bot’s username
language_code String Optional. IETF language tag of the user’s language
is_premium True OptionalTrue, if this user is a Telegram Premium user
added_to_attachment_menu True OptionalTrue, if this user added the bot to the attachment menu
can_join_groups Boolean OptionalTrue, if the bot can be invited to groups. Returned only in getMe.
can_read_all_group_messages Boolean OptionalTrue, if privacy mode is disabled for the bot. Returned only in getMe.
supports_inline_queries Boolean OptionalTrue, if the bot supports inline queries. Returned only in getMe.

Chat

This object represents a chat.

Field Type Description
id Integer Unique identifier for this chat. This number may have more than 32 significant bits and some programming languages may have difficulty/silent defects in interpreting it. But it has at most 52 significant bits, so a signed 64-bit integer or double-precision float type are safe for storing this identifier.
type String Type of chat, can be either “private”, “group”, “supergroup” or “channel”
title String Optional. Title, for supergroups, channels and group chats
username String Optional. Username, for private chats, supergroups and channels if available
first_name String Optional. First name of the other party in a private chat
last_name String Optional. Last name of the other party in a private chat
is_forum True OptionalTrue, if the supergroup chat is a forum (has topics enabled)
photo ChatPhoto Optional. Chat photo. Returned only in getChat.
active_usernames Array of String Optional. If non-empty, the list of all active chat usernames; for private chats, supergroups and channels. Returned only in getChat.
emoji_status_custom_emoji_id String Optional. Custom emoji identifier of emoji status of the other party in a private chat. Returned only in getChat.
emoji_status_expiration_date Integer Optional. Expiration date of the emoji status of the other party in a private chat in Unix time, if any. Returned only in getChat.
bio String Optional. Bio of the other party in a private chat. Returned only in getChat.
has_private_forwards True OptionalTrue, if privacy settings of the other party in the private chat allows to use tg://user?id=<user_id> links only in chats with the user. Returned only in getChat.
has_restricted_voice_and_video_messages True OptionalTrue, if the privacy settings of the other party restrict sending voice and video note messages in the private chat. Returned only in getChat.
join_to_send_messages True OptionalTrue, if users need to join the supergroup before they can send messages. Returned only in getChat.
join_by_request True OptionalTrue, if all users directly joining the supergroup need to be approved by supergroup administrators. Returned only in getChat.
description String Optional. Description, for groups, supergroups and channel chats. Returned only in getChat.
invite_link String Optional. Primary invite link, for groups, supergroups and channel chats. Returned only in getChat.
pinned_message Message Optional. The most recent pinned message (by sending date). Returned only in getChat.
permissions ChatPermissions Optional. Default chat member permissions, for groups and supergroups. Returned only in getChat.
slow_mode_delay Integer Optional. For supergroups, the minimum allowed delay between consecutive messages sent by each unpriviledged user; in seconds. Returned only in getChat.
message_auto_delete_time Integer Optional. The time after which all messages sent to the chat will be automatically deleted; in seconds. Returned only in getChat.
has_aggressive_anti_spam_enabled True OptionalTrue, if aggressive anti-spam checks are enabled in the supergroup. The field is only available to chat administrators. Returned only in getChat.
has_hidden_members True OptionalTrue, if non-administrators can only get the list of bots and administrators in the chat. Returned only in getChat.
has_protected_content True OptionalTrue, if messages from the chat can’t be forwarded to other chats. Returned only in getChat.
sticker_set_name String Optional. For supergroups, name of group sticker set. Returned only in getChat.
can_set_sticker_set True OptionalTrue, if the bot can change the group sticker set. Returned only in getChat.
linked_chat_id Integer Optional. Unique identifier for the linked chat, i.e. the discussion group identifier for a channel and vice versa; for supergroups and channel chats. This identifier may be greater than 32 bits and some programming languages may have difficulty/silent defects in interpreting it. But it is smaller than 52 bits, so a signed 64 bit integer or double-precision float type are safe for storing this identifier. Returned only in getChat.
location ChatLocation Optional. For supergroups, the location to which the supergroup is connected. Returned only in getChat.

Message

This object represents a message.

Field Type Description
message_id Integer Unique message identifier inside this chat
message_thread_id Integer Optional. Unique identifier of a message thread to which the message belongs; for supergroups only
from User Optional. Sender of the message; empty for messages sent to channels. For backward compatibility, the field contains a fake sender user in non-channel chats, if the message was sent on behalf of a chat.
sender_chat Chat Optional. Sender of the message, sent on behalf of a chat. For example, the channel itself for channel posts, the supergroup itself for messages from anonymous group administrators, the linked channel for messages automatically forwarded to the discussion group. For backward compatibility, the field from contains a fake sender user in non-channel chats, if the message was sent on behalf of a chat.
date Integer Date the message was sent in Unix time
chat Chat Conversation the message belongs to
forward_from User Optional. For forwarded messages, sender of the original message
forward_from_chat Chat Optional. For messages forwarded from channels or from anonymous administrators, information about the original sender chat
forward_from_message_id Integer Optional. For messages forwarded from channels, identifier of the original message in the channel
forward_signature String Optional. For forwarded messages that were originally sent in channels or by an anonymous chat administrator, signature of the message sender if present
forward_sender_name String Optional. Sender’s name for messages forwarded from users who disallow adding a link to their account in forwarded messages
forward_date Integer Optional. For forwarded messages, date the original message was sent in Unix time
is_topic_message True OptionalTrue, if the message is sent to a forum topic
is_automatic_forward True OptionalTrue, if the message is a channel post that was automatically forwarded to the connected discussion group
reply_to_message Message Optional. For replies, the original message. Note that the Message object in this field will not contain further reply_to_message fields even if it itself is a reply.
via_bot User Optional. Bot through which the message was sent
edit_date Integer Optional. Date the message was last edited in Unix time
has_protected_content True OptionalTrue, if the message can’t be forwarded
media_group_id String Optional. The unique identifier of a media message group this message belongs to
author_signature String Optional. Signature of the post author for messages in channels, or the custom title of an anonymous group administrator
text String Optional. For text messages, the actual UTF-8 text of the message
entities Array of MessageEntity Optional. For text messages, special entities like usernames, URLs, bot commands, etc. that appear in the text
animation Animation Optional. Message is an animation, information about the animation. For backward compatibility, when this field is set, the document field will also be set
audio Audio Optional. Message is an audio file, information about the file
document Document Optional. Message is a general file, information about the file
photo Array of PhotoSize Optional. Message is a photo, available sizes of the photo
sticker Sticker Optional. Message is a sticker, information about the sticker
story Story Optional. Message is a forwarded story
video Video Optional. Message is a video, information about the video
video_note VideoNote Optional. Message is a video note, information about the video message
voice Voice Optional. Message is a voice message, information about the file
caption String Optional. Caption for the animation, audio, document, photo, video or voice
caption_entities Array of MessageEntity Optional. For messages with a caption, special entities like usernames, URLs, bot commands, etc. that appear in the caption
has_media_spoiler True OptionalTrue, if the message media is covered by a spoiler animation
contact Contact Optional. Message is a shared contact, information about the contact
dice Dice Optional. Message is a dice with random value
game Game Optional. Message is a game, information about the game. More about games »
poll Poll Optional. Message is a native poll, information about the poll
venue Venue Optional. Message is a venue, information about the venue. For backward compatibility, when this field is set, the location field will also be set
location Location Optional. Message is a shared location, information about the location
new_chat_members Array of User Optional. New members that were added to the group or supergroup and information about them (the bot itself may be one of these members)
left_chat_member User Optional. A member was removed from the group, information about them (this member may be the bot itself)
new_chat_title String Optional. A chat title was changed to this value
new_chat_photo Array of PhotoSize Optional. A chat photo was change to this value
delete_chat_photo True Optional. Service message: the chat photo was deleted
group_chat_created True Optional. Service message: the group has been created
supergroup_chat_created True Optional. Service message: the supergroup has been created. This field can’t be received in a message coming through updates, because bot can’t be a member of a supergroup when it is created. It can only be found in reply_to_message if someone replies to a very first message in a directly created supergroup.
channel_chat_created True Optional. Service message: the channel has been created. This field can’t be received in a message coming through updates, because bot can’t be a member of a channel when it is created. It can only be found in reply_to_message if someone replies to a very first message in a channel.
message_auto_delete_timer_changed MessageAutoDeleteTimerChanged Optional. Service message: auto-delete timer settings changed in the chat
migrate_to_chat_id Integer Optional. The group has been migrated to a supergroup with the specified identifier. This number may have more than 32 significant bits and some programming languages may have difficulty/silent defects in interpreting it. But it has at most 52 significant bits, so a signed 64-bit integer or double-precision float type are safe for storing this identifier.
migrate_from_chat_id Integer Optional. The supergroup has been migrated from a group with the specified identifier. This number may have more than 32 significant bits and some programming languages may have difficulty/silent defects in interpreting it. But it has at most 52 significant bits, so a signed 64-bit integer or double-precision float type are safe for storing this identifier.
pinned_message Message Optional. Specified message was pinned. Note that the Message object in this field will not contain further reply_to_message fields even if it is itself a reply.
invoice Invoice Optional. Message is an invoice for a payment, information about the invoice. More about payments »
successful_payment SuccessfulPayment Optional. Message is a service message about a successful payment, information about the payment. More about payments »
user_shared UserShared Optional. Service message: a user was shared with the bot
chat_shared ChatShared Optional. Service message: a chat was shared with the bot
connected_website String Optional. The domain name of the website on which the user has logged in. More about Telegram Login »
write_access_allowed WriteAccessAllowed Optional. Service message: the user allowed the bot to write messages after adding it to the attachment or side menu, launching a Web App from a link, or accepting an explicit request from a Web App sent by the method requestWriteAccess
passport_data PassportData Optional. Telegram Passport data
proximity_alert_triggered ProximityAlertTriggered Optional. Service message. A user in the chat triggered another user’s proximity alert while sharing Live Location.
forum_topic_created ForumTopicCreated Optional. Service message: forum topic created
forum_topic_edited ForumTopicEdited Optional. Service message: forum topic edited
forum_topic_closed ForumTopicClosed Optional. Service message: forum topic closed
forum_topic_reopened ForumTopicReopened Optional. Service message: forum topic reopened
general_forum_topic_hidden GeneralForumTopicHidden Optional. Service message: the ‘General’ forum topic hidden
general_forum_topic_unhidden GeneralForumTopicUnhidden Optional. Service message: the ‘General’ forum topic unhidden
video_chat_scheduled VideoChatScheduled Optional. Service message: video chat scheduled
video_chat_started VideoChatStarted Optional. Service message: video chat started
video_chat_ended VideoChatEnded Optional. Service message: video chat ended
video_chat_participants_invited VideoChatParticipantsInvited Optional. Service message: new participants invited to a video chat
web_app_data WebAppData Optional. Service message: data sent by a Web App
reply_markup InlineKeyboardMarkup Optional. Inline keyboard attached to the message. login_url buttons are represented as ordinary url buttons.

MessageId

This object represents a unique message identifier.

Field Type Description
message_id Integer Unique message identifier

MessageEntity

This object represents one special entity in a text message. For example, hashtags, usernames, URLs, etc.

Field Type Description
type String Type of the entity. Currently, can be “mention” (@username), “hashtag” (#hashtag), “cashtag” ($USD), “bot_command” (/start@jobs_bot), “url” (https://telegram.org), “email” (do-not-reply@telegram.org), “phone_number” (+1-212-555-0123), “bold” (bold text), “italic” (italic text), “underline” (underlined text), “strikethrough” (strikethrough text), “spoiler” (spoiler message), “code” (monowidth string), “pre” (monowidth block), “text_link” (for clickable text URLs), “text_mention” (for users without usernames), “custom_emoji” (for inline custom emoji stickers)
offset Integer Offset in UTF-16 code units to the start of the entity
length Integer Length of the entity in UTF-16 code units
url String Optional. For “text_link” only, URL that will be opened after user taps on the text
user User Optional. For “text_mention” only, the mentioned user
language String Optional. For “pre” only, the programming language of the entity text
custom_emoji_id String Optional. For “custom_emoji” only, unique identifier of the custom emoji. Use getCustomEmojiStickers to get full information about the sticker

PhotoSize

This object represents one size of a photo or a file / sticker thumbnail.

Field Type Description
file_id String Identifier for this file, which can be used to download or reuse the file
file_unique_id String Unique identifier for this file, which is supposed to be the same over time and for different bots. Can’t be used to download or reuse the file.
width Integer Photo width
height Integer Photo height
file_size Integer Optional. File size in bytes

Animation

This object represents an animation file (GIF or H.264/MPEG-4 AVC video without sound).

Field Type Description
file_id String Identifier for this file, which can be used to download or reuse the file
file_unique_id String Unique identifier for this file, which is supposed to be the same over time and for different bots. Can’t be used to download or reuse the file.
width Integer Video width as defined by sender
height Integer Video height as defined by sender
duration Integer Duration of the video in seconds as defined by sender
thumbnail PhotoSize Optional. Animation thumbnail as defined by sender
file_name String Optional. Original animation filename as defined by sender
mime_type String Optional. MIME type of the file as defined by sender
file_size Integer Optional. File size in bytes. It can be bigger than 2^31 and some programming languages may have difficulty/silent defects in interpreting it. But it has at most 52 significant bits, so a signed 64-bit integer or double-precision float type are safe for storing this value.

Audio

This object represents an audio file to be treated as music by the Telegram clients.

Field Type Description
file_id String Identifier for this file, which can be used to download or reuse the file
file_unique_id String Unique identifier for this file, which is supposed to be the same over time and for different bots. Can’t be used to download or reuse the file.
duration Integer Duration of the audio in seconds as defined by sender
performer String Optional. Performer of the audio as defined by sender or by audio tags
title String Optional. Title of the audio as defined by sender or by audio tags
file_name String Optional. Original filename as defined by sender
mime_type String Optional. MIME type of the file as defined by sender
file_size Integer Optional. File size in bytes. It can be bigger than 2^31 and some programming languages may have difficulty/silent defects in interpreting it. But it has at most 52 significant bits, so a signed 64-bit integer or double-precision float type are safe for storing this value.
thumbnail PhotoSize Optional. Thumbnail of the album cover to which the music file belongs

Document

This object represents a general file (as opposed to photos, voice messages and audio files).

Field Type Description
file_id String Identifier for this file, which can be used to download or reuse the file
file_unique_id String Unique identifier for this file, which is supposed to be the same over time and for different bots. Can’t be used to download or reuse the file.
thumbnail PhotoSize Optional. Document thumbnail as defined by sender
file_name String Optional. Original filename as defined by sender
mime_type String Optional. MIME type of the file as defined by sender
file_size Integer Optional. File size in bytes. It can be bigger than 2^31 and some programming languages may have difficulty/silent defects in interpreting it. But it has at most 52 significant bits, so a signed 64-bit integer or double-precision float type are safe for storing this value.

Story

This object represents a message about a forwarded story in the chat. Currently holds no information.

Video

This object represents a video file.

Field Type Description
file_id String Identifier for this file, which can be used to download or reuse the file
file_unique_id String Unique identifier for this file, which is supposed to be the same over time and for different bots. Can’t be used to download or reuse the file.
width Integer Video width as defined by sender
height Integer Video height as defined by sender
duration Integer Duration of the video in seconds as defined by sender
thumbnail PhotoSize Optional. Video thumbnail
file_name String Optional. Original filename as defined by sender
mime_type String Optional. MIME type of the file as defined by sender
file_size Integer Optional. File size in bytes. It can be bigger than 2^31 and some programming languages may have difficulty/silent defects in interpreting it. But it has at most 52 significant bits, so a signed 64-bit integer or double-precision float type are safe for storing this value.

VideoNote

This object represents a video message (available in Telegram apps as of v.4.0).

Field Type Description
file_id String Identifier for this file, which can be used to download or reuse the file
file_unique_id String Unique identifier for this file, which is supposed to be the same over time and for different bots. Can’t be used to download or reuse the file.
length Integer Video width and height (diameter of the video message) as defined by sender
duration Integer Duration of the video in seconds as defined by sender
thumbnail PhotoSize Optional. Video thumbnail
file_size Integer Optional. File size in bytes

Voice

This object represents a voice note.

Field Type Description
file_id String Identifier for this file, which can be used to download or reuse the file
file_unique_id String Unique identifier for this file, which is supposed to be the same over time and for different bots. Can’t be used to download or reuse the file.
duration Integer Duration of the audio in seconds as defined by sender
mime_type String Optional. MIME type of the file as defined by sender
file_size Integer Optional. File size in bytes. It can be bigger than 2^31 and some programming languages may have difficulty/silent defects in interpreting it. But it has at most 52 significant bits, so a signed 64-bit integer or double-precision float type are safe for storing this value.

Contact

This object represents a phone contact.

Field Type Description
phone_number String Contact’s phone number
first_name String Contact’s first name
last_name String Optional. Contact’s last name
user_id Integer Optional. Contact’s user identifier in Telegram. This number may have more than 32 significant bits and some programming languages may have difficulty/silent defects in interpreting it. But it has at most 52 significant bits, so a 64-bit integer or double-precision float type are safe for storing this identifier.
vcard String Optional. Additional data about the contact in the form of a vCard

Dice

This object represents an animated emoji that displays a random value.

Field Type Description
emoji String Emoji on which the dice throw animation is based
value Integer Value of the dice, 1-6 for “????”, “????” and “????” base emoji, 1-5 for “????” and “⚽” base emoji, 1-64 for “????” base emoji

PollOption

This object contains information about one answer option in a poll.

Field Type Description
text String Option text, 1-100 characters
voter_count Integer Number of users that voted for this option

PollAnswer

This object represents an answer of a user in a non-anonymous poll.

Field Type Description
poll_id String Unique poll identifier
voter_chat Chat Optional. The chat that changed the answer to the poll, if the voter is anonymous
user User Optional. The user that changed the answer to the poll, if the voter isn’t anonymous
option_ids Array of Integer 0-based identifiers of chosen answer options. May be empty if the vote was retracted.

Poll

This object contains information about a poll.

Field Type Description
id String Unique poll identifier
question String Poll question, 1-300 characters
options Array of PollOption List of poll options
total_voter_count Integer Total number of users that voted in the poll
is_closed Boolean True, if the poll is closed
is_anonymous Boolean True, if the poll is anonymous
type String Poll type, currently can be “regular” or “quiz”
allows_multiple_answers Boolean True, if the poll allows multiple answers
correct_option_id Integer Optional. 0-based identifier of the correct answer option. Available only for polls in the quiz mode, which are closed, or was sent (not forwarded) by the bot or to the private chat with the bot.
explanation String Optional. Text that is shown when a user chooses an incorrect answer or taps on the lamp icon in a quiz-style poll, 0-200 characters
explanation_entities Array of MessageEntity Optional. Special entities like usernames, URLs, bot commands, etc. that appear in the explanation
open_period Integer Optional. Amount of time in seconds the poll will be active after creation
close_date Integer Optional. Point in time (Unix timestamp) when the poll will be automatically closed

Location

This object represents a point on the map.

Field Type Description
longitude Float Longitude as defined by sender
latitude Float Latitude as defined by sender
horizontal_accuracy Float number Optional. The radius of uncertainty for the location, measured in meters; 0-1500
live_period Integer Optional. Time relative to the message sending date, during which the location can be updated; in seconds. For active live locations only.
heading Integer Optional. The direction in which user is moving, in degrees; 1-360. For active live locations only.
proximity_alert_radius Integer Optional. The maximum distance for proximity alerts about approaching another chat member, in meters. For sent live locations only.

Venue

This object represents a venue.

Field Type Description
location Location Venue location. Can’t be a live location
title String Name of the venue
address String Address of the venue
foursquare_id String Optional. Foursquare identifier of the venue
foursquare_type String Optional. Foursquare type of the venue. (For example, “arts_entertainment/default”, “arts_entertainment/aquarium” or “food/icecream”.)
google_place_id String Optional. Google Places identifier of the venue
google_place_type String Optional. Google Places type of the venue. (See supported types.)

WebAppData

Describes data sent from a Web App to the bot.

Field Type Description
data String The data. Be aware that a bad client can send arbitrary data in this field.
button_text String Text of the web_app keyboard button from which the Web App was opened. Be aware that a bad client can send arbitrary data in this field.

ProximityAlertTriggered

This object represents the content of a service message, sent whenever a user in the chat triggers a proximity alert set by another user.

Field Type Description
traveler User User that triggered the alert
watcher User User that set the alert
distance Integer The distance between the users

MessageAutoDeleteTimerChanged

This object represents a service message about a change in auto-delete timer settings.

Field Type Description
message_auto_delete_time Integer New auto-delete time for messages in the chat; in seconds

ForumTopicCreated

This object represents a service message about a new forum topic created in the chat.

Field Type Description
name String Name of the topic
icon_color Integer Color of the topic icon in RGB format
icon_custom_emoji_id String Optional. Unique identifier of the custom emoji shown as the topic icon

ForumTopicClosed

This object represents a service message about a forum topic closed in the chat. Currently holds no information.

ForumTopicEdited

This object represents a service message about an edited forum topic.

Field Type Description
name String Optional. New name of the topic, if it was edited
icon_custom_emoji_id String Optional. New identifier of the custom emoji shown as the topic icon, if it was edited; an empty string if the icon was removed

ForumTopicReopened

This object represents a service message about a forum topic reopened in the chat. Currently holds no information.

GeneralForumTopicHidden

This object represents a service message about General forum topic hidden in the chat. Currently holds no information.

GeneralForumTopicUnhidden

This object represents a service message about General forum topic unhidden in the chat. Currently holds no information.

UserShared

This object contains information about the user whose identifier was shared with the bot using a KeyboardButtonRequestUser button.

Field Type Description
request_id Integer Identifier of the request
user_id Integer Identifier of the shared user. This number may have more than 32 significant bits and some programming languages may have difficulty/silent defects in interpreting it. But it has at most 52 significant bits, so a 64-bit integer or double-precision float type are safe for storing this identifier. The bot may not have access to the user and could be unable to use this identifier, unless the user is already known to the bot by some other means.

ChatShared

This object contains information about the chat whose identifier was shared with the bot using a KeyboardButtonRequestChat button.

Field Type Description
request_id Integer Identifier of the request
chat_id Integer Identifier of the shared chat. This number may have more than 32 significant bits and some programming languages may have difficulty/silent defects in interpreting it. But it has at most 52 significant bits, so a 64-bit integer or double-precision float type are safe for storing this identifier. The bot may not have access to the chat and could be unable to use this identifier, unless the chat is already known to the bot by some other means.

WriteAccessAllowed

This object represents a service message about a user allowing a bot to write messages after adding it to the attachment menu, launching a Web App from a link, or accepting an explicit request from a Web App sent by the method requestWriteAccess.

Field Type Description
from_request Boolean Optional. True, if the access was granted after the user accepted an explicit request from a Web App sent by the method requestWriteAccess
web_app_name String Optional. Name of the Web App, if the access was granted when the Web App was launched from a link
from_attachment_menu Boolean Optional. True, if the access was granted when the bot was added to the attachment or side menu

VideoChatScheduled

This object represents a service message about a video chat scheduled in the chat.

Field Type Description
start_date Integer Point in time (Unix timestamp) when the video chat is supposed to be started by a chat administrator

VideoChatStarted

This object represents a service message about a video chat started in the chat. Currently holds no information.

VideoChatEnded

This object represents a service message about a video chat ended in the chat.

Field Type Description
duration Integer Video chat duration in seconds

VideoChatParticipantsInvited

This object represents a service message about new members invited to a video chat.

Field Type Description
users Array of User New members that were invited to the video chat

UserProfilePhotos

This object represent a user’s profile pictures.

Field Type Description
total_count Integer Total number of profile pictures the target user has
photos Array of Array of PhotoSize Requested profile pictures (in up to 4 sizes each)

File

This object represents a file ready to be downloaded. The file can be downloaded via the link https://api.telegram.org/file/bot<token>/<file_path>. It is guaranteed that the link will be valid for at least 1 hour. When the link expires, a new one can be requested by calling getFile.

The maximum file size to download is 20 MB

Field Type Description
file_id String Identifier for this file, which can be used to download or reuse the file
file_unique_id String Unique identifier for this file, which is supposed to be the same over time and for different bots. Can’t be used to download or reuse the file.
file_size Integer Optional. File size in bytes. It can be bigger than 2^31 and some programming languages may have difficulty/silent defects in interpreting it. But it has at most 52 significant bits, so a signed 64-bit integer or double-precision float type are safe for storing this value.
file_path String Optional. File path. Use https://api.telegram.org/file/bot<token>/<file_path> to get the file.

WebAppInfo

Describes a Web App.

Field Type Description
url String An HTTPS URL of a Web App to be opened with additional data as specified in Initializing Web Apps

ReplyKeyboardMarkup

This object represents a custom keyboard with reply options (see Introduction to bots for details and examples).

Field Type Description
keyboard Array of Array of KeyboardButton Array of button rows, each represented by an Array of KeyboardButton objects
is_persistent Boolean Optional. Requests clients to always show the keyboard when the regular keyboard is hidden. Defaults to false, in which case the custom keyboard can be hidden and opened with a keyboard icon.
resize_keyboard Boolean Optional. Requests clients to resize the keyboard vertically for optimal fit (e.g., make the keyboard smaller if there are just two rows of buttons). Defaults to false, in which case the custom keyboard is always of the same height as the app’s standard keyboard.
one_time_keyboard Boolean Optional. Requests clients to hide the keyboard as soon as it’s been used. The keyboard will still be available, but clients will automatically display the usual letter-keyboard in the chat – the user can press a special button in the input field to see the custom keyboard again. Defaults to false.
input_field_placeholder String Optional. The placeholder to be shown in the input field when the keyboard is active; 1-64 characters
selective Boolean Optional. Use this parameter if you want to show the keyboard to specific users only. Targets: 1) users that are @mentioned in the text of the Message object; 2) if the bot’s message is a reply (has reply_to_message_id), sender of the original message.

Example: A user requests to change the bot’s language, bot replies to the request with a keyboard to select the new language. Other users in the group don’t see the keyboard.

KeyboardButton

This object represents one button of the reply keyboard. For simple text buttons, String can be used instead of this object to specify the button text. The optional fields web_apprequest_userrequest_chatrequest_contactrequest_location, and request_poll are mutually exclusive.

Field Type Description
text String Text of the button. If none of the optional fields are used, it will be sent as a message when the button is pressed
request_user KeyboardButtonRequestUser Optional. If specified, pressing the button will open a list of suitable users. Tapping on any user will send their identifier to the bot in a “user_shared” service message. Available in private chats only.
request_chat KeyboardButtonRequestChat Optional. If specified, pressing the button will open a list of suitable chats. Tapping on a chat will send its identifier to the bot in a “chat_shared” service message. Available in private chats only.
request_contact Boolean Optional. If True, the user’s phone number will be sent as a contact when the button is pressed. Available in private chats only.
request_location Boolean Optional. If True, the user’s current location will be sent when the button is pressed. Available in private chats only.
request_poll KeyboardButtonPollType Optional. If specified, the user will be asked to create a poll and send it to the bot when the button is pressed. Available in private chats only.
web_app WebAppInfo Optional. If specified, the described Web App will be launched when the button is pressed. The Web App will be able to send a “web_app_data” service message. Available in private chats only.

Note: request_contact and request_location options will only work in Telegram versions released after 9 April, 2016. Older clients will display unsupported message.
Note: request_poll option will only work in Telegram versions released after 23 January, 2020. Older clients will display unsupported message.
Note: web_app option will only work in Telegram versions released after 16 April, 2022. Older clients will display unsupported message.
Note: request_user and request_chat options will only work in Telegram versions released after 3 February, 2023. Older clients will display unsupported message.

KeyboardButtonRequestUser

This object defines the criteria used to request a suitable user. The identifier of the selected user will be shared with the bot when the corresponding button is pressed. More about requesting users »

Field Type Description
request_id Integer Signed 32-bit identifier of the request, which will be received back in the UserShared object. Must be unique within the message
user_is_bot Boolean Optional. Pass True to request a bot, pass False to request a regular user. If not specified, no additional restrictions are applied.
user_is_premium Boolean Optional. Pass True to request a premium user, pass False to request a non-premium user. If not specified, no additional restrictions are applied.

KeyboardButtonRequestChat

This object defines the criteria used to request a suitable chat. The identifier of the selected chat will be shared with the bot when the corresponding button is pressed. More about requesting chats »

Field Type Description
request_id Integer Signed 32-bit identifier of the request, which will be received back in the ChatShared object. Must be unique within the message
chat_is_channel Boolean Pass True to request a channel chat, pass False to request a group or a supergroup chat.
chat_is_forum Boolean Optional. Pass True to request a forum supergroup, pass False to request a non-forum chat. If not specified, no additional restrictions are applied.
chat_has_username Boolean Optional. Pass True to request a supergroup or a channel with a username, pass False to request a chat without a username. If not specified, no additional restrictions are applied.
chat_is_created Boolean Optional. Pass True to request a chat owned by the user. Otherwise, no additional restrictions are applied.
user_administrator_rights ChatAdministratorRights Optional. A JSON-serialized object listing the required administrator rights of the user in the chat. The rights must be a superset of bot_administrator_rights. If not specified, no additional restrictions are applied.
bot_administrator_rights ChatAdministratorRights Optional. A JSON-serialized object listing the required administrator rights of the bot in the chat. The rights must be a subset of user_administrator_rights. If not specified, no additional restrictions are applied.
bot_is_member Boolean Optional. Pass True to request a chat with the bot as a member. Otherwise, no additional restrictions are applied.

KeyboardButtonPollType

This object represents type of a poll, which is allowed to be created and sent when the corresponding button is pressed.

Field Type Description
type String Optional. If quiz is passed, the user will be allowed to create only polls in the quiz mode. If regular is passed, only regular polls will be allowed. Otherwise, the user will be allowed to create a poll of any type.

ReplyKeyboardRemove

Upon receiving a message with this object, Telegram clients will remove the current custom keyboard and display the default letter-keyboard. By default, custom keyboards are displayed until a new keyboard is sent by a bot. An exception is made for one-time keyboards that are hidden immediately after the user presses a button (see ReplyKeyboardMarkup).

Field Type Description
remove_keyboard True Requests clients to remove the custom keyboard (user will not be able to summon this keyboard; if you want to hide the keyboard from sight but keep it accessible, use one_time_keyboard in ReplyKeyboardMarkup)
selective Boolean Optional. Use this parameter if you want to remove the keyboard for specific users only. Targets: 1) users that are @mentioned in the text of the Message object; 2) if the bot’s message is a reply (has reply_to_message_id), sender of the original message.

Example: A user votes in a poll, bot returns confirmation message in reply to the vote and removes the keyboard for that user, while still showing the keyboard with poll options to users who haven’t voted yet.

InlineKeyboardMarkup

This object represents an inline keyboard that appears right next to the message it belongs to.

Field Type Description
inline_keyboard Array of Array of InlineKeyboardButton Array of button rows, each represented by an Array of InlineKeyboardButton objects

Note: This will only work in Telegram versions released after 9 April, 2016. Older clients will display unsupported message.

InlineKeyboardButton

This object represents one button of an inline keyboard. You must use exactly one of the optional fields.

Field Type Description
text String Label text on the button
url String Optional. HTTP or tg:// URL to be opened when the button is pressed. Links tg://user?id=<user_id> can be used to mention a user by their ID without using a username, if this is allowed by their privacy settings.
callback_data String Optional. Data to be sent in a callback query to the bot when button is pressed, 1-64 bytes
web_app WebAppInfo Optional. Description of the Web App that will be launched when the user presses the button. The Web App will be able to send an arbitrary message on behalf of the user using the method answerWebAppQuery. Available only in private chats between a user and the bot.
login_url LoginUrl Optional. An HTTPS URL used to automatically authorize the user. Can be used as a replacement for the Telegram Login Widget.
switch_inline_query String Optional. If set, pressing the button will prompt the user to select one of their chats, open that chat and insert the bot’s username and the specified inline query in the input field. May be empty, in which case just the bot’s username will be inserted.
switch_inline_query_current_chat String Optional. If set, pressing the button will insert the bot’s username and the specified inline query in the current chat’s input field. May be empty, in which case only the bot’s username will be inserted.

This offers a quick way for the user to open your bot in inline mode in the same chat – good for selecting something from multiple options.

switch_inline_query_chosen_chat SwitchInlineQueryChosenChat Optional. If set, pressing the button will prompt the user to select one of their chats of the specified type, open that chat and insert the bot’s username and the specified inline query in the input field
callback_game CallbackGame Optional. Description of the game that will be launched when the user presses the button.

NOTE: This type of button must always be the first button in the first row.

pay Boolean Optional. Specify True, to send a Pay button.

NOTE: This type of button must always be the first button in the first row and can only be used in invoice messages.

LoginUrl

This object represents a parameter of the inline keyboard button used to automatically authorize a user. Serves as a great replacement for the Telegram Login Widget when the user is coming from Telegram. All the user needs to do is tap/click a button and confirm that they want to log in:

TITLE

Telegram apps support these buttons as of version 5.7.

Sample bot: @discussbot

Field Type Description
url String An HTTPS URL to be opened with user authorization data added to the query string when the button is pressed. If the user refuses to provide authorization data, the original URL without information about the user will be opened. The data added is the same as described in Receiving authorization data.

NOTE: You must always check the hash of the received data to verify the authentication and the integrity of the data as described in Checking authorization.

forward_text String Optional. New text of the button in forwarded messages.
bot_username String Optional. Username of a bot, which will be used for user authorization. See Setting up a bot for more details. If not specified, the current bot’s username will be assumed. The url‘s domain must be the same as the domain linked with the bot. See Linking your domain to the bot for more details.
request_write_access Boolean Optional. Pass True to request the permission for your bot to send messages to the user.

SwitchInlineQueryChosenChat

This object represents an inline button that switches the current user to inline mode in a chosen chat, with an optional default inline query.

Field Type Description
query String Optional. The default inline query to be inserted in the input field. If left empty, only the bot’s username will be inserted
allow_user_chats Boolean Optional. True, if private chats with users can be chosen
allow_bot_chats Boolean Optional. True, if private chats with bots can be chosen
allow_group_chats Boolean Optional. True, if group and supergroup chats can be chosen
allow_channel_chats Boolean Optional. True, if channel chats can be chosen

CallbackQuery

This object represents an incoming callback query from a callback button in an inline keyboard. If the button that originated the query was attached to a message sent by the bot, the field message will be present. If the button was attached to a message sent via the bot (in inline mode), the field inline_message_id will be present. Exactly one of the fields data or game_short_name will be present.

Field Type Description
id String Unique identifier for this query
from User Sender
message Message Optional. Message with the callback button that originated the query. Note that message content and message date will not be available if the message is too old
inline_message_id String Optional. Identifier of the message sent via the bot in inline mode, that originated the query.
chat_instance String Global identifier, uniquely corresponding to the chat to which the message with the callback button was sent. Useful for high scores in games.
data String Optional. Data associated with the callback button. Be aware that the message originated the query can contain no callback buttons with this data.
game_short_name String Optional. Short name of a Game to be returned, serves as the unique identifier for the game

NOTE: After the user presses a callback button, Telegram clients will display a progress bar until you call answerCallbackQuery. It is, therefore, necessary to react by calling answerCallbackQuery even if no notification to the user is needed (e.g., without specifying any of the optional parameters).

ForceReply

Upon receiving a message with this object, Telegram clients will display a reply interface to the user (act as if the user has selected the bot’s message and tapped ‘Reply’). This can be extremely useful if you want to create user-friendly step-by-step interfaces without having to sacrifice privacy mode.

Field Type Description
force_reply True Shows reply interface to the user, as if they manually selected the bot’s message and tapped ‘Reply’
input_field_placeholder String Optional. The placeholder to be shown in the input field when the reply is active; 1-64 characters
selective Boolean Optional. Use this parameter if you want to force reply from specific users only. Targets: 1) users that are @mentioned in the text of the Message object; 2) if the bot’s message is a reply (has reply_to_message_id), sender of the original message.

Example: A poll bot for groups runs in privacy mode (only receives commands, replies to its messages and mentions). There could be two ways to create a new poll:

  • Explain the user how to send a command with parameters (e.g. /newpoll question answer1 answer2). May be appealing for hardcore users but lacks modern day polish.
  • Guide the user through a step-by-step process. ‘Please send me your question’, ‘Cool, now let’s add the first answer option’, ‘Great. Keep adding answer options, then send /done when you’re ready’.

The last option is definitely more attractive. And if you use ForceReply in your bot’s questions, it will receive the user’s answers even if it only receives replies, commands and mentions – without any extra work for the user.

ChatPhoto

This object represents a chat photo.

Field Type Description
small_file_id String File identifier of small (160×160) chat photo. This file_id can be used only for photo download and only for as long as the photo is not changed.
small_file_unique_id String Unique file identifier of small (160×160) chat photo, which is supposed to be the same over time and for different bots. Can’t be used to download or reuse the file.
big_file_id String File identifier of big (640×640) chat photo. This file_id can be used only for photo download and only for as long as the photo is not changed.
big_file_unique_id String Unique file identifier of big (640×640) chat photo, which is supposed to be the same over time and for different bots. Can’t be used to download or reuse the file.

ChatInviteLink

Represents an invite link for a chat.

Field Type Description
invite_link String The invite link. If the link was created by another chat administrator, then the second part of the link will be replaced with “…”.
creator User Creator of the link
creates_join_request Boolean True, if users joining the chat via the link need to be approved by chat administrators
is_primary Boolean True, if the link is primary
is_revoked Boolean True, if the link is revoked
name String Optional. Invite link name
expire_date Integer Optional. Point in time (Unix timestamp) when the link will expire or has been expired
member_limit Integer Optional. The maximum number of users that can be members of the chat simultaneously after joining the chat via this invite link; 1-99999
pending_join_request_count Integer Optional. Number of pending join requests created using this link

ChatAdministratorRights

Represents the rights of an administrator in a chat.

Field Type Description
is_anonymous Boolean True, if the user’s presence in the chat is hidden
can_manage_chat Boolean True, if the administrator can access the chat event log, boost list in channels, see channel members, report spam messages, see anonymous administrators in supergroups and ignore slow mode. Implied by any other administrator privilege
can_delete_messages Boolean True, if the administrator can delete messages of other users
can_manage_video_chats Boolean True, if the administrator can manage video chats
can_restrict_members Boolean True, if the administrator can restrict, ban or unban chat members, or access supergroup statistics
can_promote_members Boolean True, if the administrator can add new administrators with a subset of their own privileges or demote administrators that they have promoted, directly or indirectly (promoted by administrators that were appointed by the user)
can_change_info Boolean True, if the user is allowed to change the chat title, photo and other settings
can_invite_users Boolean True, if the user is allowed to invite new users to the chat
can_post_messages Boolean OptionalTrue, if the administrator can post messages in the channel, or access channel statistics; channels only
can_edit_messages Boolean OptionalTrue, if the administrator can edit messages of other users and can pin messages; channels only
can_pin_messages Boolean OptionalTrue, if the user is allowed to pin messages; groups and supergroups only
can_post_stories Boolean OptionalTrue, if the administrator can post stories in the channel; channels only
can_edit_stories Boolean OptionalTrue, if the administrator can edit stories posted by other users; channels only
can_delete_stories Boolean OptionalTrue, if the administrator can delete stories posted by other users; channels only
can_manage_topics Boolean OptionalTrue, if the user is allowed to create, rename, close, and reopen forum topics; supergroups only

Leave a Reply

Your email address will not be published. Required fields are marked *