@grammyjs/types 3.7.0 → 3.8.1

package/inline.d.ts

@@ -86,6 +86,8 @@ export interface InlineQueryResultPhoto {
     description?: string;
     /** Caption of the photo to be sent, 0-1024 characters after entities parsing */
     caption?: string;
+    /** Pass True, if the caption must be shown above the message media */
+    show_caption_above_media?: boolean;
     /** Mode for parsing entities in the photo caption. See formatting options for more details. */
     parse_mode?: ParseMode;
     /** List of special entities that appear in the caption, which can be specified instead of parse_mode */
@@ -117,6 +119,8 @@ export interface InlineQueryResultGif {
     title?: string;
     /** Caption of the GIF file to be sent, 0-1024 characters after entities parsing */
     caption?: string;
+    /** Pass True, if the caption must be shown above the message media */
+    show_caption_above_media?: boolean;
     /** Mode for parsing entities in the caption. See formatting options for more details. */
     parse_mode?: ParseMode;
     /** List of special entities that appear in the caption, which can be specified instead of parse_mode */
@@ -148,6 +152,8 @@ export interface InlineQueryResultMpeg4Gif {
     title?: string;
     /** Caption of the MPEG-4 file to be sent, 0-1024 characters after entities parsing */
     caption?: string;
+    /** Pass True, if the caption must be shown above the message media */
+    show_caption_above_media?: boolean;
     /** Mode for parsing entities in the caption. See formatting options for more details. */
     parse_mode?: ParseMode;
     /** List of special entities that appear in the caption, which can be specified instead of parse_mode */
@@ -175,6 +181,8 @@ export interface InlineQueryResultVideo {
     title: string;
     /** Caption of the video to be sent, 0-1024 characters after entities parsing */
     caption?: string;
+    /** Pass True, if the caption must be shown above the message media */
+    show_caption_above_media?: boolean;
     /** Mode for parsing entities in the video caption. See formatting options for more details. */
     parse_mode?: ParseMode;
     /** List of special entities that appear in the caption, which can be specified instead of parse_mode */
@@ -385,6 +393,8 @@ export interface InlineQueryResultCachedPhoto {
     description?: string;
     /** Caption of the photo to be sent, 0-1024 characters after entities parsing */
     caption?: string;
+    /** Pass True, if the caption must be shown above the message media */
+    show_caption_above_media?: boolean;
     /** Mode for parsing entities in the photo caption. See formatting options for more details. */
     parse_mode?: ParseMode;
     /** List of special entities that appear in the caption, which can be specified instead of parse_mode */
@@ -406,6 +416,8 @@ export interface InlineQueryResultCachedGif {
     title?: string;
     /** Caption of the GIF file to be sent, 0-1024 characters after entities parsing */
     caption?: string;
+    /** Pass True, if the caption must be shown above the message media */
+    show_caption_above_media?: boolean;
     /** Mode for parsing entities in the caption. See formatting options for more details. */
     parse_mode?: ParseMode;
     /** List of special entities that appear in the caption, which can be specified instead of parse_mode */
@@ -427,6 +439,8 @@ export interface InlineQueryResultCachedMpeg4Gif {
     title?: string;
     /** Caption of the MPEG-4 file to be sent, 0-1024 characters after entities parsing */
     caption?: string;
+    /** Pass True, if the caption must be shown above the message media */
+    show_caption_above_media?: boolean;
     /** Mode for parsing entities in the caption. See formatting options for more details. */
     parse_mode?: ParseMode;
     /** List of special entities that appear in the caption, which can be specified instead of parse_mode */
@@ -486,6 +500,8 @@ export interface InlineQueryResultCachedVideo {
     description?: string;
     /** Caption of the video to be sent, 0-1024 characters after entities parsing */
     caption?: string;
+    /** Pass True, if the caption must be shown above the message media */
+    show_caption_above_media?: boolean;
     /** Mode for parsing entities in the video caption. See formatting options for more details. */
     parse_mode?: ParseMode;
     /** List of special entities that appear in the caption, which can be specified instead of parse_mode */
@@ -607,13 +623,13 @@ export interface InputInvoiceMessageContent {
     description: string;
     /** Bot-defined invoice payload, 1-128 bytes. This will not be displayed to the user, use for your internal processes. */
     payload: string;
-    /** Payment provider token, obtained via BotFather */
-    provider_token: string;
-    /** Three-letter ISO 4217 currency code, see more on currencies */
+    /** Payment provider token, obtained via @BotFather. Pass an empty string for payments in Telegram Stars. */
+    provider_token?: string;
+    /** Three-letter ISO 4217 currency code, see more on currencies. Pass “XTR” for payments in Telegram Stars. */
     currency: string;
-    /** Price breakdown, a list of components (e.g. product price, tax, discount, delivery cost, delivery tax, bonus, etc.) */
+    /** Price breakdown, a JSON-serialized list of components (e.g. product price, tax, discount, delivery cost, delivery tax, bonus, etc.). Must contain exactly one item for payments in Telegram Stars. */
     prices: LabeledPrice[];
-    /** The maximum accepted amount for tips in the smallest units of the currency (integer, not float/double). For example, for a maximum tip of US$ 1.45 pass max_tip_amount = 145. See the exp parameter in currencies.json, it shows the number of digits past the decimal point for each currency (2 for the majority of currencies). Defaults to 0 */
+    /** The maximum accepted amount for tips in the smallest units of the currency (integer, not float/double). For example, for a maximum tip of US$ 1.45 pass max_tip_amount = 145. See the exp parameter in currencies.json, it shows the number of digits past the decimal point for each currency (2 for the majority of currencies). Defaults to 0. Not supported for payments in Telegram Stars. */
     max_tip_amount?: number;
     /** An array of suggested amounts of tip in the smallest units of the currency (integer, not float/double). At most 4 suggested tip amounts can be specified. The suggested tip amounts must be positive, passed in a strictly increased order and must not exceed max_tip_amount. */
     suggested_tip_amounts?: number[];
@@ -627,19 +643,19 @@ export interface InputInvoiceMessageContent {
     photo_width?: number;
     /** Photo height */
     photo_height?: number;
-    /** Pass True if you require the user's full name to complete the order */
+    /** Pass True if you require the user's full name to complete the order. Ignored for payments in Telegram Stars. */
     need_name?: boolean;
-    /** Pass True if you require the user's phone number to complete the order */
+    /** Pass True if you require the user's phone number to complete the order. Ignored for payments in Telegram Stars. */
     need_phone_number?: boolean;
-    /** Pass True if you require the user's email address to complete the order */
+    /** Pass True if you require the user's email address to complete the order. Ignored for payments in Telegram Stars. */
     need_email?: boolean;
-    /** Pass True if you require the user's shipping address to complete the order */
+    /** Pass True if you require the user's shipping address to complete the order. Ignored for payments in Telegram Stars. */
     need_shipping_address?: boolean;
-    /** Pass True if the user's phone number should be sent to provider */
+    /** Pass True if the user's phone number should be sent to provider. Ignored for payments in Telegram Stars. */
     send_phone_number_to_provider?: boolean;
-    /** Pass True if the user's email address should be sent to provider */
+    /** Pass True if the user's email address should be sent to provider. Ignored for payments in Telegram Stars. */
     send_email_to_provider?: boolean;
-    /** Pass True if the final price depends on the shipping method */
+    /** Pass True if the final price depends on the shipping method. Ignored for payments in Telegram Stars. */
     is_flexible?: boolean;
 }
 /** Represents a result of an inline query that was chosen by the user and sent to their chat partner.

package/langs.d.ts

@@ -0,0 +1,193 @@
+/** A two-letter ISO 639-1 language code.
+ * @see https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes
+ * @see https://www.loc.gov/standards/iso639-2/php/code_list.php
+ */
+export type LanguageCode = typeof LanguageCodes[keyof typeof LanguageCodes];
+/**
+ * @see {@link LanguageCode}
+ */
+export declare const LanguageCodes: {
+    readonly Abkhazian: "ab";
+    readonly Afar: "aa";
+    readonly Afrikaans: "af";
+    readonly Akan: "ak";
+    readonly Albanian: "sq";
+    readonly Amharic: "am";
+    readonly Arabic: "ar";
+    readonly Aragonese: "an";
+    readonly Armenian: "hy";
+    readonly Assamese: "as";
+    readonly Avaric: "av";
+    readonly Avestan: "ae";
+    readonly Aymara: "ay";
+    readonly Azerbaijani: "az";
+    readonly Bambara: "bm";
+    readonly Bashkir: "ba";
+    readonly Basque: "eu";
+    readonly Belarusian: "be";
+    readonly Bengali: "bn";
+    readonly Bislama: "bi";
+    readonly Bosnian: "bs";
+    readonly Breton: "br";
+    readonly Bulgarian: "bg";
+    readonly Burmese: "my";
+    readonly Catalan: "ca";
+    readonly Chamorro: "ch";
+    readonly Chechen: "ce";
+    readonly Chichewa: "ny";
+    readonly Chinese: "zh";
+    readonly ChurchSlavonic: "cu";
+    readonly Chuvash: "cv";
+    readonly Cornish: "kw";
+    readonly Corsican: "co";
+    readonly Cree: "cr";
+    readonly Croatian: "hr";
+    readonly Czech: "cs";
+    readonly Danish: "da";
+    readonly Divehi: "dv";
+    readonly Dutch: "nl";
+    readonly Dzongkha: "dz";
+    readonly English: "en";
+    readonly Esperanto: "eo";
+    readonly Estonian: "et";
+    readonly Ewe: "ee";
+    readonly Faroese: "fo";
+    readonly Fijian: "fj";
+    readonly Finnish: "fi";
+    readonly French: "fr";
+    readonly WesternFrisian: "fy";
+    readonly Fulah: "ff";
+    readonly Gaelic: "gd";
+    readonly Galician: "gl";
+    readonly Ganda: "lg";
+    readonly Georgian: "ka";
+    readonly German: "de";
+    readonly Greek: "el";
+    readonly Kalaallisut: "kl";
+    readonly Guarani: "gn";
+    readonly Gujarati: "gu";
+    readonly Haitian: "ht";
+    readonly Hausa: "ha";
+    readonly Hebrew: "he";
+    readonly Herero: "hz";
+    readonly Hindi: "hi";
+    readonly HiriMotu: "ho";
+    readonly Hungarian: "hu";
+    readonly Icelandic: "is";
+    readonly Ido: "io";
+    readonly Igbo: "ig";
+    readonly Indonesian: "id";
+    readonly Interlingua: "ia";
+    readonly Interlingue: "ie";
+    readonly Inuktitut: "iu";
+    readonly Inupiaq: "ik";
+    readonly Irish: "ga";
+    readonly Italian: "it";
+    readonly Japanese: "ja";
+    readonly Javanese: "jv";
+    readonly Kannada: "kn";
+    readonly Kanuri: "kr";
+    readonly Kashmiri: "ks";
+    readonly Kazakh: "kk";
+    readonly CentralKhmer: "km";
+    readonly Kikuyu: "ki";
+    readonly Kinyarwanda: "rw";
+    readonly Kirghiz: "ky";
+    readonly Komi: "kv";
+    readonly Kongo: "kg";
+    readonly Korean: "ko";
+    readonly Kuanyama: "kj";
+    readonly Kurdish: "ku";
+    readonly Lao: "lo";
+    readonly Latin: "la";
+    readonly Latvian: "lv";
+    readonly Limburgan: "li";
+    readonly Lingala: "ln";
+    readonly Lithuanian: "lt";
+    readonly LubaKatanga: "lu";
+    readonly Luxembourgish: "lb";
+    readonly Macedonian: "mk";
+    readonly Malagasy: "mg";
+    readonly Malay: "ms";
+    readonly Malayalam: "ml";
+    readonly Maltese: "mt";
+    readonly Manx: "gv";
+    readonly Maori: "mi";
+    readonly Marathi: "mr";
+    readonly Marshallese: "mh";
+    readonly Mongolian: "mn";
+    readonly Nauru: "na";
+    readonly Navajo: "nv";
+    readonly NorthNdebele: "nd";
+    readonly SouthNdebele: "nr";
+    readonly Ndonga: "ng";
+    readonly Nepali: "ne";
+    readonly Norwegian: "no";
+    readonly NorwegianBokmål: "nb";
+    readonly NorwegianNynorsk: "nn";
+    readonly SichuanYi: "ii";
+    readonly Occitan: "oc";
+    readonly Ojibwa: "oj";
+    readonly Oriya: "or";
+    readonly Oromo: "om";
+    readonly Ossetian: "os";
+    readonly Pali: "pi";
+    readonly Pashto: "ps";
+    readonly Persian: "fa";
+    readonly Polish: "pl";
+    readonly Portuguese: "pt";
+    readonly Punjabi: "pa";
+    readonly Quechua: "qu";
+    readonly Romanian: "ro";
+    readonly Romansh: "rm";
+    readonly Rundi: "rn";
+    readonly Russian: "ru";
+    readonly NorthernSami: "se";
+    readonly Samoan: "sm";
+    readonly Sango: "sg";
+    readonly Sanskrit: "sa";
+    readonly Sardinian: "sc";
+    readonly Serbian: "sr";
+    readonly Shona: "sn";
+    readonly Sindhi: "sd";
+    readonly Sinhala: "si";
+    readonly Slovak: "sk";
+    readonly Slovenian: "sl";
+    readonly Somali: "so";
+    readonly SouthernSotho: "st";
+    readonly Spanish: "es";
+    readonly Sundanese: "su";
+    readonly Swahili: "sw";
+    readonly Swati: "ss";
+    readonly Swedish: "sv";
+    readonly Tagalog: "tl";
+    readonly Tahitian: "ty";
+    readonly Tajik: "tg";
+    readonly Tamil: "ta";
+    readonly Tatar: "tt";
+    readonly Telugu: "te";
+    readonly Thai: "th";
+    readonly Tibetan: "bo";
+    readonly Tigrinya: "ti";
+    readonly Tonga: "to";
+    readonly Tsonga: "ts";
+    readonly Tswana: "tn";
+    readonly Turkish: "tr";
+    readonly Turkmen: "tk";
+    readonly Twi: "tw";
+    readonly Uighur: "ug";
+    readonly Ukrainian: "uk";
+    readonly Urdu: "ur";
+    readonly Uzbek: "uz";
+    readonly Venda: "ve";
+    readonly Vietnamese: "vi";
+    readonly Volapük: "vo";
+    readonly Walloon: "wa";
+    readonly Welsh: "cy";
+    readonly Wolof: "wo";
+    readonly Xhosa: "xh";
+    readonly Yiddish: "yi";
+    readonly Yoruba: "yo";
+    readonly Zhuang: "za";
+    readonly Zulu: "zu";
+};

package/markup.d.ts

@@ -1,6 +1,6 @@
 import type { ChatAdministratorRights, User } from "./manage.js";
 import type { MaybeInaccessibleMessage } from "./message.js";
-/** 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[][];
@@ -47,7 +47,7 @@ export declare namespace InlineKeyboardButton {
         callback_game: CallbackGame;
     }
     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;
@@ -151,7 +151,7 @@ export declare namespace KeyboardButton {
         web_app: WebAppInfo;
     }
 }
-/** 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 | KeyboardButton.RequestChatButton | KeyboardButton.RequestContactButton | KeyboardButton.RequestLocationButton | KeyboardButton.RequestPollButton | KeyboardButton.WebAppButton | string;
 /** This object represents type of a poll, which is allowed to be created and sent when the corresponding button is pressed. */
 export interface KeyboardButtonPollType {

package/message.d.ts

@@ -45,12 +45,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;
     }
@@ -263,7 +267,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 identifier without using a username. Please note:
@@ -295,9 +299,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:
 
@@ -305,7 +315,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.
 
@@ -326,6 +336,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:
 
@@ -357,13 +368,13 @@ 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;
@@ -371,7 +382,7 @@ export declare namespace MessageEntity {
         length: number;
     }
     interface CommonMessageEntity extends AbstractMessageEntity {
-        type: "mention" | "hashtag" | "cashtag" | "bot_command" | "url" | "email" | "phone_number" | "bold" | "italic" | "underline" | "strikethrough" | "spoiler" | "blockquote" | "code";
+        type: "mention" | "hashtag" | "cashtag" | "bot_command" | "url" | "email" | "phone_number" | "bold" | "italic" | "underline" | "strikethrough" | "spoiler" | "blockquote" | "expandable_blockquote" | "code";
     }
     interface PreMessageEntity extends AbstractMessageEntity {
         type: "pre";

package/methods.d.ts

@@ -7,6 +7,7 @@ import type { PassportElementError } from "./passport.js";
 import type { LabeledPrice, ShippingOption } from "./payment.js";
 import type { BotCommandScope, BotDescription, BotName, BotShortDescription, MenuButton } from "./settings.js";
 import type { Update } from "./update.js";
+import type { LanguageCode } from "./langs.js";
 /** Extracts the parameters of a given method name */
 type Params<F, M extends keyof ApiMethods<F>> = Parameters<ApiMethods<F>[M]>;
 /** Utility type providing the argument type for the given method name or `{}` if the method does not take any parameters */
@@ -93,6 +94,8 @@ export type ApiMethods<F> = {
         disable_notification?: boolean;
         /** Protects the contents of the sent message from forwarding and saving */
         protect_content?: boolean;
+        /** Unique identifier of the message effect to be added to the message */
+        message_effect_id?: string;
         /** Description of the message to reply to */
         reply_parameters?: ReplyParameters;
         /** Additional interface options. An object for an inline keyboard, custom reply keyboard, instructions to remove a reply keyboard or to force a reply from the user. */
@@ -146,6 +149,8 @@ export type ApiMethods<F> = {
         parse_mode?: string;
         /** A list of special entities that appear in the new caption, which can be specified instead of parse_mode */
         caption_entities?: MessageEntity[];
+        /** Pass True, if the caption must be shown above the message media. Ignored if a new caption isn't specified. */
+        show_caption_above_media?: boolean;
         /** Sends the message silently. Users will receive a notification with no sound. */
         disable_notification?: boolean;
         /** Protects the contents of the sent message from forwarding and saving */
@@ -190,12 +195,16 @@ export type ApiMethods<F> = {
         parse_mode?: ParseMode;
         /** A list of special entities that appear in the caption, which can be specified instead of parse_mode */
         caption_entities?: MessageEntity[];
+        /** Pass True, if the caption must be shown above the message media */
+        show_caption_above_media?: boolean;
         /** Pass True if the photo needs to be covered with a spoiler animation */
         has_spoiler?: boolean;
         /** Sends the message silently. Users will receive a notification with no sound. */
         disable_notification?: boolean;
         /** Protects the contents of the sent message from forwarding and saving */
         protect_content?: boolean;
+        /** Unique identifier of the message effect to be added to the message */
+        message_effect_id?: string;
         /** Description of the message to reply to */
         reply_parameters?: ReplyParameters;
         /** Additional interface options. An object for an inline keyboard, custom reply keyboard, instructions to remove a reply keyboard or to force a reply from the user. */
@@ -233,6 +242,8 @@ export type ApiMethods<F> = {
         disable_notification?: boolean;
         /** Protects the contents of the sent message from forwarding and saving */
         protect_content?: boolean;
+        /** Unique identifier of the message effect to be added to the message */
+        message_effect_id?: string;
         /** Description of the message to reply to */
         reply_parameters?: ReplyParameters;
         /** Additional interface options. An object for an inline keyboard, custom reply keyboard, instructions to remove a reply keyboard or to force a reply from the user. */
@@ -264,6 +275,8 @@ export type ApiMethods<F> = {
         disable_notification?: boolean;
         /** Protects the contents of the sent message from forwarding and saving */
         protect_content?: boolean;
+        /** Unique identifier of the message effect to be added to the message */
+        message_effect_id?: string;
         /** Description of the message to reply to */
         reply_parameters?: ReplyParameters;
         /** Additional interface options. An object for an inline keyboard, custom reply keyboard, instructions to remove a reply keyboard or to force a reply from the user. */
@@ -295,6 +308,8 @@ export type ApiMethods<F> = {
         parse_mode?: ParseMode;
         /** A list of special entities that appear in the caption, which can be specified instead of parse_mode */
         caption_entities?: MessageEntity[];
+        /** Pass True, if the caption must be shown above the message media */
+        show_caption_above_media?: boolean;
         /** Pass True if the video needs to be covered with a spoiler animation */
         has_spoiler?: boolean;
         /** Pass True if the uploaded video is suitable for streaming */
@@ -303,6 +318,8 @@ export type ApiMethods<F> = {
         disable_notification?: boolean;
         /** Protects the contents of the sent message from forwarding and saving */
         protect_content?: boolean;
+        /** Unique identifier of the message effect to be added to the message */
+        message_effect_id?: string;
         /** Description of the message to reply to */
         reply_parameters?: ReplyParameters;
         /** Additional interface options. An object for an inline keyboard, custom reply keyboard, instructions to remove a reply keyboard or to force a reply from the user. */
@@ -334,12 +351,16 @@ export type ApiMethods<F> = {
         parse_mode?: ParseMode;
         /** A list of special entities that appear in the caption, which can be specified instead of parse_mode */
         caption_entities?: MessageEntity[];
+        /** Pass True, if the caption must be shown above the message media */
+        show_caption_above_media?: boolean;
         /** Pass True if the animation needs to be covered with a spoiler animation */
         has_spoiler?: boolean;
         /** Sends the message silently. Users will receive a notification with no sound. */
         disable_notification?: boolean;
         /** Protects the contents of the sent message from forwarding and saving */
         protect_content?: boolean;
+        /** Unique identifier of the message effect to be added to the message */
+        message_effect_id?: string;
         /** Description of the message to reply to */
         reply_parameters?: ReplyParameters;
         /** Additional interface options. An object for an inline keyboard, custom reply keyboard, instructions to remove a reply keyboard or to force a reply from the user. */
@@ -369,6 +390,8 @@ export type ApiMethods<F> = {
         disable_notification?: boolean;
         /** Protects the contents of the sent message from forwarding and saving */
         protect_content?: boolean;
+        /** Unique identifier of the message effect to be added to the message */
+        message_effect_id?: string;
         /** Description of the message to reply to */
         reply_parameters?: ReplyParameters;
         /** Additional interface options. An object for an inline keyboard, custom reply keyboard, instructions to remove a reply keyboard or to force a reply from the user. */
@@ -397,6 +420,8 @@ export type ApiMethods<F> = {
         disable_notification?: boolean;
         /** Protects the contents of the sent message from forwarding and saving */
         protect_content?: boolean;
+        /** Unique identifier of the message effect to be added to the message */
+        message_effect_id?: string;
         /** Description of the message to reply to */
         reply_parameters?: ReplyParameters;
         /** Additional interface options. An object for an inline keyboard, custom reply keyboard, instructions to remove a reply keyboard or to force a reply from the user. */
@@ -418,6 +443,8 @@ export type ApiMethods<F> = {
         disable_notification?: boolean;
         /** Protects the contents of the sent messages from forwarding and saving */
         protect_content?: boolean;
+        /** Unique identifier of the message effect to be added to the message */
+        message_effect_id?: string;
         /** Description of the message to reply to */
         reply_parameters?: ReplyParameters;
         /** @deprecated Use `reply_parameters` instead. */
@@ -447,6 +474,8 @@ export type ApiMethods<F> = {
         disable_notification?: boolean;
         /** Protects the contents of the sent message from forwarding and saving */
         protect_content?: boolean;
+        /** Unique identifier of the message effect to be added to the message */
+        message_effect_id?: string;
         /** Description of the message to reply to */
         reply_parameters?: ReplyParameters;
         /** Additional interface options. An object for an inline keyboard, custom reply keyboard, instructions to remove a reply keyboard or to force a reply from the user. */
@@ -516,6 +545,8 @@ export type ApiMethods<F> = {
         disable_notification?: boolean;
         /** Protects the contents of the sent message from forwarding and saving */
         protect_content?: boolean;
+        /** Unique identifier of the message effect to be added to the message */
+        message_effect_id?: string;
         /** Description of the message to reply to */
         reply_parameters?: ReplyParameters;
         /** Additional interface options. An object for an inline keyboard, custom reply keyboard, instructions to remove a reply keyboard or to force a reply from the user. */
@@ -543,6 +574,8 @@ export type ApiMethods<F> = {
         disable_notification?: boolean;
         /** Protects the contents of the sent message from forwarding and saving */
         protect_content?: boolean;
+        /** Unique identifier of the message effect to be added to the message */
+        message_effect_id?: string;
         /** Description of the message to reply to */
         reply_parameters?: ReplyParameters;
         /** Additional interface options. An object for an inline keyboard, custom reply keyboard, instructions to remove a reply keyboard or to force a reply from the user. */
@@ -590,6 +623,8 @@ export type ApiMethods<F> = {
         disable_notification?: boolean;
         /** Protects the contents of the sent message from forwarding and saving */
         protect_content?: boolean;
+        /** Unique identifier of the message effect to be added to the message */
+        message_effect_id?: string;
         /** Description of the message to reply to */
         reply_parameters?: ReplyParameters;
         /** Additional interface options. An object for an inline keyboard, custom reply keyboard, instructions to remove a reply keyboard or to force a reply from the user. */
@@ -611,6 +646,8 @@ export type ApiMethods<F> = {
         disable_notification?: boolean;
         /** Protects the contents of the sent message from forwarding */
         protect_content?: boolean;
+        /** Unique identifier of the message effect to be added to the message */
+        message_effect_id?: string;
         /** Description of the message to reply to */
         reply_parameters?: ReplyParameters;
         /** Additional interface options. An object for an inline keyboard, custom reply keyboard, instructions to remove a reply keyboard or to force a reply from the user. */
@@ -1023,64 +1060,64 @@ export type ApiMethods<F> = {
         /** Unique identifier of the business connection */
         business_connection_id: string;
     }): BusinessConnection;
-    /** Use this method to change the list of the bot's commands. See https://core.telegram.org/bots#commands for more details about bot commands. Returns True on success. */
+    /** Use this method to change the list of the bot's commands. See https://core.telegram.org/bots/features#commands for more details about bot commands. Returns True on success. */
     setMyCommands(args: {
         /** A list of bot commands to be set as the list of the bot's commands. At most 100 commands can be specified. */
         commands: readonly BotCommand[];
         /** An object, describing scope of users for which the commands are relevant. Defaults to BotCommandScopeDefault. */
         scope?: BotCommandScope;
         /** A two-letter ISO 639-1 language code. If empty, commands will be applied to all users from the given scope, for whose language there are no dedicated commands */
-        language_code?: string;
+        language_code?: LanguageCode;
     }): true;
     /** Use this method to delete the list of the bot's commands for the given scope and user language. After deletion, higher level commands will be shown to affected users. Returns True on success. */
     deleteMyCommands(args: {
         /** An object, describing scope of users for which the commands are relevant. Defaults to BotCommandScopeDefault. */
         scope?: BotCommandScope;
         /** A two-letter ISO 639-1 language code. If empty, commands will be applied to all users from the given scope, for whose language there are no dedicated commands */
-        language_code?: string;
+        language_code?: LanguageCode;
     }): true;
     /** Use this method to get the current list of the bot's commands for the given scope and user language. Returns an Array of BotCommand objects. If commands aren't set, an empty list is returned. */
     getMyCommands(args: {
         /** An object, describing scope of users. Defaults to BotCommandScopeDefault. */
         scope?: BotCommandScope;
         /** A two-letter ISO 639-1 language code or an empty string */
-        language_code?: string;
+        language_code?: LanguageCode;
     }): BotCommand[];
     /** Use this method to change the bot's name. Returns True on success. */
     setMyName(args: {
         /** New bot name; 0-64 characters. Pass an empty string to remove the dedicated name for the given language. */
         name?: string;
         /** A two-letter ISO 639-1 language code. If empty, the name will be shown to all users for whose language there is no dedicated name. */
-        language_code?: string;
+        language_code?: LanguageCode;
     }): true;
     /** Use this method to get the current bot name for the given user language. Returns BotName on success. */
     getMyName(args: {
         /** A two-letter ISO 639-1 language code or an empty string */
-        language_code?: string;
+        language_code?: LanguageCode;
     }): BotName;
     /** Use this method to change the bot's description, which is shown in the chat with the bot if the chat is empty. Returns True on success. */
     setMyDescription(args: {
         /** New bot description; 0-512 characters. Pass an empty string to remove the dedicated description for the given language. */
         description?: string;
         /** A two-letter ISO 639-1 language code. If empty, the description will be applied to all users for whose language there is no dedicated description. */
-        language_code?: string;
+        language_code?: LanguageCode;
     }): true;
     /** Use this method to get the current bot description for the given user language. Returns BotDescription on success. */
     getMyDescription(args: {
         /** A two-letter ISO 639-1 language code or an empty string */
-        language_code?: string;
+        language_code?: LanguageCode;
     }): BotDescription;
     /** Use this method to change the bot's short description, which is shown on the bot's profile page and is sent together with the link when users share the bot. Returns True on success. */
     setMyShortDescription(args: {
         /** New short description for the bot; 0-120 characters. Pass an empty string to remove the dedicated short description for the given language. */
         short_description?: string;
         /** A two-letter ISO 639-1 language code. If empty, the short description will be applied to all users for whose language there is no dedicated short description. */
-        language_code?: string;
+        language_code?: LanguageCode;
     }): true;
     /** Use this method to get the current bot short description for the given user language. Returns BotShortDescription on success. */
     getMyShortDescription(args: {
         /** A two-letter ISO 639-1 language code or an empty string */
-        language_code?: string;
+        language_code?: LanguageCode;
     }): BotShortDescription;
     /** Use this method to change the bot's menu button in a private chat, or the default menu button. Returns True on success. */
     setChatMenuButton(args: {
@@ -1139,6 +1176,8 @@ export type ApiMethods<F> = {
         parse_mode?: ParseMode;
         /** A list of special entities that appear in the caption, which can be specified instead of parse_mode */
         caption_entities?: MessageEntity[];
+        /** Pass True, if the caption must be shown above the message media. Supported only for animation, photo and video messages. */
+        show_caption_above_media?: boolean;
         /** An object for an inline keyboard. */
         reply_markup?: InlineKeyboardMarkup;
     }): (Update.Edited & Message.CaptionableMessage) | true;
@@ -1214,6 +1253,8 @@ export type ApiMethods<F> = {
         disable_notification?: boolean;
         /** Protects the contents of the sent message from forwarding and saving */
         protect_content?: boolean;
+        /** Unique identifier of the message effect to be added to the message */
+        message_effect_id?: string;
         /** Description of the message to reply to */
         reply_parameters?: ReplyParameters;
         /** Additional interface options. An object for an inline keyboard, custom reply keyboard, instructions to remove a reply keyboard or to force a reply from the user. */
@@ -1375,13 +1416,13 @@ export type ApiMethods<F> = {
         description: string;
         /** Bot-defined invoice payload, 1-128 bytes. This will not be displayed to the user, use for your internal processes. */
         payload: string;
-        /** Payment provider token, obtained via @BotFather */
-        provider_token: string;
-        /** Three-letter ISO 4217 currency code, see more on currencies */
+        /** Payment provider token, obtained via BotFather. Pass an empty string for payments in Telegram Stars. */
+        provider_token?: string;
+        /** Three-letter ISO 4217 currency code, see more on currencies. Pass “XTR” for payments in Telegram Stars. */
         currency: string;
-        /** Price breakdown, a list of components (e.g. product price, tax, discount, delivery cost, delivery tax, bonus, etc.) */
+        /** Price breakdown, a JSON-serialized list of components (e.g. product price, tax, discount, delivery cost, delivery tax, bonus, etc.). Must contain exactly one item for payments in Telegram Stars. */
         prices: readonly LabeledPrice[];
-        /** The maximum accepted amount for tips in the smallest units of the currency (integer, not float/double). For example, for a maximum tip of US$ 1.45 pass max_tip_amount = 145. See the exp parameter in currencies.json, it shows the number of digits past the decimal point for each currency (2 for the majority of currencies). Defaults to 0 */
+        /** The maximum accepted amount for tips in the smallest units of the currency (integer, not float/double). For example, for a maximum tip of US$ 1.45 pass max_tip_amount = 145. See the exp parameter in currencies.json, it shows the number of digits past the decimal point for each currency (2 for the majority of currencies). Defaults to 0. Not supported for payments in Telegram Stars. */
         max_tip_amount?: number;
         /** An array of suggested amounts of tips in the smallest units of the currency (integer, not float/double). At most 4 suggested tip amounts can be specified. The suggested tip amounts must be positive, passed in a strictly increased order and must not exceed max_tip_amount. */
         suggested_tip_amounts?: number[];
@@ -1397,24 +1438,26 @@ export type ApiMethods<F> = {
         photo_width?: number;
         /** Photo height */
         photo_height?: number;
-        /** Pass True if you require the user's full name to complete the order */
+        /** Pass True if you require the user's full name to complete the order. Ignored for payments in Telegram Stars. */
         need_name?: boolean;
-        /** Pass True if you require the user's phone number to complete the order */
+        /** Pass True if you require the user's phone number to complete the order. Ignored for payments in Telegram Stars. */
         need_phone_number?: boolean;
-        /** Pass True if you require the user's email address to complete the order */
+        /** Pass True if you require the user's email address to complete the order. Ignored for payments in Telegram Stars. */
         need_email?: boolean;
-        /** Pass True if you require the user's shipping address to complete the order */
+        /** Pass True if you require the user's shipping address to complete the order. Ignored for payments in Telegram Stars. */
         need_shipping_address?: boolean;
-        /** Pass True if the user's phone number should be sent to provider */
+        /** Pass True if the user's phone number should be sent to provider. Ignored for payments in Telegram Stars. */
         send_phone_number_to_provider?: boolean;
-        /** Pass True if the user's email address should be sent to provider */
+        /** Pass True if the user's email address should be sent to provider. Ignored for payments in Telegram Stars. */
         send_email_to_provider?: boolean;
-        /** Pass True if the final price depends on the shipping method */
+        /** Pass True if the final price depends on the shipping method. Ignored for payments in Telegram Stars. */
         is_flexible?: boolean;
         /** Sends the message silently. Users will receive a notification with no sound. */
         disable_notification?: boolean;
         /** Protects the contents of the sent message from forwarding and saving */
         protect_content?: boolean;
+        /** Unique identifier of the message effect to be added to the message */
+        message_effect_id?: string;
         /** Description of the message to reply to */
         reply_parameters?: ReplyParameters;
         /** An object for an inline keyboard. If empty, one 'Pay total price' button will be shown. If not empty, the first button must be a Pay button. */
@@ -1430,8 +1473,8 @@ export type ApiMethods<F> = {
         description: string;
         /** Bot-defined invoice payload, 1-128 bytes. This will not be displayed to the user, use for your internal processes. */
         payload: string;
-        /** Payment provider token, obtained via BotFather */
-        provider_token: string;
+        /** Payment provider token, obtained via @BotFather. Pass an empty string for payments in Telegram Stars. */
+        provider_token?: string;
         /** Three-letter ISO 4217 currency code, see more on currencies */
         currency: string;
         /** Price breakdown, a list of components (e.g. product price, tax, discount, delivery cost, delivery tax, bonus, etc.) */
@@ -1485,6 +1528,13 @@ export type ApiMethods<F> = {
         /** Required if ok is False. Error message in human readable form that explains the reason for failure to proceed with the checkout (e.g. "Sorry, somebody just bought the last of our amazing black T-shirts while you were busy filling out your payment details. Please choose a different color or garment!"). Telegram will display this message to the user. */
         error_message?: string;
     }): true;
+    /** Refunds a successful payment in Telegram Stars. Returns True on success. */
+    refundStarPayment(args: {
+        /** Identifier of the user whose payment will be refunded */
+        user_id: number;
+        /** Telegram payment identifier */
+        telegram_payment_charge_id: string;
+    }): true;
     /** Informs a user that some of the Telegram Passport elements they provided contains errors. The user will not be able to re-submit their Passport to you until the errors are fixed (the contents of the field for which you returned the error must change). Returns True on success.
   
     Use this if the data submitted by the user doesn't satisfy the standards your service requires for any reason. For example, if a birthday date seems invalid, a submitted document is blurry, a scan shows evidence of tampering, etc. Supply some details in the error message to make sure the user knows how to correct the issues. */
@@ -1508,6 +1558,8 @@ export type ApiMethods<F> = {
         disable_notification?: boolean;
         /** Protects the contents of the sent message from forwarding and saving */
         protect_content?: boolean;
+        /** Unique identifier of the message effect to be added to the message */
+        message_effect_id?: string;
         /** Description of the message to reply to */
         reply_parameters?: ReplyParameters;
         /** An object for an inline keyboard. If empty, one 'Play game_title' button will be shown. If not empty, the first button must launch the game. */
@@ -1574,6 +1626,8 @@ export interface InputMediaPhoto<F> {
     media: F | string;
     /** Caption of the photo to be sent, 0-1024 characters after entities parsing */
     caption?: string;
+    /** Pass True, if the caption must be shown above the message media */
+    show_caption_above_media?: boolean;
     /** Mode for parsing entities in the photo caption. See formatting options for more details. */
     parse_mode?: ParseMode;
     /** List of special entities that appear in the caption, which can be specified instead of parse_mode */
@@ -1591,6 +1645,8 @@ export interface InputMediaVideo<F> {
     thumbnail?: F;
     /** Caption of the video to be sent, 0-1024 characters after entities parsing */
     caption?: string;
+    /** Pass True, if the caption must be shown above the message media */
+    show_caption_above_media?: boolean;
     /** Mode for parsing entities in the video caption. See formatting options for more details. */
     parse_mode?: ParseMode;
     /** List of special entities that appear in the caption, which can be specified instead of parse_mode */
@@ -1616,6 +1672,8 @@ export interface InputMediaAnimation<F> {
     thumbnail?: F;
     /** Caption of the animation to be sent, 0-1024 characters after entities parsing */
     caption?: string;
+    /** Pass True, if the caption must be shown above the message media */
+    show_caption_above_media?: boolean;
     /** Mode for parsing entities in the animation caption. See formatting options for more details. */
     parse_mode?: ParseMode;
     /** List of special entities that appear in the caption, which can be specified instead of parse_mode */

package/mod.d.ts

@@ -8,3 +8,4 @@ export * from "./passport.js";
 export * from "./payment.js";
 export * from "./settings.js";
 export * from "./update.js";
+export * from "./langs.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grammyjs/types",
-  "version": "3.7.0",
+  "version": "3.8.1",
   "description": "Telegram Bot API type declarations for grammY",
   "main": "mod.js",
   "repository": {

package/payment.d.ts

@@ -14,7 +14,7 @@ export interface Invoice {
     description: string;
     /** Unique bot deep-linking parameter that can be used to generate this invoice */
     start_parameter: string;
-    /** Three-letter ISO 4217 currency code */
+    /** Three-letter ISO 4217 currency code, or “XTR” for payments in Telegram Stars */
     currency: string;
     /** Total price in the smallest units of the currency (integer, not float/double). For example, for a price of US$ 1.45 pass amount = 145. See the exp parameter in currencies.json, it shows the number of digits past the decimal point for each currency (2 for the majority of currencies). */
     total_amount: number;
@@ -56,7 +56,7 @@ export interface ShippingOption {
 }
 /** This object contains basic information about a successful payment. */
 export interface SuccessfulPayment {
-    /** Three-letter ISO 4217 currency code */
+    /** Three-letter ISO 4217 currency code, or “XTR” for payments in Telegram Stars */
     currency: string;
     /** Total price in the smallest units of the currency (integer, not float/double). For example, for a price of US$ 1.45 pass amount = 145. See the exp parameter in currencies.json, it shows the number of digits past the decimal point for each currency (2 for the majority of currencies). */
     total_amount: number;
@@ -88,7 +88,7 @@ export interface PreCheckoutQuery {
     id: string;
     /** User who sent the query */
     from: User;
-    /** Three-letter ISO 4217 currency code */
+    /** Three-letter ISO 4217 currency code, or “XTR” for payments in Telegram Stars */
     currency: string;
     /** Total price in the smallest units of the currency (integer, not float/double). For example, for a price of US$ 1.45 pass amount = 145. See the exp parameter in currencies.json, it shows the number of digits past the decimal point for each currency (2 for the majority of currencies). */
     total_amount: number;