Types

The JSON objects of the Bot API. Fields marked ? are left out when empty; nothing is ever sent as null unless the field says so.

All ids are JSON integers below 2⁵³, so they are exact in JavaScript. Store them as 64-bit integers.

Update · BotInfo · User · Chat · Message · MessageEntity · InlineKeyboardMarkup · InlineKeyboardButton · CallbackQuery · ChatMemberUpdated · ChatMember · ChatRights · BotCommand · BotCommandScope · BotStarted · File · ChatInviteLink · WebhookInfo · EncryptedMessage · EncryptionKeyInfo

`Update`#

One update. Exactly one of the optional fields is present.

Field	Type	Description
`update_id`	Integer	Increases per bot. Acknowledge with `getUpdates(offset = update_id + 1)`. With webhooks, de-duplicate on it.
`message?`	Message	A message in a private chat or a group (privacy rules apply).
`edited_message?`	Message	An edited message the bot would receive now. Edits of encrypted rows are never delivered.
`channel_post?`	Message	A post in a channel the bot was added to.
`edited_channel_post?`	Message	An edited channel post.
`callback_query?`	CallbackQuery	A press of one of the bot's buttons.
`my_chat_member?`	ChatMemberUpdated	The bot was added, its rights changed, it was removed, suspended when a group became encrypted, attached or detached.
`chat_member?`	ChatMemberUpdated	A member joined, left, was banned, muted or unmuted. Opt-in, groups only (see Updates).
`bot_started?`	BotStarted	A person pressed Start.
`bot_blocked?`	BotStarted	A person stopped or blocked the bot (no `start_param`).
`encrypted_message?`	EncryptedMessage	An end-to-end encrypted message or press for an encrypted bot.

`BotInfo`#

The result of getMe.

Field	Type	Description
`id`	Integer	The bot number.
`is_bot`	Boolean	Always `true`.
`first_name`	String	Display name.
`username`	String	Handle, ends in `bot`.
`can_join_groups`	Boolean
`can_join_channels`	Boolean
`privacy_mode`	Boolean	`true`: in groups the bot sees only commands, mentions and replies to it.
`e2ee_mode`	String	`plain` or `encrypted`.
`api_version`	String	`"1.0"`.
`status`	String	`development`, `active`, `restricted`, …
`tier`	String	`new`, `standard` or `verified`.

`User`#

A person or a bot. People's ids are pseudonymous: different for every bot owner (see Concepts).

Field	Type	Description
`id`	Integer	A person: a large positive integer below 2⁵³. A bot: its bot number.
`is_bot`	Boolean
`first_name`	String	The person's name, as other members of a shared room see it; `"Qivuna user"` when blank.
`last_name?`	String
`username?`	String	Only if the person lets others find them by username.
`e2ee_key?`	String	Encrypted updates only: the person's public key for this bot's namespace (base64 X25519). The SDKs pin it.

`Chat`#

Field	Type	Description
`id`	Integer	Private chat: the person's id. Group or channel: a negative integer.
`type`	String	`private`, `group` or `channel`.
`title?`	String	Groups and channels.
`username?`	String	Public groups and channels with a handle; for a private chat the person's handle (if findable).
`first_name?`	String	Private chats.
`is_e2ee`	Boolean	End-to-end encrypted: an encrypted bot's private chat, or an encrypted group.
`description?`	String	`getChat` only.
`member_count?`	Integer	`getChat` only, groups and channels.

`Message`#

