Webhook¶

Polling needs a process that runs forever and adds a round trip of latency. The alternative is to let Telegram post each update to a URL you serve.

Both are supported the same way, and one setting says which one this deployment uses:

TELEGRAM_BOT = {'MODE': 'webhook'}  # or 'polling', the default

Scalars can come from the environment, so the choice can be made at startup without touching code — set it where the process is started, which for the compose recipe on Deployment is the service's own environment::

  telegram_bot:
    command: python manage.py start_tgbot
    environment:
      DJANGO_AIOGRAM_MODE: webhook

In a shell it needs exporting: a bare assignment sets a variable in that shell and does not pass it to anything it starts, so the command below would read the setting from your settings module and not from the line above it:

export DJANGO_AIOGRAM_MODE=webhook
python manage.py start_tgbot

start_tgbot prints which mode it is running in, honours --mode for a single run, and the view refuses to serve while the mode is polling — two sources of updates at once means no way to tell which one handled what.

Polling is the default because it needs nothing but an outbound connection. Reach for a webhook when the delay matters, or when an inbound HTTP endpoint is easier to run than a process that calls Telegram in a loop.

It does not remove the need for a long-running process. Only inbound polling goes away: a send from a web or worker process still goes onto the broker, and something has to consume it — which is start_tgbot, the same process that would have polled. (Inside that process bot.send() calls Telegram directly and queues nothing.) Webhook mode is not a route to serverless.

Webhooks are also not always possible — a public HTTPS endpoint with a valid certificate is a hard requirement, and plenty of deployments cannot offer one. Nothing here pushes you towards them.

What changes¶

	Polling	Webhook
Who receives updates	the `start_tgbot` container	whichever process serves the URL, normally web
Where handlers run	that container	in a request thread of your web server
Public HTTPS needed	no	yes, Telegram refuses plain HTTP
Outbound queue	consumed by the same container	still needs a consumer somewhere

The last row is the one that catches people. Inbound updates and outbound bot.send() calls are unrelated: the queue still needs a worker, and in webhook mode that worker no longer polls.

Setting it up¶

1. Configure it.

# settings.py
import os

TELEGRAM_BOT = {
    'TOKEN': os.environ['TELEGRAM_BOT_TOKEN'],
    'REDIS_URL': os.environ['REDIS_URL'],
    'MODE': 'webhook',
    'WEBHOOK_URL': 'https://example.com/tg/9c1f2b7a/',
    'WEBHOOK_SECRET': os.environ['TELEGRAM_WEBHOOK_SECRET'],
}

MODE set to webhook without a URL is check error E027: half-configured, the bot would receive nothing and say nothing about it.

The secret is not optional: the view refuses to run without one, and manage.py check reports E027. Telegram echoes it back in the X-Telegram-Bot-Api-Secret-Token header, and the view compares it with hmac.compare_digest. Give the path an unguessable segment too — that is one less thing scanning the internet will find.

2. Serve the view.

# urls.py
from django.urls import path

from django_aiogram.consumer.webhook import telegram_webhook

urlpatterns = [
    path('tg/9c1f2b7a/', telegram_webhook),
]

It is CSRF-exempt, accepts POST only, and is a plain synchronous view — which is deliberate. An async view runs on the server's loop under ASGI but on a throwaway loop per request under WSGI, and the bot's HTTP session binds to the first loop that uses it. Driving the bot's own loop behaves the same either way.

3. Register it with Telegram.

python manage.py tgbot_webhook set
python manage.py tgbot_webhook info

Telegram remembers the URL, not your settings file. info prints the pending count and the last delivery error, which is the first thing to look at when updates stop arriving.

4. Run a worker for the queue.

python manage.py start_tgbot

In webhook mode the same command consumes the queue and never calls getUpdates. Skipping it means bot.send() from your app queues messages nobody delivers.

--mode polling and --mode webhook override the setting for one run, which is what you want when trying the other mode without editing anything. It changes this process only — the view reads the setting — so the command warns when the two disagree and says what will happen: a webhook worker whose setting says polling gets no updates, because the view refuses them, and polling while a webhook is registered fails at getUpdates. For a real switch, change MODE (or DJANGO_AIOGRAM_MODE) everywhere.

Going back to polling¶

python manage.py tgbot_webhook delete
python manage.py start_tgbot --mode polling

getUpdates refuses to run while a webhook is registered, so polling will not start until the webhook is deleted. Set MODE back to 'polling' once you have decided to stay there — tgbot_webhook set warns when you register a webhook that the configured mode will not use.

What to watch out for¶

Handlers run in your web workers. A handler that blocks holds a request worker for as long as it takes. That is fine for a reply and wrong for a job that takes a minute — queue that work instead.

FSM state must be shared. With several web workers, the update that starts a dialogue and the one that continues it land in different processes. FSM_STORAGE: 'redis' is the default and it is what makes that work; 'memory' cannot.

Telegram retries a non-2xx. The view answers 200 even when a handler raised, because a handler that failed once will fail the same way on redelivery — that is a loop, not a retry. Failures are logged; see Logging.

It answers 503 for the other case: an update that was refused rather than handled, because nothing ran it. Shutting down is one reason; a loop already closed by an earlier close() is another, and that one used to answer 200 — so the update was lost and Telegram was told not to try again. There redelivery is the point — during a rolling restart it is the difference between the update moving to the next instance and disappearing into a 200 nobody acted on.

What a POST gets back: 200 handled, or a handler raised; 503 refused, so redeliver; 403 the secret does not match — the comparison is on bytes, so a secret outside ASCII is compared like any other and a matching one passes; 400 the body is not an update Telegram could have sent. Anything that is not a POST gets 405.

All five reasons for a 503, in the order the view checks them: ENABLED is off in this process; the configuration cannot be read, which is one refusal reached at two points — an unknown MODE before the next check, and an empty WEBHOOK_SECRET after it, because a polling deployment has no reason to set one; MODE is not webhook, so a worker is polling and two sources of updates would be one too many; building the bot raised ImproperlyConfigured, most often a TOKEN that is missing or malformed; and nothing ran the update — the process is shutting down, its loop is closed, or the loop's own thread had not started yet.

Updates are not queued at all. They go straight from the request to the dispatcher, whichever transport is configured: the broker carries outbound messages only, in both modes.

Health¶

The healthcheck reads the consumer's heartbeat — python -m django_aiogram.healthcheck in a container, manage.py tgbot_healthcheck by hand — so in webhook mode it answers for the start_tgbot worker rather than for the web process: the worker still runs the queue consumer, it just does not poll. Do not point it at the web service, which writes no heartbeat and would read unhealthy for ever. See Deployment.