Migration guide for version 22.x

If you're migrating from version 19.x, you might want to read our migration doc for v21 first. There were lots of interesting changes in versions v21.x.

We are back on Nuget.org!
And our old nuget feed nuget.voids.site is no more, so please remove this line from your nuget.config file, or from your IDE settings (Package sources)

⚠️ Breaking changes

We removed the Async suffix from our API method names, and renamed SendTextMessageAsync to SendMessage.
This was done to match official API documentation and because all our TelegramBotClient methods are asynchronous (no real need to differenciate between async or non-async methods)

We also reordered a few optional parameters to move away the lesser used arguments later down the argument list (typically: message_thread_id/entities) and move the more useful arguments up closer to the beginning (typically: replyParameters/replyMarkup)
This should make your life simpler as you won't need to resort to named arguments for the most commonly used method parameters.

Finally, we renamed property Message.MessageId as just Message.Id. (but MessageId will remain supported)

note

All the previous names are still supported at the moment, so your code should just run fine with version 22.0, except you will get warnings about "Obsolete" code while compiling.

📝 How to adapt your code for these changes

In order to port your code easily and get rid of compiler warnings, I suggest you use these 4 Find and Replace operations in your IDE

So start by opening the Edit > Find and Replace > Replace in Files panel (Ctrl+Shift+H)
Untick the checkboxes: Match case and Match whole word
Tick the checkbox: ✓ Use regular expressions
Select the scope to look in: Current project or Entire solution

(In the following, we suppose your TelegramBotClient variable is named bot, please modify the expressions if necessary)

  1. To remove explicit null arguments for messageThreadId/entities
    Replace: (bot\.Send\w+Async\b.*,) null,
        With: $1
    🖱️Click on Replace All
    🖱️Click on Replace All again

  2. To rename SendTextMessageAsync with SendMessage
    Replace: \.SendTextMessageAsync\b
        With: .SendMessage
    🖱️Click on Replace All

  3. To remove the Async suffixes:
    Replace: (bot\.\w+)Async\b
        With: $1
    🖱️Click on Replace All

  4. To rename the MessageId property:
    Replace: (message)\.MessageId\b
        With: $1.Id
    🖱️Click on Replace All
    (Depending on your variable naming convention, you might want to repeat that, replacing (message) with (msg) or something else)

The remaining effort to make your code compile should now be much reduced.
(maybe a few more parameter reordering if you didn't use named parameters)

Addendum: we also renamed method MakeRequestAsync to SendRequest (if you use this non-recommended method)

What's new in version 22.0

  • Support for Bot API 7.11
  • Implicit conversions for single-field structures
    For example classes containing just one string (like BotDescription, WebAppInfo or CopyTextButton) can be handled just as a string
  • Implicit conversion from FileBase classes to InputFile
    This means you can pass an object like a Video or PhotoSize directly as argument to a Send method and it will use its FileId
  • Helper method GetFileIdType
    It can tell you which type of object/media is referenced by a FileId string
  • Huge rewrite of our serialization code to make it more performant and straightforward.
  • Updated System.Text.Json due to vulnerability CVE-2024-43485

What's new in version 22.1

  • Support for Bot API 8.0
  • new helper message.MessageLink() to get the t.me link to that message (Supergroup and Channel only)
  • ToHtml/ToMarkdown: support for ExpandableBlockquote (v22.1.1)
  • fix savePreparedInlineMessage request (v22.1.2)
  • TransactionPartnerUser.Gift type was corrected in Bot API (v22.1.3)

What's new in version 22.2

  • Support for Bot API 8.1
  • Support for Native AOT / Blazor / Trimming
    (this is still experimental and we would enjoy your feedback if you try to use the library in such contexts)

What's new in version 22.3

  • Support for Bot API 8.2
  • Renamed class Telegram.Bot.Types.File as TGFile
    (the name File was annoyingly conflicting with the often-used System.IO.File class)
  • Added property Token to TelegramBotClient
    (you can use it to ParseValidateData MiniApp requests, authenticate WebHook updates, ...)

What's new in version 22.4

  • Support for Bot API 8.3
  • Added helpers ChatMember.IsInChat and ChatMember.IsAdmin
  • Added constructor ChatPermissions(bool) to set all fields to true or false
  • Fix a potential issue in .ToHtml() escaping & in URLs
  • Renamed helper classes Emoji to DiceEmoji and KnownReactionTypeEmoji to ReactionEmoji
  • Changed IReplyMarkup to abstract class ReplyMarkup so you can directly pass text, button or arrays of buttons for the replyMarkup: parameter
  • BotCommand can also now be implicitly constructed from a (string command, string description) tuple or new explicit constructor (v22.4.3)
    Example: await Bot.SetMyCommands([("/start", "Start the bot"), ("/privacy", "Privacy policy")]);
  • Added helper DownloadFile(TGFile file, ...) (v22.4.4)

What's new in version 22.5

  • Support for Bot API 9.0
  • Removed the *Async-suffixed versions of the methods that were marked [Obsolete] since v22.0.
    → Follow the steps at the top of this page to adapt your existing code if you haven't already.
  • Services.ConfigureTelegramBot* is no longer necessary to make your Webhook bot compatible with Telegram updates!
    → We've made the library structures compatible with the default JsonCamelCaseNamingPolicy used by ASP.NET Core projects.
    In some rare cases (like Native AOT / Blazor / Trimming), this call might still be necessary.
  • Removed dependency on ASP.NET Core (Microsoft.AspNetCore.App) from the main library, by moving the ConfigureTelegramBotMvc() method to a separate package Telegram.Bot.AspNetCore
    → That dependency caused some issues for users deploying to Docker / Android / WebAssembly
    → As explained above, you shouldn't need this method anymore in most cases, but if you do, you can add the nuget package Telegram.Bot.AspNetCore to your project
  • Merged the Telegram.Bot.Extensions.Passport package into the main library
    → It was old and unmaintained, but now its methods and structures supporting Telegram Passport are up-to-date and available directly in Telegram.Bot
  • New HtmlText helpers method: ToPlain, PlainLength and Truncate to get the plain text only from HTML text (remove the <tags>), the number of plain text characters, or truncate the HTML to a number of plain text characters (useful to comply with the 4096/1024 message limit)
  • Added constructor ChatAdministratorRights(bool) to set all fields to true or false (except IsAnonymous)
  • Added helper property message.IsServiceMessage to detect service messages vs content messages

Builds & Releases:

  • Dropped Azure DevOps builds in favor of GitHub Actions
    → Our alternative nuget feed will no longer be updated since we are back on Nuget.org
  • "Prerelease" versions are now pushed to Nuget.org as the library is developed, for people who want to test upcoming features early
    → You can provide feedback on these versions and help us detect problems before the next stable release
  • Now including Release Notes as part of Nuget packages
    → You can see them on nuget.org package page, or in your IDE's Package Manager, on the Package Detail pane where you select a version.

2 small breaking changes:

  • Merged AnswerShippingQuery method overloads. You'll need to add errorMessage: in your code to pass that argument and indicate failure.
  • The Poll.Type is now an enum PollType instead of string