Telegram Bot API February 12, 2025 updates (v8.3)

johnspade · johnspade · commit 791ae80e3457 · 2025-02-18T02:34:50.000+01:00
diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
 # F[Tg] - Telegramium
 
-[![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)
+[![Telegram](https://img.shields.io/badge/Telegram%20Bot%20API-8.3%20(February%2012%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)
 
 
diff --git a/build.sbt b/build.sbt
@@ -1,7 +1,7 @@
 enablePlugins(GitPlugin)
 
 ThisBuild / version := Version.mkVersion(
-  "9.802.0",
+  "9.803.0",
   git.gitCurrentBranch.value,
   git.gitDescribedVersion.value,
   git.gitUncommittedChanges.value
diff --git a/telegramium-core/src/main/scala/telegramium/bots/ChatFullInfo.scala b/telegramium-core/src/main/scala/telegramium/bots/ChatFullInfo.scala
@@ -72,6 +72,8 @@ package telegramium.bots
   *   Optional. The most recent pinned message (by sending date)
   * @param permissions
   *   Optional. Default chat member permissions, for groups and supergroups
+  * @param canSendGift
+  *   Optional. True, if gifts can be sent to the chat
   * @param canSendPaidMedia
   *   Optional. True, if paid media messages can be sent or forwarded to the channel chat. The field is available only
   *   for channel chats.
@@ -139,6 +141,7 @@ final case class ChatFullInfo(
   inviteLink: Option[String] = Option.empty,
   pinnedMessage: Option[Message] = Option.empty,
   permissions: Option[ChatPermissions] = Option.empty,
+  canSendGift: Option[Boolean] = Option.empty,
   canSendPaidMedia: Option[Boolean] = Option.empty,
   slowModeDelay: Option[Int] = Option.empty,
   unrestrictBoostCount: Option[Int] = Option.empty,
diff --git a/telegramium-core/src/main/scala/telegramium/bots/InputMedia.scala b/telegramium-core/src/main/scala/telegramium/bots/InputMedia.scala
@@ -32,7 +32,7 @@ sealed trait InputMedia {}
   *   Optional. Pass True if the animation needs to be covered with a spoiler animation
   */
 final case class InputMediaAnimation(
-  media: String,
+  media: IFile,
   thumbnail: Option[IFile] = Option.empty,
   caption: Option[String] = Option.empty,
   parseMode: Option[ParseMode] = Option.empty,
@@ -62,7 +62,7 @@ final case class InputMediaAnimation(
   *   Optional. Pass True if the photo needs to be covered with a spoiler animation
   */
 final case class InputMediaPhoto(
-  media: String,
+  media: IFile,
   caption: Option[String] = Option.empty,
   parseMode: Option[ParseMode] = Option.empty,
   captionEntities: List[iozhik.OpenEnum[MessageEntity]] = List.empty,
@@ -82,6 +82,12 @@ final case class InputMediaPhoto(
   *   should not exceed 320. Ignored if the file is not uploaded using multipart/form-data. Thumbnails can't be reused
   *   and can be only uploaded as a new file, so you can pass “attach://<file_attach_name>” if the thumbnail was
   *   uploaded using multipart/form-data under <file_attach_name>.
+  * @param cover
+  *   Optional. Cover for the video in the message. Pass a file_id to send a file that exists on the Telegram servers
+  *   (recommended), pass an HTTP URL for Telegram to get a file from the Internet, or pass
+  *   “attach://<file_attach_name>” to upload a new one using multipart/form-data under <file_attach_name> name.
+  * @param startTimestamp
+  *   Optional. Start timestamp for the video in the message
   * @param caption
   *   Optional. Caption of the video to be sent, 0-1024 characters after entities parsing
   * @param parseMode
@@ -102,8 +108,10 @@ final case class InputMediaPhoto(
   *   Optional. Pass True if the video needs to be covered with a spoiler animation
   */
 final case class InputMediaVideo(
-  media: String,
+  media: IFile,
   thumbnail: Option[IFile] = Option.empty,
+  cover: Option[IFile] = Option.empty,
+  startTimestamp: Option[Int] = Option.empty,
   caption: Option[String] = Option.empty,
   parseMode: Option[ParseMode] = Option.empty,
   captionEntities: List[iozhik.OpenEnum[MessageEntity]] = List.empty,
@@ -138,7 +146,7 @@ final case class InputMediaVideo(
   *   Always True, if the document is sent as part of an album.
   */
 final case class InputMediaDocument(
-  media: String,
+  media: IFile,
   thumbnail: Option[IFile] = Option.empty,
   caption: Option[String] = Option.empty,
   parseMode: Option[ParseMode] = Option.empty,
@@ -172,7 +180,7 @@ final case class InputMediaDocument(
   *   Optional. Title of the audio
   */
 final case class InputMediaAudio(
-  media: String,
+  media: IFile,
   thumbnail: Option[IFile] = Option.empty,
   caption: Option[String] = Option.empty,
   parseMode: Option[ParseMode] = Option.empty,
diff --git a/telegramium-core/src/main/scala/telegramium/bots/InputPaidMedia.scala b/telegramium-core/src/main/scala/telegramium/bots/InputPaidMedia.scala
@@ -9,7 +9,7 @@ sealed trait InputPaidMedia {}
   *   for Telegram to get a file from the Internet, or pass “attach://<file_attach_name>” to upload a new one using
   *   multipart/form-data under <file_attach_name> name.
   */
-final case class InputPaidMediaPhoto(media: String) extends InputPaidMedia
+final case class InputPaidMediaPhoto(media: IFile) extends InputPaidMedia
 
 /** The paid media to send is a video.
   *
@@ -23,6 +23,12 @@ final case class InputPaidMediaPhoto(media: String) extends InputPaidMedia
   *   should not exceed 320. Ignored if the file is not uploaded using multipart/form-data. Thumbnails can't be reused
   *   and can be only uploaded as a new file, so you can pass “attach://<file_attach_name>” if the thumbnail was
   *   uploaded using multipart/form-data under <file_attach_name>.
+  * @param cover
+  *   Optional. Cover for the video in the message. Pass a file_id to send a file that exists on the Telegram servers
+  *   (recommended), pass an HTTP URL for Telegram to get a file from the Internet, or pass
+  *   “attach://<file_attach_name>” to upload a new one using multipart/form-data under <file_attach_name> name.
+  * @param startTimestamp
+  *   Optional. Start timestamp for the video in the message
   * @param width
   *   Optional. Video width
   * @param height
@@ -33,8 +39,10 @@ final case class InputPaidMediaPhoto(media: String) extends InputPaidMedia
   *   Optional. Pass True if the uploaded video is suitable for streaming
   */
 final case class InputPaidMediaVideo(
-  media: String,
+  media: IFile,
   thumbnail: Option[IFile] = Option.empty,
+  cover: Option[IFile] = Option.empty,
+  startTimestamp: Option[Int] = Option.empty,
   width: Option[Int] = Option.empty,
   height: Option[Int] = Option.empty,
   duration: Option[Int] = Option.empty,
diff --git a/telegramium-core/src/main/scala/telegramium/bots/StarTransaction.scala b/telegramium-core/src/main/scala/telegramium/bots/StarTransaction.scala
@@ -1,6 +1,8 @@
 package telegramium.bots
 
-/** Describes a Telegram Star transaction.
+/** Describes a Telegram Star transaction. Note that if the buyer initiates a chargeback with the payment provider from
+  * whom they acquired Stars (e.g., Apple, Google) following this transaction, the refunded Stars will be deducted from
+  * the bot's balance. This is outside of Telegram's control.
   *
   * @param id
   *   Unique identifier of the transaction. Coincides with the identifier of the original transaction for refund
diff --git a/telegramium-core/src/main/scala/telegramium/bots/SuccessfulPayment.scala b/telegramium-core/src/main/scala/telegramium/bots/SuccessfulPayment.scala
@@ -1,6 +1,8 @@
 package telegramium.bots
 
-/** This object contains basic information about a successful payment.
+/** This object contains basic information about a successful payment. Note that if the buyer initiates a chargeback
+  * with the relevant payment provider following this transaction, the funds may be debited from your balance. This is
+  * outside of Telegram's control.
   *
   * @param currency
   *   Three-letter ISO 4217 currency code, or “XTR” for payments in Telegram Stars
diff --git a/telegramium-core/src/main/scala/telegramium/bots/TransactionPartner.scala b/telegramium-core/src/main/scala/telegramium/bots/TransactionPartner.scala
@@ -2,6 +2,15 @@ package telegramium.bots
 
 sealed trait TransactionPartner {}
 
+/** Describes a transaction with a chat.
+  *
+  * @param chat
+  *   Information about the chat
+  * @param gift
+  *   Optional. The gift sent to the chat by the bot
+  */
+final case class TransactionPartnerChat(chat: Chat, gift: Option[Gift] = Option.empty) extends TransactionPartner
+
 /** Describes the affiliate program that issued the affiliate commission received via this transaction.
   *
   * @param commissionPerMille
diff --git a/telegramium-core/src/main/scala/telegramium/bots/Video.scala b/telegramium-core/src/main/scala/telegramium/bots/Video.scala
@@ -15,6 +15,10 @@ package telegramium.bots
   *   Duration of the video in seconds as defined by the sender
   * @param thumbnail
   *   Optional. Video thumbnail
+  * @param cover
+  *   Optional. Available sizes of the cover of the video in the message
+  * @param startTimestamp
+  *   Optional. Timestamp in seconds from which the video will play in the message
   * @param fileName
   *   Optional. Original filename as defined by the sender
   * @param mimeType
@@ -31,6 +35,8 @@ final case class Video(
   height: Int,
   duration: Int,
   thumbnail: Option[PhotoSize] = Option.empty,
+  cover: List[PhotoSize] = List.empty,
+  startTimestamp: Option[Int] = Option.empty,
   fileName: Option[String] = Option.empty,
   mimeType: Option[String] = Option.empty,
   fileSize: Option[Long] = Option.empty
diff --git a/telegramium-core/src/main/scala/telegramium/bots/client/AnswerShippingQueryReq.scala b/telegramium-core/src/main/scala/telegramium/bots/client/AnswerShippingQueryReq.scala
@@ -11,7 +11,7 @@ import telegramium.bots.ShippingOption
   *   Required if ok is True. A JSON-serialized array of available shipping options.
   * @param errorMessage
   *   Required if ok is False. Error message in human readable form that explains why it is impossible to complete the
-  *   order (e.g. "Sorry, delivery to your desired address is unavailable'). Telegram will display this message to the
+  *   order (e.g. “Sorry, delivery to your desired address is unavailable”). Telegram will display this message to the
   *   user.
   */
 final case class AnswerShippingQueryReq(
diff --git a/telegramium-core/src/main/scala/telegramium/bots/client/CopyMessageReq.scala b/telegramium-core/src/main/scala/telegramium/bots/client/CopyMessageReq.scala
@@ -15,6 +15,8 @@ import telegramium.bots.KeyboardMarkup
   *   Message identifier in the chat specified in from_chat_id
   * @param messageThreadId
   *   Unique identifier for the target message thread (topic) of the forum; for forum supergroups only
+  * @param videoStartTimestamp
+  *   New start timestamp for the copied video in the message
   * @param caption
   *   New caption for media, 0-1024 characters after entities parsing. If not specified, the original caption is kept
   * @param parseMode
@@ -42,6 +44,7 @@ final case class CopyMessageReq(
   fromChatId: ChatId,
   messageId: Int,
   messageThreadId: Option[Int] = Option.empty,
+  videoStartTimestamp: Option[Int] = Option.empty,
   caption: Option[String] = Option.empty,
   parseMode: Option[ParseMode] = Option.empty,
   captionEntities: List[MessageEntity] = List.empty,
diff --git a/telegramium-core/src/main/scala/telegramium/bots/client/ForwardMessageReq.scala b/telegramium-core/src/main/scala/telegramium/bots/client/ForwardMessageReq.scala
@@ -11,6 +11,8 @@ import telegramium.bots.ChatId
   *   Message identifier in the chat specified in from_chat_id
   * @param messageThreadId
   *   Unique identifier for the target message thread (topic) of the forum; for forum supergroups only
+  * @param videoStartTimestamp
+  *   New start timestamp for the forwarded video in the message
   * @param disableNotification
   *   Sends the message silently. Users will receive a notification with no sound.
   * @param protectContent
@@ -21,6 +23,7 @@ final case class ForwardMessageReq(
   fromChatId: ChatId,
   messageId: Int,
   messageThreadId: Option[Int] = Option.empty,
+  videoStartTimestamp: Option[Int] = Option.empty,
   disableNotification: Option[Boolean] = Option.empty,
   protectContent: Option[Boolean] = Option.empty
 )
diff --git a/telegramium-core/src/main/scala/telegramium/bots/client/Methods.scala b/telegramium-core/src/main/scala/telegramium/bots/client/Methods.scala
@@ -157,7 +157,7 @@ trait Methods {
     *   Required if ok is True. A JSON-serialized array of available shipping options.
     * @param errorMessage
     *   Required if ok is False. Error message in human readable form that explains why it is impossible to complete the
-    *   order (e.g. "Sorry, delivery to your desired address is unavailable'). Telegram will display this message to the
+    *   order (e.g. “Sorry, delivery to your desired address is unavailable”). Telegram will display this message to the
     *   user.
     */
   def answerShippingQuery(
@@ -290,6 +290,8 @@ trait Methods {
     *   Message identifier in the chat specified in from_chat_id
     * @param messageThreadId
     *   Unique identifier for the target message thread (topic) of the forum; for forum supergroups only
+    * @param videoStartTimestamp
+    *   New start timestamp for the copied video in the message
     * @param caption
     *   New caption for media, 0-1024 characters after entities parsing. If not specified, the original caption is kept
     * @param parseMode
@@ -317,6 +319,7 @@ trait Methods {
     fromChatId: ChatId,
     messageId: Int,
     messageThreadId: Option[Int] = Option.empty,
+    videoStartTimestamp: Option[Int] = Option.empty,
     caption: Option[String] = Option.empty,
     parseMode: Option[ParseMode] = Option.empty,
     captionEntities: List[MessageEntity] = List.empty,
@@ -332,6 +335,7 @@ trait Methods {
       fromChatId,
       messageId,
       messageThreadId,
+      videoStartTimestamp,
       caption,
       parseMode,
       captionEntities,
@@ -1103,6 +1107,8 @@ trait Methods {
     *   Message identifier in the chat specified in from_chat_id
     * @param messageThreadId
     *   Unique identifier for the target message thread (topic) of the forum; for forum supergroups only
+    * @param videoStartTimestamp
+    *   New start timestamp for the forwarded video in the message
     * @param disableNotification
     *   Sends the message silently. Users will receive a notification with no sound.
     * @param protectContent
@@ -1113,10 +1119,19 @@ trait Methods {
     fromChatId: ChatId,
     messageId: Int,
     messageThreadId: Option[Int] = Option.empty,
+    videoStartTimestamp: Option[Int] = Option.empty,
     disableNotification: Option[Boolean] = Option.empty,
     protectContent: Option[Boolean] = Option.empty
   ): Method[Message] = {
-    val req = ForwardMessageReq(chatId, fromChatId, messageId, messageThreadId, disableNotification, protectContent)
+    val req = ForwardMessageReq(
+      chatId,
+      fromChatId,
+      messageId,
+      messageThreadId,
+      videoStartTimestamp,
+      disableNotification,
+      protectContent
+    )
     MethodReq[Message]("forwardMessage", req.asJson)
   }
 
@@ -1151,7 +1166,8 @@ trait Methods {
     MethodReq[List[MessageId]]("forwardMessages", req.asJson)
   }
 
-  /** Returns the list of gifts that can be sent by the bot to users. Requires no parameters. Returns a Gifts object.
+  /** Returns the list of gifts that can be sent by the bot to users and channel chats. Requires no parameters. Returns
+    * a Gifts object.
     */
   def getAvailableGifts(): Method[Gifts] = {
     val req = GetAvailableGiftsReq
@@ -2220,17 +2236,20 @@ trait Methods {
     MethodReq[Message]("sendGame", req.asJson)
   }
 
-  /** Sends a gift to the given user. The gift can't be converted to Telegram Stars by the user. Returns True on
-    * success.
+  /** Sends a gift to the given user or channel chat. The gift can't be converted to Telegram Stars by the receiver.
+    * Returns True on success.
     *
-    * @param userId
-    *   Unique identifier of the target user that will receive the gift
     * @param giftId
     *   Identifier of the gift
+    * @param userId
+    *   Required if chat_id is not specified. Unique identifier of the target user who will receive the gift.
+    * @param chatId
+    *   Required if user_id is not specified. Unique identifier for the chat or username of the channel (in the format
+    *   &#064;channelusername) that will receive 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
+    *   Text that will be shown along with the gift; 0-128 characters
     * @param textParseMode
     *   Mode for parsing entities in the text. See formatting options for more details. Entities other than “bold”,
     *   “italic”, “underline”, “strikethrough”, “spoiler”, and “custom_emoji” are ignored.
@@ -2240,14 +2259,15 @@ trait Methods {
     *   “custom_emoji” are ignored.
     */
   def sendGift(
-    userId: Long,
     giftId: String,
+    userId: Option[Long] = Option.empty,
+    chatId: Option[ChatId] = Option.empty,
     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, payForUpgrade, text, textParseMode, textEntities)
+    val req = SendGiftReq(giftId, userId, chatId, payForUpgrade, text, textParseMode, textEntities)
     MethodReq[Boolean]("sendGift", req.asJson)
   }
 
@@ -3007,6 +3027,12 @@ trait Methods {
     *   exceed 320. Ignored if the file is not uploaded using multipart/form-data. Thumbnails can't be reused and can be
     *   only uploaded as a new file, so you can pass “attach://<file_attach_name>” if the thumbnail was uploaded using
     *   multipart/form-data under <file_attach_name>.
+    * @param cover
+    *   Cover for the video in the message. Pass a file_id to send a file that exists on the Telegram servers
+    *   (recommended), pass an HTTP URL for Telegram to get a file from the Internet, or pass
+    *   “attach://<file_attach_name>” to upload a new one using multipart/form-data under <file_attach_name> name.
+    * @param startTimestamp
+    *   Start timestamp for the video in the message
     * @param caption
     *   Video caption (may also be used when resending videos by file_id), 0-1024 characters after entities parsing
     * @param parseMode
@@ -3044,6 +3070,8 @@ trait Methods {
     width: Option[Int] = Option.empty,
     height: Option[Int] = Option.empty,
     thumbnail: Option[IFile] = Option.empty,
+    cover: Option[IFile] = Option.empty,
+    startTimestamp: Option[Int] = Option.empty,
     caption: Option[String] = Option.empty,
     parseMode: Option[ParseMode] = Option.empty,
     captionEntities: List[MessageEntity] = List.empty,
@@ -3066,6 +3094,8 @@ trait Methods {
       width,
       height,
       thumbnail,
+      cover,
+      startTimestamp,
       caption,
       parseMode,
       captionEntities,
@@ -3082,7 +3112,7 @@ trait Methods {
     MethodReq[Message](
       "sendVideo",
       req.asJson,
-      Map("video" -> Option(video), "thumbnail" -> thumbnail).collect { case (k, Some(v)) => k -> v }
+      Map("video" -> Option(video), "thumbnail" -> thumbnail, "cover" -> cover).collect { case (k, Some(v)) => k -> v }
     )
   }
 
@@ -3396,9 +3426,9 @@ trait Methods {
     MethodReq[Either[Boolean, Message]]("setGameScore", req.asJson)
   }
 
-  /** Use this method to change the chosen reactions on a message. Service messages can't be reacted to. Automatically
-    * forwarded messages from a channel to its discussion group have the same available reactions as messages in the
-    * channel. Bots can't use paid reactions. Returns True on success.
+  /** Use this method to change the chosen reactions on a message. Service messages of some types can't be reacted to.
+    * Automatically forwarded messages from a channel to its discussion group have the same available reactions as
+    * messages in the channel. Bots can't use paid reactions. Returns True on success.
     *
     * @param chatId
     *   Unique identifier for the target chat or username of the target channel (in the format &#064;channelusername)
diff --git a/telegramium-core/src/main/scala/telegramium/bots/client/SendGiftReq.scala b/telegramium-core/src/main/scala/telegramium/bots/client/SendGiftReq.scala
diff --git a/telegramium-core/src/main/scala/telegramium/bots/client/SendVideoReq.scala b/telegramium-core/src/main/scala/telegramium/bots/client/SendVideoReq.scala
diff --git a/telegramium-core/src/main/scala/telegramium/bots/client/package.scala b/telegramium-core/src/main/scala/telegramium/bots/client/package.scala
diff --git a/telegramium-core/src/main/scala/telegramium/bots/package.scala b/telegramium-core/src/main/scala/telegramium/bots/package.scala

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,8 @@`
`1`	`1`	`package telegramium.bots`
`2`	`2`
`3`		`-/** Describes a Telegram Star transaction.`
	`3`	`+/** Describes a Telegram Star transaction. Note that if the buyer initiates a chargeback with the payment provider from`
	`4`	`+ * whom they acquired Stars (e.g., Apple, Google) following this transaction, the refunded Stars will be deducted from`
	`5`	`+ * the bot's balance. This is outside of Telegram's control.`
`4`	`6`	`*`
`5`	`7`	`* @param id`
`6`	`8`	`* Unique identifier of the transaction. Coincides with the identifier of the original transaction for refund`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,8 @@`
`1`	`1`	`package telegramium.bots`
`2`	`2`
`3`		`-/** This object contains basic information about a successful payment.`
	`3`	`+/** This object contains basic information about a successful payment. Note that if the buyer initiates a chargeback`
	`4`	`+ * with the relevant payment provider following this transaction, the funds may be debited from your balance. This is`
	`5`	`+ * outside of Telegram's control.`
`4`	`6`	`*`
`5`	`7`	`* @param currency`
`6`	`8`	`* Three-letter ISO 4217 currency code, or “XTR” for payments in Telegram Stars`