Rework Bot API 4.7

1 files changed, 74 insertions, 25 deletions

diff --git a/include/tgbot/Api.h b/include/tgbot/Api.h
index 18165d1..e5a17f5 100644
--- a/include/tgbot/Api.h
+++ b/include/tgbot/Api.h
@@ -56,20 +56,35 @@ public:
 
     /**
      * @brief Use this method to send text messages.
-     * @param chatId Unique identifier for the target chat.
-     * @param text Text of the message to be sent.
-     * @param disableWebPagePreview Optional. Disables link previews for links in this message.
-     * @param replyToMessageId Optional. If the message is a reply, ID of the original message.
-     * @param replyMarkup Optional. Additional interface options. An object for a custom reply keyboard, instructions to hide keyboard or to force a reply from the user.
-     * @param parseMode Optional. Set it to "Markdown" or "HTML" if you want Telegram apps to show bold, italic, fixed-width text or inline URLs in your bot's message.
-     * @param disableNotification Optional. Sends the message silenty.
-     * @return On success, the sent message is returned.
+     * 
+     * @param chatId Unique identifier for the target chat or username of the target channel (in the format @channelusername)
+     * @param text Text of the message to be sent
+     * @param parseMode Optional. Send Markdown or HTML, if you want Telegram apps to show bold, italic, fixed-width text or inline URLs in your bot's message.
+     * @param disableWebPagePreview Optional. Disables link previews for links in this message
+     * @param disableNotification Optional. Sends the message silently. Users will receive a notification with no sound.
+     * @param replyToMessageId Optional. If the message is a reply, ID of the original message
+     * @param replyMarkup Optional. Additional interface options. A JSON-serialized object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the user.
+     * 
+     * @return On success, the sent @ref Message is returned.
      */
-    Message::Ptr sendMessage(std::int64_t chatId, const std::string& text, bool disableWebPagePreview = false, std::int32_t replyToMessageId = 0,
-                             GenericReply::Ptr replyMarkup = std::make_shared<GenericReply>(), const std::string& parseMode = "", bool disableNotification = false) const;
+    Message::Ptr sendMessage(boost::variant<std::int64_t, const std::string&> chatId, const std::string& text, const std::string& parseMode = "",
+                             bool disableWebPagePreview = false, bool disableNotification = false, std::int32_t replyToMessageId = 0,
+                             GenericReply::Ptr replyMarkup = std::make_shared<GenericReply>()) const;
 
-    Message::Ptr sendMessage(const std::string& chatId, const std::string& text, bool disableWebPagePreview = false, std::int32_t replyToMessageId = 0,
-                            GenericReply::Ptr replyMarkup = std::make_shared<GenericReply>(), const std::string& parseMode = "", bool disableNotification = false) const;
+    /**
+     * @brief Deprecated. Use @ref Api::sendMessage
+     * @deprecated since Bot API 4.5. This remains unchanged for backward compatibility.
+     */
+    Message::Ptr sendMessage(const std::string& chatId, const std::string& text, bool disableWebPagePreview = false,
+                             std::int32_t replyToMessageId = 0, GenericReply::Ptr replyMarkup = std::make_shared<GenericReply>(), const std::string& parseMode = "",
+                             bool disableNotification = false) const;
+    /**
+     * @brief Deprecated. Use @ref Api::sendMessage
+     * @deprecated since Bot API 4.5. This remains unchanged for backward compatibility.
+     */
+    Message::Ptr sendMessage(std::int64_t chatId, const std::string& text, bool disableWebPagePreview = false,
+                             std::int32_t replyToMessageId = 0, GenericReply::Ptr replyMarkup = std::make_shared<GenericReply>(), const std::string& parseMode = "",
+                             bool disableNotification = false) const;
 
     /**
      * @brief Use this method to forward messages of any kind.
@@ -219,6 +234,7 @@ public:
 
     /**
      * @brief Use this method to create a new sticker set owned by a user. The bot will be able to edit the sticker set thus created. You must use exactly one of the fields pngSticker or tgsSticker.
+     * 
      * @param userId User identifier of created sticker set owner
      * @param name Short name of sticker set, to be used in t.me/addstickers/ URLs (e.g., animals). Can contain only english letters, digits and underscores. Must begin with a letter, can't contain consecutive underscores and must end in “_by_<bot username>”. <bot_username> is case insensitive. 1-64 characters.
      * @param title Sticker set title, 1-64 characters
@@ -227,25 +243,41 @@ public:
      * @param tgsSticker Optional. TGS animation with the sticker, uploaded using multipart/form-data. See https://core.telegram.org/animated_stickers#technical-requirements for technical requirements
      * @param containsMasks Optional. Pass True, if a set of mask stickers should be created
      * @param maskPosition Optional. A JSON-serialized object for position where the mask should be placed on faces
+     * 
      * @return Returns True on success.
      */
