@telegram.ts/types 1.8.0 → 1.10.0

package/src/markupTypes.d.ts

@@ -1,7 +1,7 @@
 import type { ChatAdministratorRights, User } from "./manageTypes";
 import type { MaybeInaccessibleMessage } from "./messageTypes";
 
-/** This object represents an inline keyboard that appears right next to the message it belongs to. */
+/** This object represents one button of an inline keyboard. Exactly one of the optional fields must be used to specify type of the button. */
 export interface InlineKeyboardMarkup {
   /** Array of button rows, each represented by an Array of InlineKeyboardButton objects */
   inline_keyboard: InlineKeyboardButton[][];
@@ -17,11 +17,11 @@ export declare namespace InlineKeyboardButton {
     url: string;
   }
   export interface CallbackButton extends AbstractInlineKeyboardButton {
-    /** Data to be sent in a callback query to the bot when button is pressed, 1-64 bytes */
+    /** Data to be sent in a callback query to the bot when button is pressed, 1-64 bytes. Not supported for messages sent on behalf of a Telegram Business account. */
     callback_data: string;
   }
   export interface WebAppButton extends AbstractInlineKeyboardButton {
-    /** 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. */
+    /** 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. Not supported for messages sent on behalf of a Telegram Business account. */
     web_app: WebAppInfo;
   }
   export interface LoginButton extends AbstractInlineKeyboardButton {
@@ -29,19 +29,19 @@ export declare namespace InlineKeyboardButton {
     login_url: LoginUrl;
   }
   export interface SwitchInlineButton extends AbstractInlineKeyboardButton {
-    /** 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. Can be empty, in which case just the bot's username will be inserted. */
+    /** 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. Not supported for messages sent on behalf of a Telegram Business account. */
     switch_inline_query: string;
   }
   export interface SwitchInlineCurrentChatButton
     extends AbstractInlineKeyboardButton {
     /** If set, pressing the button will insert the bot's username and the specified inline query in the current chat's input field. Can 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. */
+    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. Not supported in channels and for messages sent on behalf of a Telegram Business account. */
     switch_inline_query_current_chat: string;
   }
   export interface SwitchInlineChosenChatButton
     extends AbstractInlineKeyboardButton {
-    /** 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 */
+    /** 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. Not supported for messages sent on behalf of a Telegram Business account. */
     switch_inline_query_chosen_chat: SwitchInlineQueryChosenChat;
   }
   export interface GameButton extends AbstractInlineKeyboardButton {
@@ -51,7 +51,7 @@ export declare namespace InlineKeyboardButton {
     callback_game: CallbackGame;
   }
   export interface PayButton extends AbstractInlineKeyboardButton {
-    /** Specify True, to send a Pay button.
+    /** Specify True, to send a Pay button. Substrings “⭐” and “XTR” in the buttons's text will be replaced with a Telegram Star icon.
 
     NOTE: This type of button must always be the first button in the first row and can only be used in invoice messages. */
     pay: boolean;
@@ -122,7 +122,7 @@ export interface CallbackQuery {
   game_short_name?: string;
 }
 
-/** This object represents a custom keyboard with reply options (see Introduction to bots for details and examples). */
+/** This object represents a custom keyboard with reply options (see Introduction to bots for details and examples). Not supported in channels and for messages sent on behalf of a Telegram Business account. */
 export interface ReplyKeyboardMarkup {
   /** Array of button rows, each represented by an Array of KeyboardButton objects */
   keyboard: KeyboardButton[][];
@@ -171,7 +171,7 @@ export declare namespace 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_app, request_users, request_chat, request_contact, request_location, and request_poll are mutually exclusive. */
+/** This object represents one button of the reply keyboard. At most one of the optional fields must be used to specify type of the button. For simple text buttons, String can be used instead of this object to specify the button text. */
 export type KeyboardButton =
   | KeyboardButton.CommonButton
   | KeyboardButton.RequestUsersButton
@@ -188,7 +188,7 @@ export interface KeyboardButtonPollType {
   type?: "quiz" | "regular";
 }
 
-/** 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). */
+/** 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). Not supported in channels and for messages sent on behalf of a Telegram Business account. */
 export interface ReplyKeyboardRemove {
   /** 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) */
   remove_keyboard: true;
@@ -198,7 +198,7 @@ export interface ReplyKeyboardRemove {
   selective?: boolean;
 }
 
-/** 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.
+/** 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. Not supported in channels and for messages sent on behalf of a Telegram Business account.
 
 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:
 
@@ -232,11 +232,11 @@ export interface KeyboardButtonRequestUsers {
   user_is_premium?: boolean;
   /** The maximum number of users to be selected; 1-10. Defaults to 1. */
   max_quantity?: boolean;
-  /** Pass True to request the users' first and last name */
+  /** Pass True to request the users' first and last names */
   request_name?: boolean;
-  /** Pass True to request the users' username */
+  /** Pass True to request the users' usernames */
   request_username?: boolean;
-  /** Pass True to request the users' photo */
+  /** Pass True to request the users' photos */
   request_photo?: boolean;
 }
 

package/src/messageTypes.d.ts

@@ -47,12 +47,16 @@ export declare namespace Message {
     edit_date?: number;
     /** True, if the message can't be forwarded */
     has_protected_content?: true;
+    /** True, if the caption must be shown above the message media */
+    show_caption_above_media?: true;
     /** 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 */
     is_from_offline?: true;
     /** Signature of the post author for messages in channels, or the custom title of an anonymous group administrator */
     author_signature?: string;
     /** Options used for link preview generation for the message, if it is a text message and link preview options were changed */
     link_preview_options?: LinkPreviewOptions;
+    /** Unique identifier of the message effect added to the message */
+    effect_id?: string;
     /** Inline keyboard attached to the message. login_url buttons are represented as ordinary url buttons. */
     reply_markup?: InlineKeyboardMarkup;
   }
@@ -119,6 +123,8 @@ export declare namespace Message {
   export type ProximityAlertTriggeredMessage = ServiceMessage &
     MsgWith<"proximity_alert_triggered">;
   export type BoostAddedMessage = ServiceMessage & MsgWith<"boost_added">;
+  export type ChatBackgroundSetMessage = ServiceMessage &
+    MsgWith<"chat_background_set">;
   export type ForumTopicCreatedMessage = ServiceMessage &
     MsgWith<"forum_topic_created">;
   export type ForumTopicEditedMessage = ServiceMessage &
@@ -228,6 +234,8 @@ export interface Message extends Message.MediaMessage {
   proximity_alert_triggered?: ProximityAlertTriggered;
   /** Service message: user boosted the chat */
   boost_added?: ChatBoostAdded;
+  /* Service message: chat background set */
+  chat_background_set?: ChatBackground;
   /** Service message: forum topic created */
   forum_topic_created?: ForumTopicCreated;
   /** Service message: forum topic edited */
@@ -303,7 +311,7 @@ Note that Telegram clients will display an **alert** to the user before opening
 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 entities can't be nested.
+- blockquote and expandable_blockquote entities can't be nested.
 - All other entities can't contain each other.
 
 Links `tg://user?id=<user_id>` can be used to mention a user by their ID without using a username. Please note:
@@ -335,9 +343,15 @@ pre-formatted fixed-width code block written in the Python programming language
 ```
 >Block quotation started
 >Block quotation continued
->The last line of the block quotation**
->The second block quotation started right after the previous\r
->The third block quotation started right after the previous
+>Block quotation continued
+>Block quotation continued
+>The last line of the block quotation
+***>The second expandable block quotation started right after the previous
+>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:
 
@@ -345,7 +359,7 @@ Please note:
 - Inside `pre` and `code` entities, all '`' and '\' characters must be escaped with a preceding '\' character.
 - 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 `italic` and `underline` entities `__` is always greadily treated from left to right as beginning or end of `underline` entity, so instead of `___italic underline___` use `___italic underline_\r__`, where `\r` is a character with code 13, which will be ignored.
+- In case of ambiguity between `italic` and `underline` entities `__` is always greadily treated from left to right as beginning or end of an `underline` entity, so instead of `___italic underline___` use `___italic underline_**__`, adding an empty bold entity as a separator.
 - 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.
 
@@ -366,6 +380,7 @@ To use this mode, pass *HTML* in the *parse_mode* field. The following tags are
 <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:
 
@@ -397,14 +412,14 @@ 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” and “custom_emoji” entities, 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 `_snake_\__case_` for italic `snake_case` and `*2*\**2=4*` for bold `2*2=4`. */
 export type ParseMode = "Markdown" | "MarkdownV2" | "HTML";
 
 export declare namespace MessageEntity {
   interface AbstractMessageEntity {
-    /** 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), “blockquote” (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) */
+    /** 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), “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) */
     type: string;
     /** Offset in UTF-16 code units to the start of the entity */
     offset: number;
@@ -426,6 +441,7 @@ export declare namespace MessageEntity {
       | "strikethrough"
       | "spoiler"
       | "blockquote"
+      | "expandable_blockquote"
       | "code";
   }
   export interface PreMessageEntity extends AbstractMessageEntity {
@@ -747,10 +763,22 @@ export interface Dice {
 export interface PollOption {
   /** Option text, 1-100 characters */
   text: string;
+  /** Special entities that appear in the option text. Currently, only custom emoji entities are allowed in poll option texts */
+  text_entities?: MessageEntity[];
   /** Number of users that voted for this option */
   voter_count: number;
 }
 
+/** This object contains information about one answer option in a poll to send. */
+export interface InputPollOption {
+  /** Option text, 1-100 characters */
+  text: string;
+  /** Mode for parsing entities in the text. See formatting options for more details. Currently, only custom emoji entities are allowed */
+  text_parse_mode?: string;
+  /** A list of special entities that appear in the poll option text. It can be specified instead of text_parse_mode */
+  text_entities?: MessageEntity[];
+}
+
 /** This object represents an answer of a user in a non-anonymous poll. */
 export interface PollAnswer {
   /** Unique poll identifier */
@@ -769,6 +797,8 @@ export interface Poll {
   id: string;
   /** Poll question, 1-300 characters */
   question: string;
+  /** Special entities that appear in the question. Currently, only custom emoji entities are allowed in poll questions */
+  question_entities?: MessageEntity[];
   /** List of poll options */
   options: PollOption[];
   /** Total number of users that voted in the poll */
@@ -835,6 +865,14 @@ export interface Story {
   id: number;
 }
 
+/** Describes data sent from a Web App to the bot. */
+export interface WebAppData {
+  /** The data. Be aware that a bad client can send arbitrary data in this field. */
+  data: 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. */
+  button_text: string;
+}
+
 /** This object represents the content of a service message, sent whenever a user in the chat triggers a proximity alert set by another user. */
 export interface ProximityAlertTriggered {
   /** User that triggered the alert */
@@ -869,6 +907,115 @@ export interface ForumTopicEdited {
   icon_custom_emoji_id?: string;
 }
 
+/** This object represents a service message about a user boosting a chat. */
+export interface ChatBoostAdded {
+  /** Number of boosts added by the user */
+  boost_count: number;
+}
+
+/** This object describes the way a background is filled based on the selected colors. Currently, it can be one of
+- BackgroundFillSolid
+- BackgroundFillGradient
+- BackgroundFillFreeformGradient */
+export type BackgroundFill =
+  | BackgroundFillSolid
+  | BackgroundFillGradient
+  | BackgroundFillFreeformGradient;
+
+/** The background is filled using the selected color. */
+export interface BackgroundFillSolid {
+  /** Type of the background fill, always “solid” */
+  type: "solid";
+  /** The color of the background fill in the RGB24 format */
+  color: number;
+}
+
+/** The background is a gradient fill. */
+export interface BackgroundFillGradient {
+  /** Type of the background fill, always “gradient” */
+  type: "gradient";
+  /** Top color of the gradient in the RGB24 format */
+  top_color: number;
+  /** Bottom color of the gradient in the RGB24 format */
+  bottom_color: number;
+  /** Clockwise rotation angle of the background fill in degrees; 0-359 */
+  rotation_angle: number;
+}
+
+/** The background is a freeform gradient that rotates  after every message in the chat. */
+export interface BackgroundFillFreeformGradient {
+  /** Type of the background fill, always “freeform_gradient” */
+  type: "freeform_gradient";
+  /** A list of the 3 or 4 base colors that are used to generate the freeform gradient in the RGB24 format */
+  colors: number[];
+}
+
+/** This object describes the type of a background. Currently, it can be one of
+- BackgroundTypeFill
+- BackgroundTypeWallpaper
+- BackgroundTypePattern
+- BackgroundTypeChatTheme
+- BackgroundTypeFill */
+export type BackgroundType =
+  | BackgroundTypeFill
+  | BackgroundTypeWallpaper
+  | BackgroundTypePattern
+  | BackgroundTypeChatTheme;
+
+/** The background is automatically filled based on the selected colors. */
+export interface BackgroundTypeFill {
+  /** Type of the background, always “fill” */
+  type: "fill";
+  /** The background fill */
+  fill: BackgroundFill;
+  /** Dimming of the background in dark themes, as a percentage; 0-100 */
+  dark_theme_dimming: number;
+}
+
+/** The background is a wallpaper in the JPEG format. */
+export interface BackgroundTypeWallpaper {
+  /** Type of the background, always “wallpaper” */
+  type: "wallpaper";
+  /** Document with the wallpaper */
+  document: Document;
+  /** Dimming of the background in dark themes, as a percentage; 0-100 */
+  dark_theme_dimming: number;
+  /** True, if the wallpaper is downscaled to fit in a 450x450 square and then box-blurred with radius 12 */
+  is_blurred?: true;
+  /** True, if the background moves slightly when the device is tilted */
+  is_moving?: true;
+}
+
+/** The background is a PNG or TGV (gzipped subset of SVG with MIME type “application/x-tgwallpattern”) pattern to be combined with the background fill chosen by the user. */
+export interface BackgroundTypePattern {
+  /** Type of the background, always “pattern” */
+  type: "pattern";
+  /** Document with the pattern */
+  document: Document;
+  /** The background fill that is combined with the pattern */
+  fill: BackgroundFill;
+  /** Intensity of the pattern when it is shown above the filled background; 0-100 */
+  intensity: number;
+  /** True, if the background fill must be applied only to the pattern itself. All other pixels are black in this case. For dark themes only */
+  is_inverted?: true;
+  /** True, if the background moves slightly when the device is tilted */
+  is_moving?: true;
+}
+
+/** The background is taken directly from a built-in chat  theme. */
+export interface BackgroundTypeChatTheme {
+  /** Type of the background, always “chat_theme” */
+  type: "chat_theme";
+  /** Name of the chat theme, which is usually an emoji */
+  theme_name: string;
+}
+
+/** This object represents a chat background. */
+export interface ChatBackground {
+  /** Type of the background*/
+  type: BackgroundType;
+}
+
 /** This object represents a service message about a forum topic closed in the chat. Currently holds no information. */
 export interface ForumTopicClosed {}
 
@@ -942,7 +1089,7 @@ export interface VideoChatParticipantsInvited {
 
 /** This object contains information about a user that was shared with the bot using a KeyboardButtonRequestUser button. */
 export interface SharedUser {
-  /** 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 64-bit integers or double-precision float types are safe for storing these identifiers. 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. */
+  /** Identifier of the shared user. 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. */
   user_id: number;
   /** First name of the user, if the name was requested by the bot */
   first_name?: string;
@@ -1131,7 +1278,9 @@ export interface File {
   file_path?: string;
 }
 
-/** This object describes the type of a reaction. Currently, it can be one of */
+/** This object describes the type of a reaction. Currently, it can be one of
+- ReactionTypeEmoji
+- ReactionTypeCustomEmoji */
 export type ReactionType = ReactionTypeEmoji | ReactionTypeCustomEmoji;
 
 /** The reaction is based on an emoji. */

package/src/updateTypes.d.ts

@@ -89,7 +89,7 @@ export interface Update {
   /** The bot was connected to or disconnected from a business account, or a user edited an existing connection with the bot */
   business_connection?: BusinessConnection;
 
-  /** New non-service message from a connected business account */
+  /** New message from a connected business account */
   business_message?: Message & Update.Private;
 
   /** New version of a message from a connected business account */