Webhooks

With Webhook, your application gets notified automatically by Telegram when new updates arrive for your bot.

Your application will receive HTTP POST requests with an Update structure in the body, using specific JSON serialization settings Telegram.Bot.JsonBotAPI.Options.

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

ASP.NET Core with Controllers (MVC)

First you need to configure your Web App startup code:

• Locate the line services.AddControllers(); (in Program.cs or Startup.cs)
• If you're using .NET 6.0 or more recent, add the line:

  services.ConfigureTelegramBotMvc();
  

• For older .NET versions, add the line:

  services.ConfigureTelegramBot<Microsoft.AspNetCore.Mvc.JsonOptions>(opt => opt.JsonSerializerOptions);
  

Next, in a controller class (like BotController.cs), you need to add an action for the updates. Typically:

[HttpPost]
public async Task HandleUpdate([FromBody] Update update)
{
    // put your code to handle one Update here.
}

Good, now skip to SetWebHookAsync below

ASP.NET Core with Minimal APIs

First you need to configure your Web App startup code:

• Locate the line builder.Build(); (in Program.cs)
• Above it, insert the line:

  builder.Services.ConfigureTelegramBot<Microsoft.AspNetCore.Http.Json.JsonOptions>(opt => opt.SerializerOptions);
  

Next, you need to map an action for the updates. Typically:

app.MapPost("/bot", (Update update) => HandleUpdate(update));
...

async Task HandleUpdate(Update update)
{
    // put your code to handle one Update here.
}

Good, now skip to SetWebHookAsync below

Old ASP.NET 4.x support

For older .NET Framework usage, you may use the following code:

public async Task<IHttpActionResult> Post()
{
    Update update;
    using (var body = await Request.Content.ReadAsStreamAsync())
        update = System.Text.Json.JsonSerializer.Deserialize<Update>(body, JsonBotAPI.Options);
    await HandleUpdate(update);
    return Ok();
}

SetWebHookAsync

Your update handler code is ready, now you need to instruct Telegram to send updates to your URL, by running:

var bot = new TelegramBotClient("YOUR_BOT_TOKEN");
await bot.SetWebhookAsync("https://your.public.host:port/bot", allowedUpdates: []);

You can now deploy your app to your webapp host machine.

Note: If you decide to switch back to Long Polling, remember to call bot.DeleteWebhookAsync()

Common issues

• You need a supported certificate If your host doesn't provide one or you want to develop on your own machine, consider using ngrok: Useful step-by-step guide
• You must use HTTPS (TLS 1.2+), IPv4, and ports 443, 80, 88, or 8443
• Official webhook guide
• If your update handler throws an exception or takes too much time to return, Telegram will consider it a temporary failure and will RESEND the same update a bit later.
  You may want to prevent handling the same update.Id twice:

  if (update.Id <= LastUpdateId) return;
  LastUpdateId = update.Id;
  // your code to handle the Update here.
  

• Most web hostings will recycle your app after some HTTP inactivity (= stop your app and restart it on the next HTTP request)
  To prevent issues like this:
  • Search for an Always-On option with your host (usually not free)
  • Make sure your web app can be safely stopped (saved state) and restarted later (reloading state)
  • Make sure you don't have critical background code that needs to keep running at all time
  • Have a service like cron-job.org ping your webapp every 5 minutes to keep it active. (host will likely still recycle your app after a few days)
  • Host your app on a VPS machine rather than a webapp host.