-    bool createNewStickerSet(std::int64_t userId, const std::string& name, const std::string& title, const std::string& emojis,
-                             boost::variant<InputFile::Ptr, std::string> pngSticker = "", boost::variant<InputFile::Ptr, std::string> tgsSticker = "",
+    bool createNewStickerSet(std::int64_t userId, const std::string& name, const std::string& title,
+                             const std::string& emojis, boost::variant<InputFile::Ptr, std::string> pngSticker = "", boost::variant<InputFile::Ptr, std::string> tgsSticker = "",
                              bool containsMasks = false, MaskPosition::Ptr maskPosition = nullptr) const;
 
     /**
+     * @brief Deprecated. Use @ref Api::createNewStickerSet
+     * @deprecated since Bot API 4.7. This remains unchanged for backward compatibility.
+     */
+    bool createNewStickerSet(std::int64_t userId, const std::string& name, const std::string& title,
+                             boost::variant<InputFile::Ptr, std::string> pngSticker, const std::string& emojis, bool containsMasks = false, MaskPosition::Ptr maskPosition = nullptr) const;
+
+    /**
      * @brief Use this method to add a new sticker to a set created by the bot. You must use exactly one of the fields png_sticker or tgs_sticker. Animated stickers can be added to animated sticker sets and only to them. Animated sticker sets can have up to 50 stickers. Static sticker sets can have up to 120 stickers.
+     * 
      * @param userId User identifier of sticker set owner
      * @param name Sticker set name
      * @param emojis One or more emoji corresponding to the sticker
      * @param pngSticker Optional. PNG image with the sticker, must be up to 512 kilobytes in size, dimensions must not exceed 512px, and either width or height must be exactly 512px. Pass a file_id as a String to send a file that already exists on the Telegram servers, pass an HTTP URL as a String for Telegram to get a file from the Internet, or upload a new one using multipart/form-data.
      * @param tgsSticker Optional. TGS animation with the sticker, uploaded using multipart/form-data. See https://core.telegram.org/animated_stickers#technical-requirements for technical requirements
      * @param maskPosition Optional. A JSON-serialized object for position where the mask should be placed on faces
+     * 
      * @return Returns True on success.
      */
     bool addStickerToSet(std::int64_t userId, const std::string& name, const std::string& emojis,
-                         boost::variant<InputFile::Ptr, std::string> pngSticker = "", boost::variant<InputFile::Ptr, std::string> tgsSticker = "",
-                         MaskPosition::Ptr maskPosition = nullptr) const;
+                         boost::variant<InputFile::Ptr, std::string> pngSticker = "", boost::variant<InputFile::Ptr, std::string> tgsSticker = "", MaskPosition::Ptr maskPosition = nullptr) const;
+
+    /**
+     * @brief Deprecated. Use @ref Api::addStickerToSet
+     * @deprecated since Bot API 4.7. This remains unchanged for backward compatibility.
+     */
+    bool addStickerToSet(std::int64_t userId, const std::string& name, boost::variant<InputFile::Ptr, std::string> pngSticker,
+                         const std::string& emojis, MaskPosition::Ptr maskPosition = nullptr) const;
 
     /**
      * @brief Use this method to move a sticker in a set created by the bot to a specific position.
@@ -264,9 +296,11 @@ public:
 
     /**
      * @brief Use this method to set the thumbnail of a sticker set. Animated thumbnails can be set for animated sticker sets only.
+     * 
      * @param name Sticker set name
      * @param userId User identifier of the sticker set owner
      * @param thumb Optional. A PNG image with the thumbnail, must be up to 128 kilobytes in size and have width and height exactly 100px, or a TGS animation with the thumbnail up to 32 kilobytes in size; see https://core.telegram.org/animated_stickers#technical-requirements for animated sticker technical requirements. Pass a file_id as a String to send a file that already exists on the Telegram servers, pass an HTTP URL as a String for Telegram to get a file from the Internet, or upload a new one using multipart/form-data. Animated sticker set thumbnail can't be uploaded via HTTP URL.
+     * 
      * @return Returns True on success.
      */
     bool setStickerSetThumb(const std::string& name, std::int64_t userId, boost::variant<InputFile::Ptr, std::string> thumb = "") const;
