How to Build and Deploy a python-telegram-bot v20 Webhook
The python-telegram-bot v20 release introduced major structural changes. According to the documentation,
“All networking and I/O-related logic now works via coroutine functions (i.e.
async def ...functions). In particular, all methods of the
telegram.Botclass that make requests to the Bot API are now coroutine functions and need to be
await-ed.” — python-telegram-bot v20 change logs
The process of transitioning from python-telegram-bot version 13 to version 20 turned out to be more complex than I had originally anticipated. Converting synchronous
def functions to
async def and adding
await to new coroutines was fairly easy. But the main difficulty was finding detailed documentation on how to build and deploy python-telegram-bot v20 webhooks in a production setting.
This article explains why and how I migrated from:
- python-telegram-bot v13 → v20
- Flask → FastAPI
- Gunicorn → Gunicorn + Uvicorn
Why Upgrade from v13 to v20?
v13.x and older are no longer supported by the python-telegram-bot dev team. If Telegram API introduces any new features, they will only be available on v20 and above.
Why Use a Webhook and Not Polling?
Most examples provided by the python-telegram-bot dev team use
Application.run_polling. But webhooks are generally recommended over polling for most Telegram bot use cases, because polling requires your bot to constantly make requests to Telegram’s servers, which can consume significant resources. On the other hand, webhooks offer extended functionality, update faster, and scale better.
The Challenge of using Flask with python-telegram-bot v20
Using a WGSI like Flask with python-telegram-bot v20 is awkward.
Flask, a WSGI (Web Server Gateway Interface), is synchronous and can handle only one request at a time. But you can still run async functions in Flask using
asyncio.run(), as in the custom webhook bot example provided by the python-telegram-bot dev team.
asyncio.run() starts an event loop and executes the given coroutine until it completes. If there are any asynchronous tasks running before or after the request is handled, those tasks will be executed in a separate event loop.
# Code snippet from https://docs.python-telegram-bot.org/en/v20.6/examples.customwebhookbot.html webserver = uvicorn.Server( config=uvicorn.Config( app=WsgiToAsgi(flask_app), port=PORT, use_colors=False, host="127.0.0.1", ) ) async with application: await application.start() await webserver.serve() # start bot's webserver await application.stop()
However, this implementation is slightly awkward because Flask is intrinsically incompatible with async globals.
Examples in the documentation are not suitable for production environments.
asyncio.run() as an entry point in production is usually not recommended. The
asyncio.run() function is designed for development and testing purposes, and it may not provide the same level of robustness and reliability as production servers like Gunicorn or UWSGI.
These production servers offer many additional features, such as logging, monitoring, and health checks, which are essential for ensuring the stability and security of a production application.
If you want to deploy your bot in production, it’s much cleaner to use an ASGI (Asynchronous Server Gateway Interface) with an ASGI web server implementation.
How to Do It — Migration and Deployment
From Flask (WSGI) to FastAPI (AGSI)
Migrating a Flask application to an ASGI is straightforward. I chose FastAPI because I found a comprehensive migration tutorial here. The syntaxes of both frameworks are quite similar, which means you won’t have to make too many code changes.
# From python-telegram-bot v20 application = ( Application.builder() .updater(None) .token(<your-bot-token>) # replace <your-bot-token> .read_timeout(7) .get_updates_read_timeout(42) .build() ) # From FastAPI @asynccontextmanager async def lifespan(app: FastAPI): async with application: await application.start() yield await application.stop()
Quart appears to be a feasible alternative, but it does not offer support for deployments using Uvicorn, which is the webserver implementation I was adapting from the script provided by the python-telegram-bot team.
A working example
The following code shows a minimal example that uses FastAPI to build a python-telegram-bot v20 webhook. This bot will respond with “starting…” when it receives the
# main.py from contextlib import asynccontextmanager from http import HTTPStatus from telegram import Update from telegram.ext import Application, CommandHandler from telegram.ext._contexttypes import ContextTypes from fastapi import FastAPI, Request, Response # Initialize python telegram bot ptb = ( Application.builder() .updater(None) .token(<your-bot-token>) # replace <your-bot-token> .read_timeout(7) .get_updates_read_timeout(42) .build() ) @asynccontextmanager async def lifespan(_: FastAPI): await ptb.bot.setWebhook(<your-webhook-url>) # replace <your-webhook-url> async with ptb: await ptb.start() yield await ptb.stop() # Initialize FastAPI app (similar to Flask) app = FastAPI(lifespan=lifespan) @app.post("/") async def process_update(request: Request): req = await request.json() update = Update.de_json(req, ptb.bot) await ptb.process_update(update) return Response(status_code=HTTPStatus.OK) # Example handler async def start(update, _: ContextTypes.DEFAULT_TYPE): """Send a message when the command /start is issued.""" await update.message.reply_text("starting...") ptb.add_handler(CommandHandler("start", start))
To start the bot, pip install all required dependencies and run the start command:
gunicorn main:app -k uvicorn.workers.UvicornWorker.
This code snippet is adapted from a real Telegram bot in production. Check out the source code for @cron_telebot here to see how it is implemented. Feel free to adapt the script to suit your use case.
In this article, we learnt how to build and deploy a python-telegram-bot v20 webhook.
Hope this tutorial helped you. If you enjoyed this article, please follow me on Medium to show your support.
Thank you for reading!