Field	Type	Description
`message_id`	Integer	Pseudonymous, per bot owner.
`date`	Integer	Unix time.
`edit_date?`	Integer
`chat`	Chat
`from?`	User	Absent for channel posts.
`sender_chat?`	Chat	Channel posts: the channel.
`text?`	String	Absent when the message has files (then `caption`) or is end-to-end encrypted (then `envelope`).
`entities?`	Array of MessageEntity	The bot's own messages: the formatting it sent. People's messages: only the leading `bot_command` and `mention`s (people's rich text is not passed on).
`command?`	Object	`{name, args, addressed_to_me}` when a person's message starts with a command. `name` is lower case, `args` the rest of the text.
`reply_to_message?`	Message	The full message if this bot sent it; otherwise only `{message_id}`.
`reply_markup?`	InlineKeyboardMarkup	Only on the bot's own messages, with its `callback_data`. Nobody else ever receives callback data.
`protect_content?`	Boolean	The bot's own messages.
`photo? / video? / document?`	File	The first attachment, by its stored type. One File, not a list of sizes.
`attachments?`	Array of Object	When a person sent more than one file: every file, in order, as `{type, …File}`.
`caption?`	String	Text of a message with files.
`caption_entities?`	Array of MessageEntity
`envelope?`	String	End-to-end encrypted rows in an encrypted bot's private chat.

`MessageEntity`#

Offsets and lengths are in UTF-16 code units (as in Telegram).

Field	Type	Description
`type`	String	`bold`, `italic`, `underline`, `strikethrough`, `code`, `pre`, `text_link`, `url`, `mention`, `bot_command`, `spoiler`.
`offset`	Integer	≥ 0.
`length`	Integer	≥ 1; the entity must lie inside the text.
`url?`	String	`text_link`: an `https://` URL without user info, at most 2,048 characters.
`language?`	String	`pre`: `[A-Za-z0-9_+#.-]{1,32}`.

`InlineKeyboardMarkup`#

{"inline_keyboard": [[button, …], …]}. No other key. At most 10 rows, 8 buttons a row, 64 buttons.

Field	Type	Description
`inline_keyboard`	Array of Array of InlineKeyboardButton	`[]` means no keyboard.

`InlineKeyboardButton`#

Exactly one of callback_data and url; any other field is refused.

Field	Type	Description
`text`	String	1–40 characters, no control characters; invisible formatting characters are removed first.
`callback_data?`	String	1–64 bytes. Comes back in `callback_query.data`.
`url?`	String	`https://`, no user info, at most 512 characters. The app shows the registrable domain before opening it.

`CallbackQuery`#

Field	Type	Description
`id`	String	26 characters. Answer it with `answerCallbackQuery` within 15 minutes.
`from`	User	Who pressed.
`message`	Message	The bot's message with the keyboard.
`data`	String	The button's `callback_data`.

`ChatMemberUpdated`#

Used by my_chat_member (the bot itself) and chat_member (a member).

Field	Type	Description
`chat`	Chat
`from?`	User	Who made the change, when known.
`date`	Integer
`user?`	User	`chat_member` only: the member.
`old_status / new_status`	String	`my_chat_member`: `member`, `left`, `suspended_e2ee`, `attached`, `detached`. `chat_member`: `member`, `left`, `kicked`, `restricted`.
`rights?`	ChatRights	`my_chat_member`: the rights the bot has now.
`mode?`	String	`server` or `addressed` (encrypted groups).
`consent_receipt_id?`	String	The id (a ULID string) of the immutable consent receipt the admin's action created.
`until_date?`	Integer	`chat_member`, `restricted`: end of a timed mute.

`ChatMember`#

Field	Type	Description
`user`	User
`status`	String	`owner`, `admin`, `member`, `restricted` (muted), `kicked` (banned), `left`.
`until_date?`	Integer	A bot's timed mute.

`ChatRights`#

Booleans. Absent = false.

Field	Type	Description
`can_send`	Boolean	Groups: send text. Default on.
`can_send_media`	Boolean	Groups and channels: send files. Default on.
`can_read_all`	Boolean	Public groups only, and only with the bot's privacy mode off: receive every message. Off by default; shown to admins in red.
`can_delete_messages`	Boolean	Groups.
`can_restrict_members`	Boolean	Groups: mute.
`can_ban_members`	Boolean	Groups.
`can_pin`	Boolean	Groups.
`can_invite`	Boolean	Groups and channels: create invite links.
`can_post`	Boolean	Channels: post. Default on.
`can_edit_posts`	Boolean	Channels: edit others' posts (own posts are always editable).
`can_change_info`	Boolean	Reserved: no v1 method uses it and it cannot be granted.

`BotCommand`#

Field	Type	Description
`command`	String	`^[a-z0-9_]{1,32}$`, without the slash.
`description`	String	1–256 characters.

`BotCommandScope`#

Field	Type	Description
`type`	String	`default`, `all_private_chats`, `all_group_chats`, `all_chat_administrators` or `chat`.
`chat_id?`	Integer	Only with `chat`: a room the bot is in, or a person who started it.

`BotStarted`#

bot_started and bot_blocked.

Field	Type	Description
`from`	User
`chat`	Chat	The private chat.
`start_param?`	String	`bot_started`: the `start` value of the link the person opened (≤ 64 of `A–Z a–z 0–9 _ -`).
`date`	Integer

`File`#

Field	Type	Description
`file_id`	String	40 hex characters, valid for this bot only, at most 30 days.
`file_unique_id`	String	Stable for the same file within the bot's id namespace (shared by the bots its owner created); unlinkable across namespaces.
`file_size`	Integer	Bytes.
`mime_type?`	String
`file_name?`	String
`file_path?`	String	`getFile` only: download at `/v1/file/<file_path>` for 1 hour.

`ChatInviteLink`#

Field	Type	Description
`invite_link`	String
`expire_date?`	Integer
`member_limit?`	Integer
`is_revoked`	Boolean

`WebhookInfo`#

Field	Type	Description
`url`	String	`""` when no webhook is set.
`has_secret`	Boolean
`pending_update_count`	Integer
`max_connections`	Integer
`allowed_updates`	Array of String	The effective list (the default set when none is stored).
`encrypt_payload`	Boolean
`last_error_date? / last_error_message?`	Integer / String	Kept after a disable, so you can see why. Our own wording; never the response body or the URL.
`failing_since?`	Integer	While the webhook is enabled and failing.

`EncryptedMessage`#

encrypted_message: content the server cannot read.

Field	Type	Description
`message_id`	Integer	1:1: the message's id. Encrypted groups: the id of this request (it is not a group message).
`date`	Integer
`chat`	Chat	`is_e2ee: true`. Server-asserted: bind your answer to it, never authorise on it.
`from`	User	With `e2ee_key` (the sender key the envelope opens with).
`kind`	String	`message` or `callback`.
`envelope`	String	`s2\|…`, sealed by the person to the bot's key. The plaintext is a QB1 request.
`reply_token?`	String	Encrypted groups: `rt1_…`, 5 replies within 1 hour.
`callback_query_id?`	String	Presses.

`EncryptionKeyInfo`#

Field	Type	Description
`active`	Object or null	`{fingerprint, seq, activated_at}` (unix seconds).
`proposed`	Object or null	`{fingerprint, proposed_at}`.
`bot_id`	Integer	The bot account's user id (the `bot` field of QB1).

Types

Update#

BotInfo#

User#

Chat#

Message#

MessageEntity#

InlineKeyboardMarkup#

InlineKeyboardButton#

CallbackQuery#

ChatMemberUpdated#

ChatMember#

ChatRights#

BotCommand#

BotCommandScope#

BotStarted#

File#

ChatInviteLink#

WebhookInfo#

EncryptedMessage#

EncryptionKeyInfo#