Получение обновлений

Бот получает входящие сообщения, нажатия кнопок и другие события как объекты Update. Есть два взаимоисключающих способа: long polling через getUpdates и вебхук через setWebhook.

Long polling

Самый простой вариант, не требует публичного адреса. Бот в цикле вызывает getUpdates с параметром timeout: сервер держит запрос открытым, пока не появятся обновления.

Shell

curl "https://api.staticgram.top/bot$TOKEN/getUpdates?timeout=30&offset=0"

offset: передавайте update_id последнего обработанного обновления + 1, тогда предыдущие считаются подтверждёнными. Отрицательный offset (до -10000) возвращает хвост очереди.
limit: от 1 до 100 (по умолчанию 100).
timeout: от 0 до 50 секунд.
allowed_updates: список типов обновлений. Значение сохраняется для следующих вызовов. Пустой список означает набор по умолчанию; chat_member, message_reaction и message_reaction_count приходят только если указаны явно.

Один получатель

Одновременно может работать только один вызов getUpdates на бота. Второй параллельный запрос получит 409 Conflict. Пока установлен вебхук, getUpdates тоже возвращает 409: удалите вебхук через deleteWebhook.

Вебхуки

Сервер StaticGram сам отправляет каждое обновление POST-запросом с JSON-телом на ваш адрес.

Shell

curl "https://api.staticgram.top/bot$TOKEN/setWebhook" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://bot.example.com/webhook",
    "secret_token": "s3cr3t_value",
    "allowed_updates": ["message", "callback_query"],
    "drop_pending_updates": true
  }'

url: HTTPS или HTTP, любой порт. Self-signed сертификаты не поддерживаются: параметр certificate принимается, но игнорируется, доставка проверяет сертификат по системному хранилищу.
secret_token: 1-256 символов A-Z a-z 0-9 _ -. Приходит в заголовке X-Telegram-Bot-Api-Secret-Token; проверяйте его, чтобы отсекать чужие запросы.
max_connections: 1-100, по умолчанию 40.
ip_address: проверяется на корректность и игнорируется.

Если ваш сервер не ответил кодом 2xx, доставка повторяется. Состояние очереди и последняя ошибка видны в getWebhookInfo.

Пример приёма вебхука на aiogram 3:

Python

from aiohttp import web
from aiogram.webhook.aiohttp_server import SimpleRequestHandler, setup_application

WEBHOOK_PATH = "/webhook"
SECRET = "s3cr3t_value"


async def on_startup(bot):
    await bot.set_webhook("https://bot.example.com" + WEBHOOK_PATH, secret_token=SECRET)

dp.startup.register(on_startup)
app = web.Application()
SimpleRequestHandler(dispatcher=dp, bot=bot, secret_token=SECRET).register(app, path=WEBHOOK_PATH)
setup_application(app, dp, bot=bot)
web.run_app(app, port=8080)

Какие обновления приходят

Сервер формирует message, edited_message, channel_post, edited_channel_post, callback_query, inline_query, chosen_inline_result, poll, poll_answer, my_chat_member, chat_member, chat_join_request, pre_checkout_query, purchased_paid_media, message_reaction, chat_boost, removed_chat_boost, бизнес-обновления (business_connection, business_message, edited_business_message, deleted_business_messages) и managed_bot.

shipping_query не приходит никогда: счета в звёздах не бывают с доставкой. Гостевые запросы (guest_message) сервер не формирует.

Порядок получения обновлений и подтверждение через offset описаны в официальной документации: Making requests when getting updates.