@@ -696,9 +730,11 @@ public:
 
     /**
      * @brief Use this method to set a custom title for an administrator in a supergroup promoted by the bot.
+     * 
      * @param chatId Unique identifier for the target chat or username of the target supergroup (in the format @supergroupusername)
      * @param userId Unique identifier of the target user
      * @param customTitle New custom title for the administrator; 0-16 characters, emoji are not allowed
+     * 
      * @return True on success
      */
     bool setChatAdministratorCustomTitle(std::int64_t chatId, std::int64_t userId, const std::string& customTitle) const;
@@ -815,32 +851,45 @@ public:
 
     /**
      * @brief Use this method to send a native poll.
+     * 
      * @param chatId Unique identifier for the target chat or username of the target channel (in the format @channelusername)
      * @param question Poll question, 1-255 characters
      * @param options A JSON-serialized list of answer options, 2-10 strings 1-100 characters each
-     * @param disableNotification Optional. Sends the message silently. Users will receive a notification with no sound.
-     * @param replyToMessageId Optional. If the message is a reply, ID of the original message
-     * @param replyMarkup Optional. Additional interface options. A JSON-serialized object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the user.
      * @param isAnonymous Optional. True, if the poll needs to be anonymous, defaults to True
      * @param type Optional. Poll type, “quiz” or “regular”, defaults to “regular”
      * @param allowsMultipleAnswers Optional. True, if the poll allows multiple answers, ignored for polls in quiz mode, defaults to False
      * @param correctOptionId Optional. 0-based identifier of the correct answer option, required for polls in quiz mode
      * @param isClosed Optional. Pass True, if the poll needs to be immediately closed. This can be useful for poll preview.
-     * @return On success, the sent message is returned.
+     * @param disableNotification Optional. Sends the message silently. Users will receive a notification with no sound.
+     * @param replyToMessageId Optional. If the message is a reply, ID of the original message
+     * @param replyMarkup Optional. Additional interface options. A JSON-serialized object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the user.
+     * 
+     * @return On success, the sent @ref Message is returned.
      */
-    Message::Ptr sendPoll(std::int64_t chatId, const std::string& question, const std::vector<std::string>& options, bool disableNotification = false, std::int32_t replyToMessageId = 0,
-                          GenericReply::Ptr replyMarkup = std::make_shared<GenericReply>(), bool isAnonymous = true, const std::string& type = "", bool allowsMultipleAnswers = false,
-                          std::int32_t correctOptionId = 0, bool isClosed = false) const;
+    Message::Ptr sendPoll(std::int64_t chatId, const std::string& question, const std::vector<std::string>& options,
+                          bool isAnonymous = true, const std::string& type = "", bool allowsMultipleAnswers = false,
+                          std::int32_t correctOptionId = 0, bool isClosed = false, bool disableNotification = false,
+                          std::int32_t replyToMessageId = 0, GenericReply::Ptr replyMarkup = std::make_shared<GenericReply>()) const;
+
+    /**
+     * @brief Deprecated. Use @ref Api::sendPoll
+     * @deprecated since Bot API 4.6. This remains unchanged for backward compatibility.
+     */
+    Message::Ptr sendPoll(std::int64_t chatId, const std::string& question, const std::vector<std::string>& options,
+                          bool disableNotification = false, std::int32_t replyToMessageId = 0, GenericReply::Ptr replyMarkup = std::make_shared<GenericReply>()) const;
 
     /**
      * @brief Use this method to send a dice, which will have a random value from 1 to 6.
+     * 
      * @param chatId Unique identifier for the target chat or username of the target channel (in the format @channelusername)
      * @param disableNotification Optional. Sends the message silently. Users will receive a notification with no sound.
      * @param replyToMessageId Optional. If the message is a reply, ID of the original message
      * @param replyMarkup Optional. Additional interface options. A JSON-serialized object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the user.
-     * @return On success, the sent message is returned.
+     * 
+     * @return On success, the sent @ref Message is returned.
      */
-    Message::Ptr sendDice(std::int64_t chatId, bool disableNotification = false, std::int32_t replyToMessageId = 0, GenericReply::Ptr replyMarkup = std::make_shared<GenericReply>()) const;
+    Message::Ptr sendDice(std::int64_t chatId, bool disableNotification = false, std::int32_t replyToMessageId = 0,
+                          GenericReply::Ptr replyMarkup = std::make_shared<GenericReply>()) const;
 
     /**
      * @brief Use this method to stop a poll which was sent by the bot.