Bot telegramu: webhook lub długie odpytywanie, secret_token i wdrożenie na serwerze bezserwerowym
Dwa sposoby otrzymywania aktualizacji
Bot API dostarcza wiadomości przychodzące na dwa wzajemnie wykluczające się sposoby:
- Długie odpytywanie - bot sam wywołuje
getUpdatesz parametremtimeout, Telegram utrzymuje żądanie otwarte do czasu pojawienia się aktualizacji. Potrzebny jest stale działający proces, porty przychodzące nie są potrzebne. - Webhook – Telegram wysyła każdą aktualizację z żądaniem POST na Twój adres HTTPS. Proces może nie działać cały czas, więc opcja jest bezserwerowa.
Nie działają one jednocześnie: po zainstalowaniu webhooka getUpdates zwraca błąd 409 Konflikt. Jest to częsty powód, dla którego „bot przestał odpowiadać”, gdy na serwerze w trybie odpytywania została uruchomiona lokalna kopia.
| | Długie odpytywanie | Webhook | |---|---|---| | Gdzie biegać | VPS, kontenerowy, lokalny | bezserwerowy, dowolny serwer HTTPS | | Adres publiczny | nie potrzebne | HTTPS na porcie 443, 80, 88 lub 8443 | | Rozwój | proste, działa dzięki NAT | potrzebuję tunelu do lokalnego debugowania | | Prosty proces | aktualizacje czekają w kolejce | Telegram powtarza dostawę |
W przypadku programowania i bota na jednym VPS, długie odpytywanie jest łatwiejsze. Do wdrożenia w Vercel, Cloudflare Workers lub w funkcji - tylko webhook.
Webhook z sekretnym tokenem
Adres URL webhooka nie może być uważany za tajemnicę. Bez weryfikacji każdy, kto ją rozpozna, wyśle fałszywą aktualizację w imieniu dowolnego użytkownika. Parametr secret_token podczas instalowania webhooka rozwiązuje ten problem: Telegram prześle go w nagłówku X-Telegram-Bot-Api-Secret-Token każdego żądania.
SECRET=$(openssl rand -hex 32) # допустимы A-Z, a-z, 0-9, _ и -, до 256 символов
curl -s "https://api.telegram.org/bot${BOT_TOKEN}/setWebhook" \
-d "url=https://example.com/api/telegram" \
-d "secret_token=${SECRET}" \
-d 'allowed_updates=["message","callback_query"]' \
-d "drop_pending_updates=true"allowed_updates ogranicza typy zdarzeń przychodzących do webhooka - mniej niepotrzebnych wywołań funkcji. drop_pending_updates wyrzuca nagromadzoną kolejkę, dzięki czemu bot po wdrożeniu nie odpowiada na setki starych wiadomości.
Obsługa w Next.js
[[VB_1_KOD]]
Dlaczego tak:
- Sekret jest sprawdzany najpierw i poprzez
timingSafeEqual. - Deduplikacja przez `update_id`. Jeżeli odpowiedź nie dotarła na czas lub nie została zwrócona 2xx, Telegram ponawia dostawę. Bez deduplikacji użytkownik otrzyma dwie odpowiedzi lub dwa utworzone zamówienia.
- Zawsze 200 po przetworzeniu, nawet jeśli wiadomość nie została rozpoznana. Błędny status spowoduje ponowne próby i zablokowanie kolejki aktualizacji.
- Token bota w adresie URL. Nie rejestruj pełnych adresów URL żądań do Bot API: token trafi do logów. W tym przykładzie rejestrowana jest tylko metoda i status.
Możesz także odpowiedzieć bezpośrednio w treści odpowiedzi webhooka, zwracając JSON z polem method (na przykład {"method":"sendMessage","chat_id":...,"text":"..."}). Oszczędza to jedno żądanie wychodzące, ale nie będziesz wiedzieć, czy wiadomość została dostarczona.
Funkcje bezserwerowe
- Czas wykonania. Jeśli przetwarzanie jest długie (wywołanie LLM, generowanie pliku), funkcja może nie spełniać limitu platformy, a Telegram uzna, że dostarczenie nie powiodło się. Szybko odpowiedz za pomocą 200 i przenieś pracę do kolejki lub zadania w tle i wyślij wynik poprzez
sendMessage. - Parallelizm. Parametr
max_connectionswsetWebhook(od 1 do 100, domyślnie 40) określa liczbę jednoczesnych żądań wysyłanych przez Telegram. Kolejność wiadomości od tego samego użytkownika nie jest gwarantowana podczas przetwarzania równoległego. Jeśli bot prowadzi dialog krok po kroku, zapisz stan w bazie danych i uwzględnij wyścigi. - Zimny start. Pierwsza wiadomość po czasie bezczynności jest przetwarzana wolniej. W przypadku botów jest to zwykle akceptowalne.
Diagnostyka
curl -s "https://api.telegram.org/bot${BOT_TOKEN}/getWebhookInfo"Odpowiedź zawiera pending_update_count (ile aktualizacji oczekuje na dostarczenie), last_error_date i last_error_message. Typowe błędy:
Wrong response from the webhook: 403 Forbidden- sekret w zmiennych środowiskowych nie jest zgodny z kluczem przekazanym dosetWebhook.SSL errorlubConnection refused- niedostępny adres lub certyfikat, któremu Telegram nie ufa.- Zwiększanie
pending_update_count- procedura obsługi odpowiada błędem lub skończył się czas.
Kiedy pozostać przy długim odpytywaniu
Jeśli bot działa na własnym serwerze, obciążenie jest niewielkie i nie chcesz publikować punktu końcowego HTTPS, długie odpytywanie jest niezawodne i proste. Biblioteki takie jak grammY i Telegraf obsługują oba tryby, a przejście zajmuje wtedy kilka linii.