Testowanie webhooka bota Telegram na localhost

Aby przetestować webhook bota Telegramu na hoście lokalnym, udostępnij swój lokalny serwer za pomocą publicznego tunelu HTTPS, wywołaj setWebhook z tym adresem URL i sprawdź nagłówek tajnego tokena Telegramu przy każdym żądaniu. Daje to prawdziwą wiadomość, zapytanie zwrotne i członkostwo aktualizacje bez wdrażania po każdej zmianie kodu. Pełna pętla wygląda następująco: uruchom moduł obsługi bota, uruchom npx portpreview 3000, zarejestruj wynikowy adres URL, wyślij botowi wiadomość i sprawdź żądanie lokalnie.

Dlaczego Telegram nie może wysyłać aktualizacji bezpośrednio do hosta lokalnego

Interfejs API botów aplikacji Telegram wysyła aktualizacje webhooków z infrastruktury Telegramu na dostępny w Internecie adres URL. localhost, 127.0.0.1 i prywatne adresy LAN nie mogą być routowane z tej infrastruktury. Tunel hosta lokalnego kończy protokół HTTPS pod adresem publicznym i przekazuje niezmienione żądanie HTTP do portu lokalnego.

Boty Telegramu mogą otrzymywać aktualizacje na dwa wzajemnie wykluczające się sposoby: długie odpytywanie przez getUpdates lub webhooki. Oficjalne odwołanie setWebhook stwierdza, że ​​getUpdates jest niedostępne, gdy skonfigurowany jest wychodzący webhook. Jeśli proces odpytywania nadal trwa, zatrzymaj go przed oceną przepływu elementu webhook.

Utwórz lokalny punkt końcowy webhooka

W tym przykładzie Express program obsługi jest celowo mały. Sprawdza wspólny sekret przed dotknięciem aktualizacji, szybko potwierdza i przenosi pracę poza ścieżkę odpowiedzi.

import express from 'express';
import crypto from 'node:crypto';

const app = express();
app.use(express.json({ limit: '1mb' }));

