Available types

Available types

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

• User
• GroupChat
• Message
• PhotoSize
• Audio
• Document
• Sticker
• Video
• Voice
• Contact
• Location
• Update
• InputFile
• UserProfilePhotos
• File
• ReplyKeyboardMarkup
• ReplyKeyboardHide
• ForceReply

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
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

GroupChat

This object represents a group chat.

Field	Type	Description
id	Integer	Unique identifier for this group chat
title	String	Group name

Message

This object represents a message.

Field	Type	Description
message_id	Integer	Unique message identifier
from	User	Sender
date	Integer	Date the message was sent in Unix time
chat	User or [GroupChat](#groupchat)	Conversation the message belongs to — user in case of a private message, GroupChat in case of a group
forward_from	User	Optional. For forwarded messages, sender of the original message
forward_date	Integer	Optional. For forwarded messages, date the original message was sent in Unix time
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.
text	String	Optional. For text messages, the actual UTF-8 text of the message
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
video	Video	Optional. Message is a video, information about the video
voice	Voice	Optional. Message is a voice message, information about the file
caption	String	Optional. Caption for the photo or video
contact	Contact	Optional. Message is a shared contact, information about the contact
location	Location	Optional. Message is a shared location, information about the location
new_chat_participant	User	Optional. A new member was added to the group, information about them (this member may be bot itself)
left_chat_participant	User	Optional. A member was removed from the group, information about them (this member may be bot itself)
new_chat_title	String	Optional. A group title was changed to this value
new_chat_photo	Array of PhotoSize	Optional. A group photo was change to this value
delete_chat_photo	True	Optional. Informs that the group photo was deleted
group_chat_created	True	Optional. Informs that the group has been created

PhotoSize

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

Field	Type	Description
file_id	String	Unique identifier for this file
width	Integer	Photo width
height	Integer	Photo height
file_size	Integer	Optional. File size

Audio

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

Field	Type	Description
file_id	String	Unique identifier for this 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
mime_type	String	Optional. MIME type of the file as defined by sender
file_size	Integer	Optional. File size

Document

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

Field	Type	Description
file_id	String	Unique file identifier
thumb	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

Sticker

This object represents a sticker.

Field	Type	Description
file_id	String	Unique identifier for this file
width	Integer	Sticker width
height	Integer	Sticker height
thumb	PhotoSize	Optional. Sticker thumbnail in .webp or .jpg format
file_size	Integer	Optional. File size

Video

This object represents a video file.

Field	Type	Description
file_id	String	Unique identifier for this 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
thumb	PhotoSize	Optional. Video thumbnail
mime_type	String	Optional. Mime type of a file as defined by sender
file_size	Integer	Optional. File size

Voice

This object represents a voice note.

Field	Type	Description
file_id	String	Unique identifier for this 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

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

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

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.

Maximum file size to download is 200MB

Field	Type	Description
file_id	String	Unique identifier for this file
file_size	Integer	Optional. File size, if known
file_path	String	Optional. File path. Use `https://api.telegram.org/file/bot/` to get the file.

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 String	Array of button rows, each represented by an Array of Strings
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. Defaults to _false_.
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.

ReplyKeyboardHide

Upon receiving a message with this object, Telegram clients will hide 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
hide_keyboard	True	Requests clients to hide the custom keyboard
selective	Boolean	Optional. Use this parameter if you want to hide 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 hides keyboard for that user, while still showing the keyboard with poll options to users who haven't voted yet.

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'
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.

InputFile

This object represents the contents of a file to be uploaded. Must be posted using multipart/form-data in the usual way that files are uploaded via the browser.

Resending files without reuploading

There are two ways of sending a file (photo, sticker, audio etc.). If it‘s a new file, you can upload it using multipart/form-data. If the file is already on our servers, you don’t need to reupload it: each file object has a file_id field, you can simply pass this file_id as a parameter instead.

• It is not possible to change the file type when resending by file_id. I.e. a Video can't be sent as a photo, a photo can't be sent as a document, etc.
• It is not possible to resend thumbnails.
• Resending a photo by file_id will send all of its sizes.