Merge pull request #1404 from TelegramBots/develop

Bot API 7.8

.azure-pipelines/variables.yml

@@ -1,7 +1,7 @@
-variables:
+variables:
  - group: Integration Tests Variables
  - name: versionPrefix
- value: 21.7.1
+ value: 21.8.0
  - name: versionSuffix
  value: ''
  - name: ciVersionSuffix

CHANGELOG.md

@@ -1,7 +1,7 @@
 ## [v21.*] - 2024-06-22
 
 Starting with version 21.x, changes are documented here: 
-https://telegrambots.github.io/book/Migration-Guide-to-Version-21.x.html
+https://telegrambots.github.io/book/migrate/Version-21.x.html
 
 We keep this library updated to the latest version of Telegram Bot API. 
 See the [latest changes to Bot API here](https://core.telegram.org/bots/api#recent-changes)

README.md

@@ -1,7 +1,7 @@
-# .NET Client for Telegram Bot API
+# .NET Client for Telegram Bot API
 
 [![Nuget](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fnuget.voids.site%2Fv3%2Fpackage%2FTelegram.Bot%2Findex.json&query=versions%5B-1%3A%5D&style=flat-square&label=Telegram.Bot&color=d8b541)](https://nuget.voids.site/packages/Telegram.Bot)
-[![Bot API Version](https://img.shields.io/badge/Bot%20API-7.7-f36caf.svg?style=flat-square)](https://core.telegram.org/bots/api#july-7-2024)
+[![Bot API Version](https://img.shields.io/badge/Bot_API-7.8-f36caf.svg?style=flat-square)](https://core.telegram.org/bots/api)
 [![Documentations](https://img.shields.io/badge/Documentations-Book-orange.svg?style=flat-square)](https://telegrambots.github.io/book/)
 [![Telegram Chat](https://img.shields.io/badge/Support_Chat-Telegram-blue.svg?style=flat-square)](https://t.me/joinchat/B35YY0QbLfd034CFnvCtCA) 
 [![Master build](https://img.shields.io/azure-devops/build/tgbots/14f9ab3f-313a-4339-8534-e8b96c7763cc/6?style=flat-square&label=master)](https://dev.azure.com/tgbots/Telegram.Bot/_build/latest?definitionId=6&branchName=master)
@@ -32,7 +32,7 @@ Please check ➡️ [the Quickstart guide].
 
 ## 🚧 Supported Platforms
 
-Project targets **.NET Standard 2.0** and **.NET 6** at minimum.
+Project targets **.NET Standard 2.0** and **.NET 6** at minimum, with **.NET 8** or more recent recommended.
 
 ## 📦 Extension Packages
 

src/Telegram.Bot/ITelegramBotClient.cs

@@ -6,6 +6,10 @@
 
 namespace Telegram.Bot;
 
+#pragma warning disable CS1591
+public delegate ValueTask AsyncEventHandler<in TArgs>(ITelegramBotClient botClient, TArgs args, CancellationToken cancellationToken = default);
+#pragma warning restore CS1591
+
 /// <summary>
 /// A client interface to use the Telegram Bot API
 /// </summary>
@@ -75,8 +79,8 @@ Task<TResponse> MakeRequestAsync<TResponse>(
  /// <param name="cancellationToken">
  /// A cancellation token that can be used by other objects or threads to receive notice of cancellation.
  /// </param>
- /// <exception cref="ArgumentException">filePath is <c>null</c>, empty or too short</exception>
- /// <exception cref="ArgumentNullException"><paramref name="destination"/> is <c>null</c></exception>
+ /// <exception cref="ArgumentException">filePath is <see langword="null"/>, empty or too short</exception>
+ /// <exception cref="ArgumentNullException"><paramref name="destination"/> is <see langword="null"/></exception>
  Task DownloadFileAsync(
  string filePath,
  Stream destination,

src/Telegram.Bot/Requests/Available methods/Manage Chat/PinChatMessageRequest.cs

@@ -1,7 +1,7 @@
 namespace Telegram.Bot.Requests;
 
 /// <summary>Use this method to add a message to the list of pinned messages in a chat. If the chat is not a private chat, the bot must be an administrator in the chat for this to work and must have the 'CanPinMessages' administrator right in a supergroup or 'CanEditMessages' administrator right in a channel.<para>Returns: </para></summary>
-public partial class PinChatMessageRequest : RequestBase<bool>, IChatTargetable
+public partial class PinChatMessageRequest : RequestBase<bool>, IChatTargetable, IBusinessConnectable
 {
  /// <summary>Unique identifier for the target chat or username of the target channel (in the format <c>@channelusername</c>)</summary>
  [JsonIgnore(Condition = JsonIgnoreCondition.Never)]
@@ -14,6 +14,9 @@ public partial class PinChatMessageRequest : RequestBase<bool>, IChatTargetable
  /// <summary>Pass <see langword="true"/> if it is not necessary to send a notification to all chat members about the new pinned message. Notifications are always disabled in channels and private chats.</summary>
  public bool DisableNotification { get; set; }
 
+ /// <summary>Unique identifier of the business connection on behalf of which the message will be pinned</summary>
+ public string? BusinessConnectionId { get; set; }
+
  /// <summary>Initializes an instance of <see cref="PinChatMessageRequest"/></summary>
  /// <param name="chatId">Unique identifier for the target chat or username of the target channel (in the format <c>@channelusername</c>)</param>
  /// <param name="messageId">Identifier of a message to pin</param>

src/Telegram.Bot/Requests/Available methods/Manage Chat/UnpinChatMessageRequest.cs

@@ -1,15 +1,18 @@
 namespace Telegram.Bot.Requests;
 
 /// <summary>Use this method to remove a message from the list of pinned messages in a chat. If the chat is not a private chat, the bot must be an administrator in the chat for this to work and must have the 'CanPinMessages' administrator right in a supergroup or 'CanEditMessages' administrator right in a channel.<para>Returns: </para></summary>
-public partial class UnpinChatMessageRequest : RequestBase<bool>, IChatTargetable
+public partial class UnpinChatMessageRequest : RequestBase<bool>, IChatTargetable, IBusinessConnectable
 {
  /// <summary>Unique identifier for the target chat or username of the target channel (in the format <c>@channelusername</c>)</summary>
  [JsonIgnore(Condition = JsonIgnoreCondition.Never)]
  public required ChatId ChatId { get; set; }
 
- /// <summary>Identifier of a message to unpin. If not specified, the most recent pinned message (by sending date) will be unpinned.</summary>
+ /// <summary>Identifier of the message to unpin. Required if <see cref="BusinessConnectionId">BusinessConnectionId</see> is specified. If not specified, the most recent pinned message (by sending date) will be unpinned.</summary>
  public int? MessageId { get; set; }
 
+ /// <summary>Unique identifier of the business connection on behalf of which the message will be unpinned</summary>
+ public string? BusinessConnectionId { get; set; }
+
  /// <summary>Initializes an instance of <see cref="UnpinChatMessageRequest"/></summary>
  /// <param name="chatId">Unique identifier for the target chat or username of the target channel (in the format <c>@channelusername</c>)</param>
  [Obsolete("Use parameterless constructor with required properties")]

src/Telegram.Bot/Requests/Stickers/SetStickerSetThumbnailRequest.cs

@@ -15,7 +15,7 @@ public partial class SetStickerSetThumbnailRequest : FileRequestBase<bool>, IUse
  [JsonIgnore(Condition = JsonIgnoreCondition.Never)]
  public required StickerFormat Format { get; set; }
 
- /// <summary>A <b>.WEBP</b> or <b>.PNG</b> image with the thumbnail, must be up to 128 kilobytes in size and have a width and height of exactly 100px, or a <b>.TGS</b> animation with a thumbnail up to 32 kilobytes in size (see <a href="https://core.telegram.org/stickers#animated-sticker-requirements">https://core.telegram.org/stickers#animated-sticker-requirements</a> for animated sticker technical requirements), or a <b>WEBM</b> video with the thumbnail up to 32 kilobytes in size; see <a href="https://core.telegram.org/stickers#video-sticker-requirements">https://core.telegram.org/stickers#video-sticker-requirements</a> for video sticker technical requirements. Pass a <em>FileId</em> 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 <see cref="InputFileStream"/>. <a href="https://core.telegram.org/bots/api#sending-files">More information on Sending Files »</a>. Animated and video sticker set thumbnails can't be uploaded via HTTP URL. If omitted, then the thumbnail is dropped and the first sticker is used as the thumbnail.</summary>
+ /// <summary>A <b>.WEBP</b> or <b>.PNG</b> image with the thumbnail, must be up to 128 kilobytes in size and have a width and height of exactly 100px, or a <b>.TGS</b> animation with a thumbnail up to 32 kilobytes in size (see <a href="https://core.telegram.org/stickers#animation-requirements">https://core.telegram.org/stickers#animation-requirements</a> for animated sticker technical requirements), or a <b>WEBM</b> video with the thumbnail up to 32 kilobytes in size; see <a href="https://core.telegram.org/stickers#video-requirements">https://core.telegram.org/stickers#video-requirements</a> for video sticker technical requirements. Pass a <em>FileId</em> 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 <see cref="InputFileStream"/>. <a href="https://core.telegram.org/bots/api#sending-files">More information on Sending Files »</a>. Animated and video sticker set thumbnails can't be uploaded via HTTP URL. If omitted, then the thumbnail is dropped and the first sticker is used as the thumbnail.</summary>
  public InputFile? Thumbnail { get; set; }
 
  /// <summary>Initializes an instance of <see cref="SetStickerSetThumbnailRequest"/></summary>

src/Telegram.Bot/TelegramBotClient.cs

@@ -39,6 +39,10 @@ public TimeSpan Timeout
  internal string BaseFileUrl => _options.BaseFileUrl;
  #endregion
 
+#pragma warning disable CS1591
+ public delegate Task OnUpdateHandler(Update update);
+ public delegate Task OnMessageHandler(Message message, UpdateType type);
+ public delegate Task OnErrorHandler(Exception exception, Polling.HandleErrorSource source);
  OnUpdateHandler? _onUpdate;
  OnMessageHandler? _onMessage;
  CancellationTokenSource? _receivingEvents;
@@ -48,6 +52,7 @@ public TimeSpan Timeout
  public event OnMessageHandler? OnMessage { add { _onMessage += value; StartEventReceiving(); } remove { _onMessage -= value; StopEventReceiving(); } }
  /// <summary>Handler to be called when there was a polling error or an exception in your handlers</summary>
  public event OnErrorHandler? OnError;
+#pragma warning restore CS1591
 
  /// <summary>
  /// Global cancellation token
@@ -358,7 +363,7 @@ private void StartEventReceiving()
  {
  var task = OnError?.Invoke(ex, source);
  if (task != null) await task.ConfigureAwait(true);
- else System.Diagnostics.Debug.WriteLine(ex); // fallback logging if OnError is unset
+ else System.Diagnostics.Trace.WriteLine(ex); // fallback logging if OnError is unset
  }, new() { AllowedUpdates = Update.AllTypes }, _receivingEvents.Token);
  }
 

src/Telegram.Bot/TelegramBotClientExtensions.ApiMethods.cs

@@ -1,4 +1,4 @@
-using System.Threading;
+using System.Threading;
 using System.Threading.Tasks;
 using Telegram.Bot.Requests;
 using File = Telegram.Bot.Types.File;
@@ -1526,34 +1526,40 @@ public static async Task SetChatDescriptionAsync(
  /// <param name="chatId">Unique identifier for the target chat or username of the target channel (in the format <c>@channelusername</c>)</param>
  /// <param name="messageId">Identifier of a message to pin</param>
  /// <param name="disableNotification">Pass <see langword="true"/> if it is not necessary to send a notification to all chat members about the new pinned message. Notifications are always disabled in channels and private chats.</param>
+ /// <param name="businessConnectionId">Unique identifier of the business connection on behalf of which the message will be pinned</param>
  /// <param name="cancellationToken">A cancellation token that can be used by other objects or threads to receive notice of cancellation</param>
  public static async Task PinChatMessageAsync(
  this ITelegramBotClient botClient,
  ChatId chatId,
  int messageId,
  bool disableNotification = default,
+ string? businessConnectionId = default,
  CancellationToken cancellationToken = default
  ) => await botClient.ThrowIfNull().MakeRequestAsync(new PinChatMessageRequest
  {
  ChatId = chatId,
  MessageId = messageId,
  DisableNotification = disableNotification,
+ BusinessConnectionId = businessConnectionId,
  }, cancellationToken).ConfigureAwait(false);
 
  /// <summary>Use this method to remove a message from the list of pinned messages in a chat. If the chat is not a private chat, the bot must be an administrator in the chat for this to work and must have the 'CanPinMessages' administrator right in a supergroup or 'CanEditMessages' administrator right in a channel.</summary>
  /// <param name="botClient">An instance of <see cref="ITelegramBotClient"/></param>
  /// <param name="chatId">Unique identifier for the target chat or username of the target channel (in the format <c>@channelusername</c>)</param>
- /// <param name="messageId">Identifier of a message to unpin. If not specified, the most recent pinned message (by sending date) will be unpinned.</param>
+ /// <param name="messageId">Identifier of the message to unpin. Required if <paramref name="businessConnectionId"/> is specified. If not specified, the most recent pinned message (by sending date) will be unpinned.</param>
+ /// <param name="businessConnectionId">Unique identifier of the business connection on behalf of which the message will be unpinned</param>
  /// <param name="cancellationToken">A cancellation token that can be used by other objects or threads to receive notice of cancellation</param>
  public static async Task UnpinChatMessageAsync(
  this ITelegramBotClient botClient,
  ChatId chatId,
  int? messageId = default,
+ string? businessConnectionId = default,
  CancellationToken cancellationToken = default
  ) => await botClient.ThrowIfNull().MakeRequestAsync(new UnpinChatMessageRequest
  {
  ChatId = chatId,
  MessageId = messageId,
+ BusinessConnectionId = businessConnectionId,
  }, cancellationToken).ConfigureAwait(false);
 
  /// <summary>Use this method to clear the list of pinned messages in a chat. If the chat is not a private chat, the bot must be an administrator in the chat for this to work and must have the 'CanPinMessages' administrator right in a supergroup or 'CanEditMessages' administrator right in a channel.</summary>
@@ -2791,7 +2797,7 @@ public static async Task SetStickerSetTitleAsync(
  /// <param name="name">Sticker set name</param>
  /// <param name="userId">User identifier of the sticker set owner</param>
  /// <param name="format">Format of the thumbnail, must be one of <see cref="StickerFormat.Static">Static</see> for a <b>.WEBP</b> or <b>.PNG</b> image, <see cref="StickerFormat.Animated">Animated</see> for a <b>.TGS</b> animation, or <see cref="StickerFormat.Video">Video</see> for a <b>WEBM</b> video</param>
- /// <param name="thumbnail">A <b>.WEBP</b> or <b>.PNG</b> image with the thumbnail, must be up to 128 kilobytes in size and have a width and height of exactly 100px, or a <b>.TGS</b> animation with a thumbnail up to 32 kilobytes in size (see <a href="https://core.telegram.org/stickers#animated-sticker-requirements">https://core.telegram.org/stickers#animated-sticker-requirements</a> for animated sticker technical requirements), or a <b>WEBM</b> video with the thumbnail up to 32 kilobytes in size; see <a href="https://core.telegram.org/stickers#video-sticker-requirements">https://core.telegram.org/stickers#video-sticker-requirements</a> for video sticker technical requirements. Pass a <em>FileId</em> 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 <see cref="InputFileStream"/>. <a href="https://core.telegram.org/bots/api#sending-files">More information on Sending Files »</a>. Animated and video sticker set thumbnails can't be uploaded via HTTP URL. If omitted, then the thumbnail is dropped and the first sticker is used as the thumbnail.</param>
+ /// <param name="thumbnail">A <b>.WEBP</b> or <b>.PNG</b> image with the thumbnail, must be up to 128 kilobytes in size and have a width and height of exactly 100px, or a <b>.TGS</b> animation with a thumbnail up to 32 kilobytes in size (see <a href="https://core.telegram.org/stickers#animation-requirements">https://core.telegram.org/stickers#animation-requirements</a> for animated sticker technical requirements), or a <b>WEBM</b> video with the thumbnail up to 32 kilobytes in size; see <a href="https://core.telegram.org/stickers#video-requirements">https://core.telegram.org/stickers#video-requirements</a> for video sticker technical requirements. Pass a <em>FileId</em> 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 <see cref="InputFileStream"/>. <a href="https://core.telegram.org/bots/api#sending-files">More information on Sending Files »</a>. Animated and video sticker set thumbnails can't be uploaded via HTTP URL. If omitted, then the thumbnail is dropped and the first sticker is used as the thumbnail.</param>
  /// <param name="cancellationToken">A cancellation token that can be used by other objects or threads to receive notice of cancellation</param>
  public static async Task SetStickerSetThumbnailAsync(
  this ITelegramBotClient botClient,

src/Telegram.Bot/Types/User.cs

@@ -40,4 +40,7 @@ public partial class User
 
  /// <summary><em>Optional</em>. <see langword="true"/>, if the bot can be connected to a Telegram Business account to receive its messages. Returned only in <see cref="TelegramBotClientExtensions.GetMeAsync">GetMe</see>.</summary>
  public bool CanConnectToBusiness { get; set; }
+
+ /// <summary><em>Optional</em>. <see langword="true"/>, if the bot has a main Web App. Returned only in <see cref="TelegramBotClientExtensions.GetMeAsync">GetMe</see>.</summary>
+ public bool HasMainWebApp { get; set; }
 }

test/Telegram.Bot.Tests.Integ/Admin Bot/ChatMemberAdministrationTestFixture.cs

@@ -43,7 +43,7 @@ await testsFixture.SendTestCollectionNotificationAsync(collectionName,
  $"[{chat.FirstName}](tg://user?id={chat.Id}) doesn't have a username.\n" +
  "❎ Failing tests...");
 
- throw new ArgumentNullException(nameof(chat.Username), "Chat member doesn't have a username");
+ throw new InvalidOperationException("Chat member doesn't have a username");
  }
 
  public async Task InitializeAsync()

test/Telegram.Bot.Tests.Integ/Framework/RetryTelegramBotClient.cs

@@ -24,9 +24,10 @@ internal class TestClientOptions(
 };
 
 internal class RetryTelegramBotClient(
+ TestClientOptions options,
  IMessageSink diagnosticMessageSink,
- TestClientOptions options)
- : TelegramBotClient(options)
+ CancellationToken ct = default)
+ : TelegramBotClient(options, cancellationToken: ct)
 {
  private Stream[]? _testStreams;
  public void WithStreams(Stream[] streams) => _testStreams = streams;
@@ -74,7 +75,7 @@ internal static class RetryTelegramBotClientExtensions
 {
  public static ITelegramBotClient WithStreams(this ITelegramBotClient botClient, params System.IO.Stream[] streams)
  {
- ((RetryTelegramBotClient)botClient).WithStreams(streams);
+ if (botClient is RetryTelegramBotClient retry) retry.WithStreams(streams);
  return botClient;
  }
 }