Telegram Bot API January 1, 2025 updates (v8.2)

Author: johnspade

README.md

@@ -1,6 +1,6 @@
 # F[Tg] - Telegramium
 
-[![Telegram](https://img.shields.io/badge/Telegram%20Bot%20API-8.1%20(December%204%2C%202024)-blue)](https://core.telegram.org/bots/api#recent-changes)
+[![Telegram](https://img.shields.io/badge/Telegram%20Bot%20API-8.2%20(January%201%2C%202025)-blue)](https://core.telegram.org/bots/api#recent-changes)
 [![Maven Central](https://maven-badges.herokuapp.com/maven-central/io.github.apimorphism/telegramium-core_3/badge.svg)](https://maven-badges.herokuapp.com/maven-central/io.github.apimorphism/telegramium-core_3)
 
 

build.sbt

@@ -1,7 +1,7 @@
 enablePlugins(GitPlugin)
 
 ThisBuild / version := Version.mkVersion(
-  "9.801.0",
+  "9.802.0",
   git.gitCurrentBranch.value,
   git.gitDescribedVersion.value,
   git.gitUncommittedChanges.value

telegramium-core/src/main/scala/telegramium/bots/BackgroundType.scala

@@ -20,7 +20,7 @@ final case class BackgroundTypeWallpaper(
   isMoving: Option[Boolean] = Option.empty
 ) extends BackgroundType
 
-/** The background is a PNG or TGV (gzipped subset of SVG with MIME type “application/x-tgwallpattern”) pattern to be
+/** 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.
   *
   * @param document

telegramium-core/src/main/scala/telegramium/bots/Gift.scala

@@ -8,6 +8,8 @@ package telegramium.bots
   *   The sticker that represents the gift
   * @param starCount
   *   The number of Telegram Stars that must be paid to send the sticker
+  * @param upgradeStarCount
+  *   Optional. The number of Telegram Stars that must be paid to upgrade the gift to a unique one
   * @param totalCount
   *   Optional. The total number of the gifts of this type that can be sent; for limited gifts only
   * @param remainingCount
@@ -17,6 +19,7 @@ final case class Gift(
   id: String,
   sticker: Sticker,
   starCount: Int,
+  upgradeStarCount: Option[Int] = Option.empty,
   totalCount: Option[Int] = Option.empty,
   remainingCount: Option[Int] = Option.empty
 )

telegramium-core/src/main/scala/telegramium/bots/InlineQueryResult.scala

@@ -9,7 +9,7 @@ sealed trait InlineQueryResult {}
   * @param id
   *   Unique identifier for this result, 1-64 bytes
   * @param gifUrl
-  *   A valid URL for the GIF file. File size must not exceed 1MB
+  *   A valid URL for the GIF file
   * @param thumbnailUrl
   *   URL of the static (JPEG or GIF) or animated (MPEG4) thumbnail for the result
   * @param gifWidth
@@ -277,8 +277,6 @@ final case class InlineQueryResultCachedVoice(
   *   Optional. Inline keyboard attached to the message
   * @param url
   *   Optional. URL of the result
-  * @param hideUrl
-  *   Optional. Pass True if you don't want the URL to be shown in the message
   * @param description
   *   Optional. Short description of the result
   * @param thumbnailUrl
@@ -294,7 +292,6 @@ final case class InlineQueryResultArticle(
   inputMessageContent: InputMessageContent,
   replyMarkup: Option[InlineKeyboardMarkup] = Option.empty,
   url: Option[String] = Option.empty,
-  hideUrl: Option[Boolean] = Option.empty,
   description: Option[String] = Option.empty,
   thumbnailUrl: Option[String] = Option.empty,
   thumbnailWidth: Option[Int] = Option.empty,
@@ -345,7 +342,7 @@ final case class InlineQueryResultAudio(
   * @param id
   *   Unique identifier for this result, 1-64 bytes
   * @param mpeg4Url
-  *   A valid URL for the MPEG4 file. File size must not exceed 1MB
+  *   A valid URL for the MPEG4 file
   * @param thumbnailUrl
   *   URL of the static (JPEG or GIF) or animated (MPEG4) thumbnail for the result
   * @param mpeg4Width

telegramium-core/src/main/scala/telegramium/bots/InputSticker.scala

@@ -9,7 +9,7 @@ package telegramium.bots
   *   Animated and video stickers can't be uploaded via HTTP URL.
   * @param format
   *   Format of the added sticker, must be one of “static” for a .WEBP or .PNG image, “animated” for a .TGS animation,
-  *   “video” for a WEBM video
+  *   “video” for a .WEBM video
   * @param emojiList
   *   List of 1-20 emoji associated with the sticker
   * @param maskPosition

telegramium-core/src/main/scala/telegramium/bots/client/GetUpdatesReq.scala

@@ -16,8 +16,8 @@ package telegramium.bots.client
   *   "edited_channel_post", "callback_query"] to only receive updates of these types. See Update for a complete list of
   *   available update types. Specify an empty list to receive all update types except chat_member, message_reaction,
   *   and message_reaction_count (default). If not specified, the previous setting will be used. Please note that this
-  *   parameter doesn't affect updates created before the call to the getUpdates, so unwanted updates may be received
-  *   for a short period of time.
+  *   parameter doesn't affect updates created before the call to getUpdates, so unwanted updates may be received for a
+  *   short period of time.
   */
 final case class GetUpdatesReq(
   offset: Option[Int] = Option.empty,

telegramium-core/src/main/scala/telegramium/bots/client/Methods.scala

@@ -1394,7 +1394,7 @@ trait Methods {
     *   "edited_channel_post", "callback_query"] to only receive updates of these types. See Update for a complete list
     *   of available update types. Specify an empty list to receive all update types except chat_member,
     *   message_reaction, and message_reaction_count (default). If not specified, the previous setting will be used.
-    *   Please note that this parameter doesn't affect updates created before the call to the getUpdates, so unwanted
+    *   Please note that this parameter doesn't affect updates created before the call to getUpdates, so unwanted
     *   updates may be received for a short period of time.
     */
   def getUpdates(
@@ -1600,6 +1600,28 @@ trait Methods {
     MethodReq[Boolean]("refundStarPayment", req.asJson)
   }
 
+  /** Removes verification from a chat that is currently verified on behalf of the organization represented by the bot.
+    * Returns True on success.
+    *
+    * @param chatId
+    *   Unique identifier for the target chat or username of the target channel (in the format @channelusername)
+    */
+  def removeChatVerification(chatId: ChatId): Method[Boolean] = {
+    val req = RemoveChatVerificationReq(chatId)
+    MethodReq[Boolean]("removeChatVerification", req.asJson)
+  }
+
+  /** Removes verification from a user who is currently verified on behalf of the organization represented by the bot.
+    * Returns True on success.
+    *
+    * @param userId
+    *   Unique identifier of the target user
+    */
+  def removeUserVerification(userId: Long): Method[Boolean] = {
+    val req = RemoveUserVerificationReq(userId)
+    MethodReq[Boolean]("removeUserVerification", req.asJson)
+  }
+
   /** Use this method to reopen a closed topic in a forum supergroup chat. The bot must be an administrator in the chat
     * for this to work and must have the can_manage_topics administrator rights, unless it is the creator of the topic.
     * Returns True on success.
@@ -2205,6 +2227,8 @@ trait Methods {
     *   Unique identifier of the target user that will receive the gift
     * @param giftId
     *   Identifier of the gift
+    * @param payForUpgrade
+    *   Pass True to pay for the gift upgrade from the bot's balance, thereby making the upgrade free for the receiver
     * @param text
     *   Text that will be shown along with the gift; 0-255 characters
     * @param textParseMode
@@ -2218,11 +2242,12 @@ trait Methods {
   def sendGift(
     userId: Long,
     giftId: String,
+    payForUpgrade: Option[Boolean] = Option.empty,
     text: Option[String] = Option.empty,
     textParseMode: Option[ParseMode] = Option.empty,
     textEntities: List[MessageEntity] = List.empty
   ): Method[Boolean] = {
-    val req = SendGiftReq(userId, giftId, text, textParseMode, textEntities)
+    val req = SendGiftReq(userId, giftId, payForUpgrade, text, textParseMode, textEntities)
     MethodReq[Boolean]("sendGift", req.asJson)
   }
 
@@ -3565,12 +3590,12 @@ trait Methods {
     *   User identifier of the sticker set owner
     * @param format
     *   Format of the thumbnail, must be one of “static” for a .WEBP or .PNG image, “animated” for a .TGS animation, or
-    *   “video” for a WEBM video
+    *   “video” for a .WEBM video
     * @param thumbnail
     *   A .WEBP or .PNG image with the thumbnail, must be up to 128 kilobytes in size and have a width and height of
     *   exactly 100px, or a .TGS animation with a thumbnail up to 32 kilobytes in size (see
     *   https://core.telegram.org/stickers#animation-requirements for animated sticker technical requirements), or a
-    *   WEBM video with the thumbnail up to 32 kilobytes in size; see
+    *   .WEBM video with the thumbnail up to 32 kilobytes in size; see
     *   https://core.telegram.org/stickers#video-requirements for video 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 and video
@@ -3624,10 +3649,10 @@ trait Methods {
 
   /** Use this method to specify a URL and receive incoming updates via an outgoing webhook. Whenever there is an update
     * for the bot, we will send an HTTPS POST request to the specified URL, containing a JSON-serialized Update. In case
-    * of an unsuccessful request, we will give up after a reasonable amount of attempts. Returns True on success. If
-    * you'd like to make sure that the webhook was set by you, you can specify secret data in the parameter
-    * secret_token. If specified, the request will contain a header “X-Telegram-Bot-Api-Secret-Token” with the secret
-    * token as content.
+    * of an unsuccessful request (a request with response HTTP status code different from 2XY), we will repeat the
+    * request and give up after a reasonable amount of attempts. Returns True on success. If you'd like to make sure
+    * that the webhook was set by you, you can specify secret data in the parameter secret_token. If specified, the
+    * request will contain a header “X-Telegram-Bot-Api-Secret-Token” with the secret token as content.
     *
     * @param url
     *   HTTPS URL to send updates to. Use an empty string to remove webhook integration
@@ -3844,4 +3869,30 @@ trait Methods {
     )
   }
 
+  /** Verifies a chat on behalf of the organization which is represented by the bot. Returns True on success.
+    *
+    * @param chatId
+    *   Unique identifier for the target chat or username of the target channel (in the format @channelusername)
+    * @param customDescription
+    *   Custom description for the verification; 0-70 characters. Must be empty if the organization isn't allowed to
+    *   provide a custom verification description.
+    */
+  def verifyChat(chatId: ChatId, customDescription: Option[String] = Option.empty): Method[Boolean] = {
+    val req = VerifyChatReq(chatId, customDescription)
+    MethodReq[Boolean]("verifyChat", req.asJson)
+  }
+
+  /** Verifies a user on behalf of the organization which is represented by the bot. Returns True on success.
+    *
+    * @param userId
+    *   Unique identifier of the target user
+    * @param customDescription
+    *   Custom description for the verification; 0-70 characters. Must be empty if the organization isn't allowed to
+    *   provide a custom verification description.
+    */
+  def verifyUser(userId: Long, customDescription: Option[String] = Option.empty): Method[Boolean] = {
+    val req = VerifyUserReq(userId, customDescription)
+    MethodReq[Boolean]("verifyUser", req.asJson)
+  }
+
 }

telegramium-core/src/main/scala/telegramium/bots/client/RemoveChatVerificationReq.scala

@@ -0,0 +1,8 @@
+package telegramium.bots.client
+
+import telegramium.bots.ChatId
+
+/** @param chatId
+  *   Unique identifier for the target chat or username of the target channel (in the format @channelusername)
+  */
+final case class RemoveChatVerificationReq(chatId: ChatId)

telegramium-core/src/main/scala/telegramium/bots/client/RemoveUserVerificationReq.scala

@@ -0,0 +1,4 @@
+package telegramium.bots.client
+
+/** @param userId Unique identifier of the target user */
+final case class RemoveUserVerificationReq(userId: Long)

telegramium-core/src/main/scala/telegramium/bots/client/SendGiftReq.scala

@@ -7,6 +7,8 @@ import telegramium.bots.MessageEntity
   *   Unique identifier of the target user that will receive the gift
   * @param giftId
   *   Identifier of the gift
+  * @param payForUpgrade
+  *   Pass True to pay for the gift upgrade from the bot's balance, thereby making the upgrade free for the receiver
   * @param text
   *   Text that will be shown along with the gift; 0-255 characters
   * @param textParseMode
@@ -20,6 +22,7 @@ import telegramium.bots.MessageEntity
 final case class SendGiftReq(
   userId: Long,
   giftId: String,
+  payForUpgrade: Option[Boolean] = Option.empty,
   text: Option[String] = Option.empty,
   textParseMode: Option[ParseMode] = Option.empty,
   textEntities: List[MessageEntity] = List.empty

telegramium-core/src/main/scala/telegramium/bots/client/SetStickerSetThumbnailReq.scala

@@ -8,11 +8,11 @@ import telegramium.bots.IFile
   *   User identifier of the sticker set owner
   * @param format
   *   Format of the thumbnail, must be one of “static” for a .WEBP or .PNG image, “animated” for a .TGS animation, or
-  *   “video” for a WEBM video
+  *   “video” for a .WEBM video
   * @param thumbnail
   *   A .WEBP or .PNG image with the thumbnail, must be up to 128 kilobytes in size and have a width and height of
   *   exactly 100px, or a .TGS animation with a thumbnail up to 32 kilobytes in size (see
-  *   https://core.telegram.org/stickers#animation-requirements for animated sticker technical requirements), or a WEBM
+  *   https://core.telegram.org/stickers#animation-requirements for animated sticker technical requirements), or a .WEBM
   *   video with the thumbnail up to 32 kilobytes in size; see https://core.telegram.org/stickers#video-requirements for
   *   video 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

telegramium-core/src/main/scala/telegramium/bots/client/VerifyChatReq.scala

@@ -0,0 +1,11 @@
+package telegramium.bots.client
+
+import telegramium.bots.ChatId
+
+/** @param chatId
+  *   Unique identifier for the target chat or username of the target channel (in the format @channelusername)
+  * @param customDescription
+  *   Custom description for the verification; 0-70 characters. Must be empty if the organization isn't allowed to
+  *   provide a custom verification description.
+  */
+final case class VerifyChatReq(chatId: ChatId, customDescription: Option[String] = Option.empty)

telegramium-core/src/main/scala/telegramium/bots/client/VerifyUserReq.scala

@@ -0,0 +1,9 @@
+package telegramium.bots.client
+
+/** @param userId
+  *   Unique identifier of the target user
+  * @param customDescription
+  *   Custom description for the verification; 0-70 characters. Must be empty if the organization isn't allowed to
+  *   provide a custom verification description.
+  */
+final case class VerifyUserReq(userId: Long, customDescription: Option[String] = Option.empty)

telegramium-core/src/main/scala/telegramium/bots/client/package.scala

@@ -887,6 +887,26 @@ object CirceImplicits {
       )
     }
 
+  implicit lazy val removechatverificationreqEncoder: Encoder[RemoveChatVerificationReq] =
+    (x: RemoveChatVerificationReq) => {
+      Json.fromFields(
+        List(
+          "chat_id" -> x.chatId.asJson,
+          "method"  -> "removeChatVerification".asJson
+        ).filter(!_._2.isNull)
+      )
+    }
+
+  implicit lazy val removeuserverificationreqEncoder: Encoder[RemoveUserVerificationReq] =
+    (x: RemoveUserVerificationReq) => {
+      Json.fromFields(
+        List(
+          "user_id" -> x.userId.asJson,
+          "method"  -> "removeUserVerification".asJson
+        ).filter(!_._2.isNull)
+      )
+    }
+
   implicit lazy val reopenforumtopicreqEncoder: Encoder[ReopenForumTopicReq] =
     (x: ReopenForumTopicReq) => {
       Json.fromFields(
@@ -1118,6 +1138,7 @@ object CirceImplicits {
         List(
           "user_id"         -> x.userId.asJson,
           "gift_id"         -> x.giftId.asJson,
+          "pay_for_upgrade" -> x.payForUpgrade.asJson,
           "text"            -> x.text.asJson,
           "text_parse_mode" -> x.textParseMode.asJson,
           "text_entities"   -> x.textEntities.asJson,
@@ -1824,4 +1845,26 @@ object CirceImplicits {
       )
     }
 
+  implicit lazy val verifychatreqEncoder: Encoder[VerifyChatReq] =
+    (x: VerifyChatReq) => {
+      Json.fromFields(
+        List(
+          "chat_id"            -> x.chatId.asJson,
+          "custom_description" -> x.customDescription.asJson,
+          "method"             -> "verifyChat".asJson
+        ).filter(!_._2.isNull)
+      )
+    }
+
+  implicit lazy val verifyuserreqEncoder: Encoder[VerifyUserReq] =
+    (x: VerifyUserReq) => {
+      Json.fromFields(
+        List(
+          "user_id"            -> x.userId.asJson,
+          "custom_description" -> x.customDescription.asJson,
+          "method"             -> "verifyUser".asJson
+        ).filter(!_._2.isNull)
+      )
+    }
+
 }