function sameSecret(received = '', expected = '') {
  const a = Buffer.from(received);
  const b = Buffer.from(expected);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

app.post('/webhooks/telegram', (req, res) => {
  const received = req.get('x-telegram-bot-api-secret-token') || '';
  if (!sameSecret(received, process.env.TELEGRAM_WEBHOOK_SECRET)) {
    return res.sendStatus(401);
  }

  const update = req.body;
  res.sendStatus(200);
  queueMicrotask(() => handleUpdate(update));
});

app.listen(3000, () => console.log('Listening on http://localhost:3000'));

Telegram wysyła serializowany w formacie JSON Update. W przeciwieństwie do dostawców opartych na HMAC, funkcja secret_token Telegramu nie podpisuje treści. Umieszcza wybraną wartość w X-Telegram-Bot-Api-Secret-Token. Token potwierdza, że ​​nadawca zna wartość użytą podczas rejestracji webhooka, ale nie zapewnia podsumowania ładunku. TLS chroni żądanie podczas przesyłania.

Udostępnij punkt końcowy za pomocą protokołu HTTPS

1. Uruchom aplikację i potwierdź, że curl -i http://localhost:3000/webhooks/telegram dotrze do serwera, nawet jeśli GET zwróci 404.
2. Otwórz drugi terminal i uruchom npx portpreview 3000.
3. Skopiuj publiczne źródło HTTPS i dołącz /webhooks/telegram.
4. Utrzymaj proces tunelowania, podczas gdy Telegram dostarcza aktualizacje.

Interfejs API botów akceptuje adresy URL webhook HTTPS. Telegram dokumentuje obsługę webhooka na portach 443, 80, 88 i 8443; publiczny punkt końcowy zarządzanego tunelu zwykle używa numeru 443, nawet jeśli przekazywany proces lokalny nasłuchuje na numerze 3000.

Zarejestruj bezpiecznie webhook Telegramu

Utwórz losowy klucz tajny zawierający wyłącznie litery, cyfry, podkreślenia i łączniki. Telegram dopuszcza 1–256 znaków. Nie używaj ponownie tokena bota jako tej wartości.

export TELEGRAM_WEBHOOK_SECRET="$(openssl rand -hex 32)"

curl -sS -X POST \
  "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/setWebhook" \
  -d "url=https://YOUR-TUNNEL.portpreview.dev/webhooks/telegram" \
  -d "secret_token=${TELEGRAM_WEBHOOK_SECRET}" \
  -d 'allowed_updates=["message","callback_query"]' \
  -d "drop_pending_updates=true"

allowed_updates redukuje hałas i powinien wyświetlać tylko typy aktualizacji obsługiwane przez bota. drop_pending_updates=true jest przydatny podczas rozpoczynania nowej sesji lokalnej, ale trwale odrzuca aktualizacje oczekujące w kolejce, więc pomiń go, gdy te zdarzenia mają znaczenie. Dokumentacja aktualizacji Telegramu opisuje pola takie jak message, callback_query i my_chat_member.

Potwierdź rejestrację przed debugowaniem kodu

Użyj getWebhookInfo, aby oddzielić błędy konfiguracji od błędów obsługi:

curl -sS "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getWebhookInfo"

Sprawdź url, pending_update_count, last_error_message i last_error_date. Pusty adres URL oznacza, że ​​rejestracja nie została zapisana. Rosnąca liczba oczekujących połączeń zwykle oznacza, że ​​Telegram nie może się połączyć lub punkt końcowy zwraca stan inny niż 2xx. Wyślij bezpośrednią wiadomość do bota po rejestracji; samo otwarcie czatu niekoniecznie powoduje utworzenie aktualizacji.

Obsługuj aktualizacje bez powodowania ponownych prób

Potwierdź przed powolną pracą

Zwróć odpowiedź 2xx, gdy tylko żądanie zostanie uwierzytelnione i trwale zaakceptowane. Eksporty baz danych, wywołania AI i interfejsy API innych firm powinny działać asynchronicznie. Telegram ponawia nieudane żądania po odpowiedziach innych niż 2xx, więc powolna praca synchroniczna może powodować powstawanie duplikatów.

Deduplikuj za pomocą update_id

Każda aktualizacja ma update_id. Przechowuj przetworzone identyfikatory z okresem ważności lub wymuszaj unikalny klucz bazy danych. W ponownej próbie nie można wysłać drugiego potwierdzenia płatności, utworzyć duplikatu biletu ani dwukrotnie wykonać tego samego wywołania zwrotnego.

Modeluj jawnie każdy typ aktualizacji

Nie każda aktualizacja zawiera message.text. Przyciski wywołania zwrotnego pojawiają się pod callback_query; posty na kanałach i zmiany członkostwa mają inne pola. Rozgałęziaj się na obecnym polu najwyższego poziomu i traktuj nieznane typy jako prawidłowe, zamiast rzucać.

Zasady bezpieczeństwa dotyczące testowania lokalnego bota Telegramu

• Najpierw sprawdź poprawność tajnego nagłówka. Odrzuć brakujące lub nieprawidłowe wartości przed zarejestrowaniem lub analizowaniem wrażliwych pól.
• Trzymaj tokeny z dala od adresów URL i dzienników. Token API bota w poleceniu rejestracji jest poświadczeniem. Unikaj historii powłoki w systemach współdzielonych i obracaj odsłonięty token za pośrednictwem BotFather.
• Użyj nieodgadnionej trasy i sekretu. Trasa to głęboka obrona; tajny nagłówek to faktyczna kontrola aplikacji.
• Ogranicz przechwytywane dane. Wiadomości mogą zawierać nazwiska, nazwy użytkowników, numery telefonów, pliki i tekst prywatnej rozmowy. Po zakończeniu zredaguj dzienniki i usuń lokalne przechwytywania.
• Nigdy nie wyłączaj uwierzytelniania w trakcie programowania. Tunel publiczny jest publiczny. Kod lokalny powinien przeprowadzać te same kontrole co produkcja.

Zapoznaj się z szerszym przewodnikiem dotyczącym bezpieczeństwa tunelu hosta lokalnego, aby zapoznać się z praktykami kontroli dostępu i przechowywania danych.

Rozwiązywanie typowych błędów webhooka Telegramu

Telegram zgłasza błąd certyfikatu lub połączenia

Użyj adresu URL HTTPS tunelu, a nie jego lokalnego celu HTTP. Upewnij się, że tunel jest aktywny i adres URL się nie zmienił. Jeśli zamiast tego podasz własny certyfikat z podpisem własnym, Telegram wymaga przesłania certyfikatu publicznego w postaci pliku; zarządzany punkt końcowy TLS pozwala uniknąć tej konfiguracji.

Punkt końcowy zwraca 401

Porównaj sekret przekazany do setWebhook ze zmienną środowiskową używaną przez proces. W nazwach nagłówków wielkość liter nie jest rozróżniana, ale serwery proxy lub oprogramowanie pośredniczące mogą usuwać niestandardowe nagłówki. Sprawdź przychodzące nagłówki bez drukowania tajnej wartości.

Nie nadeszły żadne żądania

Uruchom getWebhookInfo, sprawdź, czy zarejestrowana ścieżka dokładnie odpowiada Twojej trasie i upewnij się, że żadna zapora sieciowa nie blokuje lokalnego połączenia tunelu. Jeśli niedawno korzystałeś z odpytywania, upewnij się, że adres URL elementu webhook jest teraz wypełniony. Uruchom aktualną aktualizację, wysyłając wiadomość do bota.

Aktualizacje pojawiają się wielokrotnie

Status dziennika i czas odpowiedzi. Wyjątki po otrzymaniu żądania mogą zamienić zamierzone 200 w 500. Zwróć natychmiast 200, ustaw przetwarzanie jako idempotentne i użyj kontrolowanego odtwarzania webhooka zamiast czekać na ponowne próby dostawcy podczas debugowania.

Testuj zapytania i pliki wywołania zwrotnego, nie tylko tekst

Przydatna macierz testów botów obejmuje więcej niż message.text. Wyślij zdjęcie z podpisem, udostępnij kontakt, edytuj wiadomość i naciśnij przycisk na klawiaturze wbudowanej. W przypadku zapytań zwrotnych zadzwoń natychmiast pod numer answerCallbackQuery, aby klient przestał wyświetlać wskaźnik postępu, a następnie wykonaj wolniejszą pracę osobno. Aktualizacje plików zawierają identyfikatory; pobieranie bajtów jest drugą operacją Bot API i nie powinno opóźniać odpowiedzi webhooka.

Przechowuj osprzęt wykonany z oczyszczonych aktualizacji na potrzeby testów jednostkowych, ale zachowaj pełną ścieżkę transportową dla co najmniej jednego testu każdego obsługiwanego typu. Urządzenie potwierdza, że ​​Twój dyspozytor rozumie ładunek; prawdziwe dostarczanie tunelowane potwierdza również rejestrację, TLS, nagłówki, analizę treści i zachowanie potwierdzające. Dodając nowy wpis allowed_updates, wywołaj ponownie setWebhook i sprawdź, czy getWebhookInfo odzwierciedla zamierzoną konfigurację.

Usuń webhook po sesji lokalnej

curl -sS -X POST \
  "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/deleteWebhook" \
  -d "drop_pending_updates=false"

Usunięcie webhooka umożliwia powrót do getUpdates. Jeśli adres URL tunelu zmieni się w następnej sesji, zadzwoń ponownie pod numer setWebhook. Aby uzyskać dodatkową diagnostykę, postępuj zgodnie z ogólnym przebiegiem debugowania lokalnego webhooka.