|
4 | 4 |
|
5 | 5 | With Webhook, your web application gets notified [sequentially](#updates-are-posted-sequentially-to-your-webapp), automatically by Telegram when new updates arrive for your bot. |
6 | 6 |
|
7 | | -Your application will receive HTTP POST requests with an Update structure in the body, using specific JSON serialization settings `Telegram.Bot.JsonBotAPI.Options`. |
| 7 | +Your application will receive HTTP POST requests with an Update structure in the JSON body. |
8 | 8 |
|
9 | | -Below, you will find how to configure an **ASP.NET Core Web API** project to make it work with Telegram.Bot, either with Controllers or Minimal APIs |
| 9 | +> Since version 22.5 of the library, you no longer need to configure the JSON serialization settings for your WebApp in most cases. |
| 10 | +> But if necessary, refer to section **[Configure JSON serialization settings](#configure-json-serialization-settings)** below. |
10 | 11 |
|
11 | | -⚠️ IMPORTANT: This guide describes configuration for versions 21.* and later of the library _(based on System.Text.Json rather than NewtonsoftJson)_. If you're using older versions, [you should upgrade first](../../migrate/Version-21.x.md)! |
| 12 | +Here are example codes for handling updates, depending on the types of ASP.NET projects: |
12 | 13 |
|
13 | | -## ASP.NET Core with Controllers (MVC) |
14 | | -[](https://github.com/TelegramBots/Telegram.Bot.Examples/tree/master/Webhook.Controllers) |
15 | | - |
16 | | -First you need to configure your Web App startup code: |
17 | | -- Locate the line `services.AddControllers();` _(in Program.cs or Startup.cs)_ |
18 | | -- If you're using .NET 6.0 or more recent, add the line: |
| 14 | +* **ASP.NET Core with Controllers (MVC)** [](https://github.com/TelegramBots/Telegram.Bot.Examples/tree/master/Webhook.Controllers) |
19 | 15 | ```csharp |
20 | | - services.ConfigureTelegramBotMvc(); |
| 16 | + // Add this action in a controller class (like BotController.cs): |
| 17 | + [HttpPost] |
| 18 | + public async Task HandleUpdate([FromBody] Update update) |
| 19 | + { |
| 20 | + // put your code to handle one Update here. |
| 21 | + } |
21 | 22 | ``` |
22 | | -- For older .NET versions, add the line: |
| 23 | +* **ASP.NET Core with Minimal APIs** [](https://github.com/TelegramBots/Telegram.Bot.Examples/tree/master/Webhook.MinimalAPIs) |
23 | 24 | ```csharp |
24 | | - services.ConfigureTelegramBot<Microsoft.AspNetCore.Mvc.JsonOptions>(opt => opt.JsonSerializerOptions); |
25 | | - ``` |
26 | | - |
27 | | -Next, in a controller class (like BotController.cs), you need to add an action for the updates. Typically: |
28 | | -```csharp |
29 | | -[HttpPost] |
30 | | -public async Task HandleUpdate([FromBody] Update update) |
31 | | -{ |
32 | | - // put your code to handle one Update here. |
33 | | -} |
34 | | -``` |
35 | | - |
36 | | -Good, now skip to [SetWebHook](#setwebhook) below |
37 | | - |
38 | | -## ASP.NET Core with Minimal APIs |
39 | | -[](https://github.com/TelegramBots/Telegram.Bot.Examples/tree/master/Webhook.MinimalAPIs) |
| 25 | + app.MapPost("/bot", (Update update) => HandleUpdate(update)); |
| 26 | + ... |
40 | 27 |
|
41 | | -First you need to configure your Web App startup code: |
42 | | -- Locate the line `builder.Build();` _(in Program.cs)_ |
43 | | -- Above it, insert the line: |
| 28 | + async Task HandleUpdate(Update update) |
| 29 | + { |
| 30 | + // put your code to handle one Update here. |
| 31 | + } |
| 32 | + ``` |
| 33 | +* **Old ASP.NET 4.x support** |
44 | 34 | ```csharp |
45 | | - builder.Services.ConfigureTelegramBot<Microsoft.AspNetCore.Http.Json.JsonOptions>(opt => opt.SerializerOptions); |
| 35 | + public async Task<IHttpActionResult> Post() |
| 36 | + { |
| 37 | + Update update; |
| 38 | + using (var body = await Request.Content.ReadAsStreamAsync()) |
| 39 | + update = System.Text.Json.JsonSerializer.Deserialize<Update>(body, JsonBotAPI.Options); |
| 40 | + await HandleUpdate(update); |
| 41 | + return Ok(); |
| 42 | + } |
46 | 43 | ``` |
47 | 44 |
|
48 | | -Next, you need to map an action for the updates. Typically: |
49 | | -```csharp |
50 | | -app.MapPost("/bot", (Update update) => HandleUpdate(update)); |
51 | | -... |
52 | | - |
53 | | -async Task HandleUpdate(Update update) |
54 | | -{ |
55 | | - // put your code to handle one Update here. |
56 | | -} |
57 | | -``` |
58 | | - |
59 | | -Good, now skip to [SetWebHook](#setwebhook) below |
60 | | - |
61 | | -## Old ASP.NET 4.x support |
62 | | - |
63 | | -For older .NET Framework usage, you may use the following code: |
64 | | -```csharp |
65 | | -public async Task<IHttpActionResult> Post() |
66 | | -{ |
67 | | - Update update; |
68 | | - using (var body = await Request.Content.ReadAsStreamAsync()) |
69 | | - update = System.Text.Json.JsonSerializer.Deserialize<Update>(body, JsonBotAPI.Options); |
70 | | - await HandleUpdate(update); |
71 | | - return Ok(); |
72 | | -} |
73 | | -``` |
74 | | - |
75 | | -## SetWebHook |
76 | | -Your update handler code is ready, now you need to instruct Telegram to send updates to your URL, by running: |
| 45 | +Now that your update handler code is ready, you need to instruct Telegram to start sending updates to your URL, by running: |
77 | 46 | ```csharp |
78 | 47 | var bot = new TelegramBotClient("YOUR_BOT_TOKEN"); |
79 | 48 | await bot.SetWebhook("https://your.public.host:port/bot", allowedUpdates: []); |
80 | 49 | ``` |
81 | 50 |
|
82 | | -You can now deploy your app to your webapp host machine. |
| 51 | +Great! You can now deploy your app to your webapp host machine. |
83 | 52 |
|
84 | 53 | _Note: If you decide to switch back to [Long Polling](polling.md), remember to call `bot.DeleteWebhook()`_ |
85 | 54 |
|
| 55 | + |
86 | 56 | ## Common issues |
87 | 57 |
|
88 | 58 | - You need a [supported certificate](https://core.telegram.org/bots/faq#i-39m-having-problems-with-webhooks) |
@@ -118,3 +88,30 @@ Initially Telegram will resend the failed update quickly, then with increasing i |
118 | 88 |
|
119 | 89 | If you need to process the incoming updates faster, in parallel, you will want to delegate their handling separately and acknowledge the POST request by returning from the controller immediately. |
120 | 90 | For more details, refer to [this section of our documentation](.#sequential-vs-parallel-updates). |
| 91 | + |
| 92 | + |
| 93 | +## Configure JSON serialization settings |
| 94 | + |
| 95 | +Telegram updates & requests are sent using JSON payloads with `snake_case` property names. |
| 96 | +Such serialization is normally achieved thanks to `Telegram.Bot.JsonBotAPI.Options` serialization settings. |
| 97 | + |
| 98 | +Since version 22.5, the library should already be compatible with Telegram Webhook without needing extra configuration for your WebApp. |
| 99 | + |
| 100 | +In some rare cases _(like [Native AOT](https://learn.microsoft.com/en-us/dotnet/core/deploying/native-aot) / [Blazor](https://learn.microsoft.com/en-us/aspnet/core/blazor/webassembly-build-tools-and-aot) / [Trimming](https://learn.microsoft.com/en-us/dotnet/core/deploying/trimming/trim-self-contained))_, this might still be necessary and here is how to configure your project: |
| 101 | +* **ASP.NET Core with Minimal APIs** |
| 102 | + Locate the line `builder.Build();` _(in Program.cs)_ and insert this line <u>above</u>: |
| 103 | + ```csharp |
| 104 | + builder.Services.ConfigureTelegramBot<Microsoft.AspNetCore.Http.Json.JsonOptions>(opt => opt.SerializerOptions); |
| 105 | + ``` |
| 106 | +* **ASP.NET Core with Controllers** _(recommended method for .NET 6.0+)_ |
| 107 | + Add the [nuget package](https://www.nuget.org/packages/Telegram.Bot.AspNetCore) `Telegram.Bot.AspNetCore` to your project. |
| 108 | + Locate the line `services.AddControllers();` _(in Program.cs or Startup.cs)_ and add this line below: |
| 109 | + ```csharp |
| 110 | + services.ConfigureTelegramBotMvc(); |
| 111 | + ``` |
| 112 | +* **ASP.NET Core with Controllers** _(any .NET version)_ |
| 113 | + Locate the line `services.AddControllers();` _(in Program.cs or Startup.cs)_ and add this line below: |
| 114 | + ```csharp |
| 115 | + services.ConfigureTelegramBot<Microsoft.AspNetCore.Mvc.JsonOptions>(opt => opt.JsonSerializerOptions); |
| 116 | + ``` |
| 117 | + |
0 commit comments