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 identifier 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. This update may at times be triggered by changes to message fields that are either unavailable or not actively used by your bot.
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. This update may at times be triggered by changes to message fields that are either unavailable or not actively used by your bot.
business_connection BusinessConnection Optional. The bot was connected to or disconnected from a business account, or a user edited an existing connection with the bot
business_message Message Optional. New message from a connected business account
edited_business_message Message Optional. New version of a message from a connected business account
deleted_business_messages BusinessMessagesDeleted Optional. Messages were deleted from a connected business account
message_reaction MessageReactionUpdated Optional. A reaction to a message was changed by a user. The bot must be an administrator in the chat and must explicitly specify in the list of allowed_updates to receive these updates. The update isn’t received for reactions set by bots."message_reaction"
message_reaction_count MessageReactionCountUpdated Optional. Reactions to a message with anonymous reactions were changed. The bot must be an administrator in the chat and must explicitly specify in the list of allowed_updates to receive these updates. The updates are grouped and can be sent with delay up to a few minutes."message_reaction_count"
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
purchased_paid_media PaidMediaPurchased Optional. A user purchased paid media with a non-empty payload sent by the bot in a non-channel chat
poll Poll Optional. New poll state. Bots receive only updates about manually 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 in the list of allowed_updates to receive these updates."chat_member"
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.
chat_boost ChatBoostUpdated Optional. A chat boost was added or changed. The bot must be an administrator in the chat to receive these updates.
removed_chat_boost ChatBoostRemoved Optional. A boost was removed from a chat. The bot must be an administrator 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 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, message_reaction, and message_reaction_count (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.["message", "edited_channel_post", "callback_query"] |

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.

使用此方法指定URL，并通过传出的webhook接收传入的更新。每当机器人有更新时，我们将向指定的URL发送HTTPS POST请求，其中包含json序列化的update。如果请求不成功，我们将在合理次数的尝试后放弃。成功时返回True。

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.

如果您想确保webhook是由您设置的，您可以在参数secret中指定秘密数据_令牌。如果指定，请求将包含一个标题“X-Telegram-Bot-Api-Secret-Token”，其内容为秘密令牌。

Parameter Type Required Description
url String Yes HTTPS URL to send updates to. Use an empty string to remove webhook integration
发送更新到的HTTPS URL。使用空字符串删除webhook集成
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
用于发送webhook请求的固定IP地址，而不是通过DNS解析的IP地址
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.
允许同时连接到webhook进行更新传递的最大HTTPS连接数，1-100。默认为40。使用较低的值来限制bot服务器上的负载，使用较高的值来增加bot的吞吐量。
allowed_updates Array of String Optional
可选 A JSON-serialized list of the update types you want your bot to receive. For example, specify 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, message_reaction, and message_reaction_count (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
您希望bot接收的更新类型的json序列化列表。例如，指定只接收这些类型的更新。有关可用更新类型的完整列表，请参阅更新。指定一个空列表来接收除聊天之外的所有更新类型_成员信息_反应和信息_反应_数(默认)。如果未指定，将使用先前的设置。请注意，此参数不会影响调用setWebhook之前创建的更新，因此可能会在短时间内收到不需要的更新time.["message", "edited_channel_post", "callback_query"]
drop_pending_updates Boolean Optional
可选 Pass True to drop all pending updates
传递True以删除所有挂起的更新
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 , , , and are allowed. The header is useful to ensure that the request comes from a webhook set by you.A-Za-z0-9_-
在每个webhook请求中以“X-Telegram-Bot-Api-Secret-Token”头发送的秘密令牌，1-256个字符。只允许字符、、和。头信息对于确保请求来自你设置的webhook非常有用。A-Za-z0-9_-

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 webhooks: 443, 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.

如果您决定切换回getuupdates，可以使用此方法删除webhook集成。成功时返回True。

Parameter Type Required Description
drop_pending_updates Boolean Optional Pass True to drop all pending updates
传递True以删除所有挂起的更新

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 Optional. True, if this user is a Telegram Premium user
added_to_attachment_menu True Optional. True, if this user added the bot to the attachment menu
can_join_groups Boolean Optional. True, if the bot can be invited to groups. Returned only in getMe.
can_read_all_group_messages Boolean Optional. True, if privacy mode is disabled for the bot. Returned only in getMe.
supports_inline_queries Boolean Optional. True, if the bot supports inline queries. Returned only in getMe.
can_connect_to_business Boolean Optional. True, if the bot can be connected to a Telegram Business account to receive its messages. Returned only in getMe.
has_main_web_app Boolean Optional. True, if the bot has a main Web App. 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 the 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 Optional. True, if the supergroup chat is a forum (has topics enabled)

ChatFullInfo

This object contains full information about 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 the 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 Optional. True, if the supergroup chat is a forum (has topics enabled)
accent_color_id Integer Identifier of the accent color for the chat name and backgrounds of the chat photo, reply header, and link preview. See accent colors for more details.
max_reaction_count Integer The maximum number of reactions that can be set on a message in the chat
photo ChatPhoto Optional. Chat photo
active_usernames Array of String Optional. If non-empty, the list of all active chat usernames; for private chats, supergroups and channels
birthdate Birthdate Optional. For private chats, the date of birth of the user
business_intro BusinessIntro Optional. For private chats with business accounts, the intro of the business
business_location BusinessLocation Optional. For private chats with business accounts, the location of the business
business_opening_hours BusinessOpeningHours Optional. For private chats with business accounts, the opening hours of the business
personal_chat Chat Optional. For private chats, the personal channel of the user
available_reactions Array of ReactionType Optional. List of available reactions allowed in the chat. If omitted, then all emoji reactions are allowed.
background_custom_emoji_id String Optional. Custom emoji identifier of the emoji chosen by the chat for the reply header and link preview background
profile_accent_color_id Integer Optional. Identifier of the accent color for the chat’s profile background. See profile accent colors for more details.
profile_background_custom_emoji_id String Optional. Custom emoji identifier of the emoji chosen by the chat for its profile background
emoji_status_custom_emoji_id String Optional. Custom emoji identifier of the emoji status of the chat or the other party in a private chat
emoji_status_expiration_date Integer Optional. Expiration date of the emoji status of the chat or the other party in a private chat, in Unix time, if any
bio String Optional. Bio of the other party in a private chat
has_private_forwards True Optional. True, if privacy settings of the other party in the private chat allows to use links only in chats with the usertg://user?id=<user_id>
has_restricted_voice_and_video_messages True Optional. True, if the privacy settings of the other party restrict sending voice and video note messages in the private chat
join_to_send_messages True Optional. True, if users need to join the supergroup before they can send messages
join_by_request True Optional. True, if all users directly joining the supergroup without using an invite link need to be approved by supergroup administrators
description String Optional. Description, for groups, supergroups and channel chats
invite_link String Optional. Primary invite link, for groups, supergroups and channel chats
pinned_message Message Optional. The most recent pinned message (by sending date)
permissions ChatPermissions Optional. Default chat member permissions, for groups and supergroups
can_send_paid_media True Optional. True, if paid media messages can be sent or forwarded to the channel chat. The field is available only for channel chats.
slow_mode_delay Integer Optional. For supergroups, the minimum allowed delay between consecutive messages sent by each unprivileged user; in seconds
unrestrict_boost_count Integer Optional. For supergroups, the minimum number of boosts that a non-administrator user needs to add in order to ignore slow mode and chat permissions
message_auto_delete_time Integer Optional. The time after which all messages sent to the chat will be automatically deleted; in seconds
has_aggressive_anti_spam_enabled True Optional. True, if aggressive anti-spam checks are enabled in the supergroup. The field is only available to chat administrators.
has_hidden_members True Optional. True, if non-administrators can only get the list of bots and administrators in the chat
has_protected_content True Optional. True, if messages from the chat can’t be forwarded to other chats
has_visible_history True Optional. True, if new chat members will have access to old messages; available only to chat administrators
sticker_set_name String Optional. For supergroups, name of the group sticker set
can_set_sticker_set True Optional. True, if the bot can change the group sticker set
custom_emoji_sticker_set_name String Optional. For supergroups, the name of the group’s custom emoji sticker set. Custom emoji from this set can be used by all users and bots in the group.
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.
location ChatLocation Optional. For supergroups, the location to which the supergroup is connected

Message

This object represents a message.

Field Type Description
message_id Integer Unique message identifier inside this chat. In specific instances (e.g., message containing a video sent to a big chat), the server might automatically schedule a message instead of sending it immediately. In such cases, this field will be 0 and the relevant message will be unusable until it is actually sent
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; may be empty for messages sent to channels. For backward compatibility, if the message was sent on behalf of a chat, the field contains a fake sender user in non-channel chats
sender_chat Chat Optional. Sender of the message when sent on behalf of a chat. For example, the supergroup itself for messages sent by its anonymous administrators or a linked channel for messages automatically forwarded to the channel’s discussion group. For backward compatibility, if the message was sent on behalf of a chat, the field from contains a fake sender user in non-channel chats.
sender_boost_count Integer Optional. If the sender of the message boosted the chat, the number of boosts added by the user
sender_business_bot User Optional. The bot that actually sent the message on behalf of the business account. Available only for outgoing messages sent on behalf of the connected business account.
date Integer Date the message was sent in Unix time. It is always a positive number, representing a valid date.
business_connection_id String Optional. Unique identifier of the business connection from which the message was received. If non-empty, the message belongs to a chat of the corresponding business account that is independent from any potential bot chat which might share the same identifier.
chat Chat Chat the message belongs to
forward_origin MessageOrigin Optional. Information about the original message for forwarded messages
is_topic_message True Optional. True, if the message is sent to a forum topic
is_automatic_forward True Optional. True, if the message is a channel post that was automatically forwarded to the connected discussion group
reply_to_message Message Optional. For replies in the same chat and message thread, 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.
external_reply ExternalReplyInfo Optional. Information about the message that is being replied to, which may come from another chat or forum topic
quote TextQuote Optional. For replies that quote part of the original message, the quoted part of the message
reply_to_story Story Optional. For replies to a story, the original story
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 Optional. True, if the message can’t be forwarded
is_from_offline True Optional. True, if the message was sent by an implicit action, for example, as an away or a greeting business message, or as a scheduled message
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
link_preview_options LinkPreviewOptions Optional. Options used for link preview generation for the message, if it is a text message and link preview options were changed
effect_id String Optional. Unique identifier of the message effect added to the message
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
paid_media PaidMediaInfo Optional. Message contains paid media; information about the paid media
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, paid media, 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
show_caption_above_media True Optional. True, if the caption must be shown above the message media
has_media_spoiler True Optional. True, 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 MaybeInaccessibleMessage Optional. Specified message was pinned. Note that the Message object in this field will not contain further reply_to_message fields even if it itself is 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 »
refunded_payment RefundedPayment Optional. Message is a service message about a refunded payment, information about the payment. More about payments »
users_shared UsersShared Optional. Service message: users were 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.
boost_added ChatBoostAdded Optional. Service message: user boosted the chat
chat_background_set ChatBackground Optional. Service message: chat background set
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
giveaway_created GiveawayCreated Optional. Service message: a scheduled giveaway was created
giveaway Giveaway Optional. The message is a scheduled giveaway message
giveaway_winners GiveawayWinners Optional. A giveaway with public winners was completed
giveaway_completed GiveawayCompleted Optional. Service message: a giveaway without public winners was completed
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. buttons are represented as ordinary buttons.login_url``url

MessageId

This object represents a unique message identifier.

Field Type Description
message_id Integer Unique message identifier. In specific instances (e.g., message containing a video sent to a big chat), the server might automatically schedule a message instead of sending it immediately. In such cases, this field will be 0 and the relevant message will be unusable until it is actually sent

InaccessibleMessage

This object describes a message that was deleted or is otherwise inaccessible to the bot.

Field Type Description
chat Chat Chat the message belonged to
message_id Integer Unique message identifier inside the chat
date Integer Always 0. The field can be used to differentiate regular and inaccessible messages.

MaybeInaccessibleMessage

This object describes a message that can be inaccessible to the bot. It can be one of

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” (), “hashtag” ( or ), “cashtag” ( or ), “bot_command” (), “url” (), “email” (), “phone_number” (), “bold” (bold text), “italic” (italic text), “underline” (underlined text), “strikethrough” (strikethrough text), “spoiler” (spoiler message), “blockquote” (block quotation), “expandable_blockquote” (collapsed-by-default block quotation), “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)@username``#hashtag``#hashtag@chatusername``$USD``$USD@chatusername``/start@jobs_bot``https://telegram.org``do-not-reply@telegram.org``+1-212-555-0123
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

sendMessage

Use this method to send text messages. On success, the sent Message is returned.

使用此方法发送短信。如果成功，则返回发送的Message。

Parameter Type Required Description
business_connection_id String Optional Unique identifier of the business connection on behalf of which the message will be sent
将代表其发送消息的业务连接的唯一标识符
chat_id Integer or String Yes Unique identifier for the target chat or username of the target channel (in the format @channelusername)
目标聊天或目标通道的用户名的唯一标识符（格式为@channelusername）
message_thread_id Integer Optional Unique identifier for the target message thread (topic) of the forum; for forum supergroups only
论坛的目标消息线程（主题）的唯一标识符；仅适用于论坛超级组
text String Yes Text of the message to be sent, 1-4096 characters after entities parsing
要发送的消息文本，经过实体解析后的1-4096个字符
parse_mode String Optional Mode for parsing entities in the message text. See formatting options for more details.
用于解析消息文本中的实体的模式。有关详细信息，请参阅格式化选项
entities Array of MessageEntity Optional A JSON-serialized list of special entities that appear in message text, which can be specified instead of parse_mode
出现在消息文本中的特殊实体的json序列化列表，可以指定而不是解析_模式
link_preview_options LinkPreviewOptions Optional Link preview generation options for the message
消息的链接预览生成选项
disable_notification Boolean Optional Sends the message silently. Users will receive a notification with no sound.
以静默方式发送消息。用户将会收到一个没有声音的通知。
protect_content Boolean Optional Protects the contents of the sent message from forwarding and saving
保护已发送邮件的内容不被转发和保存
allow_paid_broadcast Boolean Optional Pass True to allow up to 1000 messages per second, ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message. The relevant Stars will be withdrawn from the bot’s balance
设置为True允许每秒发送1000条消息，忽略广播限制，每条消息收费0.1 Telegram Stars。相关的Stars将从bot的余额中扣除
message_effect_id String Optional Unique identifier of the message effect to be added to the message; for private chats only
要添加到消息中的消息效果的唯一标识符；仅限私人聊天
reply_parameters ReplyParameters Optional Description of the message to reply to
要回复的消息的描述
reply_markup InlineKeyboardMarkup or ReplyKeyboardMarkup or ReplyKeyboardRemove or ForceReply Optional Additional interface options. A JSON-serialized object for an inline keyboard, custom reply keyboard, instructions to remove a reply keyboard or to force a reply from the user
附加接口选项。一个json序列化的对象，用于内联键盘、自定义回复键盘、删除回复键盘或强制用户回复的指令

html实体消息发送

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
<b>bold</b>, <strong>bold</strong>
<i>italic</i>, <em>italic</em>
<u>underline</u>, <ins>underline</ins>
<s>strikethrough</s>, <strike>strikethrough</strike>, <del>strikethrough</del>
<span class="tg-spoiler">spoiler</span>, <tg-spoiler>spoiler</tg-spoiler>
<b>bold <i>italic bold <s>italic bold strikethrough <span class="tg-spoiler">italic bold strikethrough spoiler</span></s> <u>underline italic bold</u></i> bold</b>
<a href="http://www.example.com/">inline URL</a>
<a href="tg://user?id=123456789">inline mention of a user</a>
<tg-emoji emoji-id="5368324170671202286">👍</tg-emoji>
<code>inline fixed-width code</code>
<pre>pre-formatted fixed-width code block</pre>
<pre><code class="language-python">pre-formatted fixed-width code block written in the Python programming language</code></pre>
<blockquote>Block quotation started\nBlock quotation continued\nThe last line of the block quotation</blockquote>
<blockquote expandable>Expandable block quotation started\nExpandable block quotation continued\nExpandable block quotation continued\nHidden by default part of the block quotation started\nExpandable block quotation continued\nThe last line of the block quotation</blockquote>

bold, bold italic, italic underline, underline strikethrough, strikethrough, strikethrough spoiler, spoiler bold italic bold italic bold strikethrough italic bold strikethrough spoiler underline italic bold bold inline URL inline mention of a user ?? inline fixed-width code

1
pre-formatted fixed-width code block
1
pre-formatted fixed-width code block written in the Python programming language

Block quotation started\nBlock quotation continued\nThe last line of the block quotation

Expandable block quotation started\nExpandable block quotation continued\nExpandable block quotation continued\nHidden by default part of the block quotation started\nExpandable block quotation continued\nThe last line of the block quotation

Formatting options

The Bot API supports basic formatting for messages. You can use bold, italic, underlined, strikethrough, spoiler text, block quotations as well as inline links and pre-formatted code in your bots’ messages. Telegram clients will render them accordingly. You can specify text entities directly, or use markdown-style or HTML-style formatting.

Note that Telegram clients will display an alert to the user before opening an inline link (‘Open this link?’ together with the full URL).

Message entities can be nested, providing following restrictions are met:
- If two entities have common characters, then one of them is fully contained inside another.
- bold, italic, underline, strikethrough, and spoiler entities can contain and can be part of any other entities, except pre and code.
- blockquote and expandable_blockquote entities can’t be nested.
- All other entities can’t contain each other.

Links can be used to mention a user by their identifier without using a username. Please note:tg://user?id=<user_id>

  • These links will work only if they are used inside an inline link or in an inline keyboard button. For example, they will not work, when used in a message text.

  • Unless the user is a member of the chat where they were mentioned, these mentions are only guaranteed to work if the user has contacted the bot in private in the past or has sent a callback query to the bot via an inline button and doesn’t have Forwarded Messages privacy enabled for the bot.

You can find the list of programming and markup languages for which syntax highlighting is supported at libprisma#supported-languages.

MarkdownV2 style

To use this mode, pass MarkdownV2 in the parse_mode field. Use the following syntax in your message:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
*bold \*text*
_italic \*text_
__underline__
~strikethrough~
||spoiler||
*bold _italic bold ~italic bold strikethrough ||italic bold strikethrough spoiler||~ __underline italic bold___ bold*
[inline URL](http://www.example.com/)
[inline mention of a user](tg://user?id=123456789)
![](tg://emoji?id=5368324170671202286)
`inline fixed-width code`
```
pre-formatted fixed-width code block
```
```python
pre-formatted fixed-width code block written in the Python programming language
```
>Block quotation started
>Block quotation continued
>Block quotation continued
>Block quotation continued
>The last line of the block quotation
**>The expandable block quotation started right after the previous block quotation
>It is separated from the previous block quotation by an empty bold entity
>Expandable block quotation continued
>Hidden by default part of the expandable block quotation started
>Expandable block quotation continued
>The last line of the expandable block quotation with the expandability mark||

Please note:

  • Any character with code between 1 and 126 inclusively can be escaped anywhere with a preceding ‘\‘ character, in which case it is treated as an ordinary character and not a part of the markup. This implies that ‘\‘ character usually must be escaped with a preceding ‘\‘ character.

  • Inside and entities, all ‘`‘ and ‘\‘ characters must be escaped with a preceding ‘\‘ character.pre``code

  • Inside the part of the inline link and custom emoji definition, all ‘)’ and ‘\‘ must be escaped with a preceding ‘\‘ character.(...)

  • In all other places characters ‘_‘, ‘*‘, ‘[‘, ‘]‘, ‘(‘, ‘)’, ‘~’, ‘`‘, ‘>’, ‘#’, ‘+’, ‘-‘, ‘=’, ‘|’, ‘{‘, ‘}’, ‘.’, ‘!’ must be escaped with the preceding character ‘\‘.

  • In case of ambiguity between and entities is always greadily treated from left to right as beginning or end of an entity, so instead of use , adding an empty bold entity as a separator.italic``underline``__``underline``___italic underline___``___italic underline_**__

  • A valid emoji must be provided as an alternative value for the custom emoji. The emoji will be shown instead of the custom emoji in places where a custom emoji cannot be displayed (e.g., system notifications) or if the message is forwarded by a non-premium user. It is recommended to use the emoji from the emoji field of the custom emoji sticker.

  • Custom emoji entities can only be used by bots that purchased additional usernames on Fragment.

HTML style

To use this mode, pass HTML in the parse_mode field. The following tags are currently supported:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
<b>bold</b>, <strong>bold</strong>
<i>italic</i>, <em>italic</em>
<u>underline</u>, <ins>underline</ins>
<s>strikethrough</s>, <strike>strikethrough</strike>, <del>strikethrough</del>
<span class="tg-spoiler">spoiler</span>, <tg-spoiler>spoiler</tg-spoiler>
<b>bold <i>italic bold <s>italic bold strikethrough <span class="tg-spoiler">italic bold strikethrough spoiler</span></s> <u>underline italic bold</u></i> bold</b>
<a href="http://www.example.com/">inline URL</a>
<a href="tg://user?id=123456789">inline mention of a user</a>
<tg-emoji emoji-id="5368324170671202286"></tg-emoji>
<code>inline fixed-width code</code>
<pre>pre-formatted fixed-width code block</pre>
<pre><code class="language-python">pre-formatted fixed-width code block written in the Python programming language</code></pre>
<blockquote>Block quotation started\nBlock quotation continued\nThe last line of the block quotation</blockquote>
<blockquote expandable>Expandable block quotation started\nExpandable block quotation continued\nExpandable block quotation continued\nHidden by default part of the block quotation started\nExpandable block quotation continued\nThe last line of the block quotation</blockquote>

Please note:

  • Only the tags mentioned above are currently supported.

  • All , and symbols that are not a part of a tag or an HTML entity must be replaced with the corresponding HTML entities ( with , with and with ).<``>``&``<``&lt;``>``&gt;``&``&amp;

  • All numerical HTML entities are supported.

  • The API currently supports only the following named HTML entities: , , and .&lt;``&gt;``&amp;``&quot;

  • Use nested and tags, to define programming language for entity.pre``code``pre

  • Programming language can’t be specified for standalone tags.code

  • A valid emoji must be used as the content of the tag. The emoji will be shown instead of the custom emoji in places where a custom emoji cannot be displayed (e.g., system notifications) or if the message is forwarded by a non-premium user. It is recommended to use the emoji from the emoji field of the custom emoji sticker.tg-emoji

  • Custom emoji entities can only be used by bots that purchased additional usernames on Fragment.

Markdown style

This is a legacy mode, retained for backward compatibility. To use this mode, pass Markdown in the parse_mode field. Use the following syntax in your message:

1
2
3
4
5
6
7
8
9
10
11
*bold text*
_italic text_
[inline URL](http://www.example.com/)
[inline mention of a user](tg://user?id=123456789)
`inline fixed-width code`
```
pre-formatted fixed-width code block
```
```python
pre-formatted fixed-width code block written in the Python programming language
```

Please note:

  • Entities must not be nested, use parse mode MarkdownV2 instead.

  • There is no way to specify “underline”, “strikethrough”, “spoiler”, “blockquote”, “expandable_blockquote” and “custom_emoji” entities, use parse mode MarkdownV2 instead.

  • To escape characters ‘_‘, ‘*‘, ‘`‘, ‘[‘ outside of an entity, prepend the characters ‘\‘ before them.

  • Escaping inside entities is not allowed, so entity must be closed first and reopened again: use for italic and for bold ._snake_\__case_``snake_case``*2*\**2=4*``2*2=4

By default, all bots are able to broadcast up to 30 messages per second to their users. Developers can increase this limit by enabling Paid Broadcasts in @Botfather - allowing their bot to broadcast up to 1000 messages per second.

Each message broadcasted over the free amount of 30 messages per second incurs a cost of 0.1 Stars per message, paid with Telegram Stars from the bot’s balance. In order to use this feature, a bot must have at least 10,000 Stars on its balance.

Bots with increased limits are only charged for messages that are broadcasted successfully.

Telegram Bot API