Czego szukasz?

Wpisz temat, narzędzie lub problem do rozwiązania.

← Wszystkie artykuły

Jak wysyłać powiadomienia z serwera na Telegram

Niebieska linia łączy panel serwera z telefonem pokazującym pusty alert z dzwonkiem.

Backup może zakończyć się błędem, mimo że zadanie w harmonogramie uruchomiło się punktualnie. Krótki alert na telefonie pozwala zauważyć problem bez regularnego zaglądania do logów. Powiadomienia z serwera na Telegram można wysyłać zwykłym żądaniem HTTPS, bez instalowania komunikatora na VPS-ie.

Zbudujemy małego nadawcę w Pythonie 3. Token będzie zapisany poza kodem, tekst trafi do skryptu przez standardowe wejście, a błąd wysyłki da niezerowy kod zakończenia. Przykład dotyczy własnego bota i prywatnej rozmowy, nie wysyłania wiadomości do przypadkowych odbiorców.

Jak działa taki alert

Skrypt na serwerze wywołuje metodę sendMessage w Telegram Bot API. Telegram przyjmuje wiadomość i udostępnia ją wskazanej rozmowie. Do wysyłania potrzebujesz dwóch wartości: tokenu bota oraz identyfikatora chat_id.

Nie musisz otwierać portu przychodzącego na VPS-ie. Nadawca wykonuje połączenie wychodzące HTTPS. W tym wariancie nie tworzymy endpointu webhooka i nie odbieramy poleceń administracyjnych z telefonu.

Rozdziel trzy etapy: wykrycie problemu, przygotowanie krótkiej treści oraz dostarczenie alertu. Dzięki temu później wymienisz kanał powiadomień bez przepisywania całego skryptu backupu. Jeśli HTTP i JSON są nowe, zacznij od wprowadzenia do REST API.

1. Utwórz osobnego bota

W Telegramie otwórz oficjalnego @BotFather, sprawdź nazwę konta i użyj /newbot. Nadaj botowi nazwę oraz unikalną nazwę użytkownika zgodnie z instrukcjami. Otrzymany token pozwala wykonywać operacje w imieniu bota.

Następnie otwórz prywatną rozmowę z nowym botem i wyślij /start. To użytkownik inicjuje taką rozmowę. Samo poznanie czyjejś nazwy użytkownika nie daje botowi prawa do rozpoczęcia prywatnej konwersacji.

Do ćwiczenia użyj nowego bota, którego nie obsługuje już inna aplikacja. Odczytywanie aktualizacji przez dwa procesy może utrudniać diagnozę. Jeśli istniejący bot korzysta z webhooka, getUpdates nie będzie działać równolegle. Nie usuwaj cudzej konfiguracji webhooka, aby wykonać przykład.

2. Zapisz token poza skryptem

Na serwerze, jako użytkownik wykonujący późniejsze zadanie, przygotuj prywatny katalog:

install -d -m 700 "$HOME/.config/tt-telegram"
install -m 600 /dev/null "$HOME/.config/tt-telegram/config.json"
nano "$HOME/.config/tt-telegram/config.json"

Polecenie install tworzące plik wykonaj tylko przy pierwszej konfiguracji, ponieważ zastąpi jego wcześniejszą zawartość. W edytorze wpisz:

{
  "token": "TUTAJ_TOKEN_OD_BOTFATHER",
  "chat_id": 0
}

Na tym etapie chat_id jest wartością tymczasową. Nie uruchamiaj jeszcze wysyłania. Nie zapisuj tokenu w repozytorium, parametrze crona ani wprost w komendzie w historii powłoki.

Uprawnienia 600 pozwalają czytać i zapisywać plik właścicielowi. Nie ukrywają go jednak przed administratorem systemu. Jeśli bot działa na współdzielonym serwerze, uwzględnij to w modelu dostępu. Podstawy uprawnień sprawdzisz w kalkulatorze chmod oraz poradniku Permission denied.

3. Przygotuj nadawcę w Pythonie

Zapisz kod jako telegram_notify.py, na przykład w katalogu ~/bin. Korzysta wyłącznie z biblioteki standardowej Pythona 3. Wysyła zwykły tekst, bez trybu Markdown i HTML, dzięki czemu znaki z komunikatu błędu nie zmieniają formatowania wiadomości.

#!/usr/bin/env python3
import argparse
import json
import os
from pathlib import Path
import stat
import sys
import urllib.error
import urllib.request


def api_call(token, method, payload):
    request = urllib.request.Request(
        f"https://api.telegram.org/bot{token}/{method}",
        data=json.dumps(payload).encode("utf-8"),
        headers={"Content-Type": "application/json"},
        method="POST",
    )
    status = 200
    try:
        with urllib.request.urlopen(request, timeout=20) as response:
            raw = response.read(1_000_000)
    except urllib.error.HTTPError as error:
        status = error.code
        raw = error.read(1_000_000)
        error.close()
    except (urllib.error.URLError, TimeoutError, OSError):
        raise RuntimeError("Blad sieci lub timeout. Dostarczenie niepewne.") from None
    try:
        result = json.loads(raw)
    except (ValueError, UnicodeError):
        raise RuntimeError("Odpowiedz nie jest poprawnym JSON-em.") from None
    if not isinstance(result, dict):
        raise RuntimeError("Nieoczekiwany format odpowiedzi.")
    if status >= 400 or result.get("ok") is not True:
        code = result.get("error_code", status)
        delay = result.get("parameters", {}).get("retry_after")
        suffix = f" Poczekaj co najmniej {delay} s." if isinstance(delay, int) else ""
        raise RuntimeError(f"Telegram odrzucil zadanie, kod {code}.{suffix}")
    return result["result"]


def main():
    parser = argparse.ArgumentParser()
    parser.add_argument("--config", type=Path,
                        default=Path.home() / ".config/tt-telegram/config.json")
    parser.add_argument("--discover", action="store_true")
    args = parser.parse_args()
    try:
        if os.name == "posix" and stat.S_IMODE(args.config.stat().st_mode) & 0o077:
            raise RuntimeError("Ustaw uprawnienia 600 dla pliku konfiguracji.")
        config = json.loads(args.config.read_text(encoding="utf-8"))
        token = config["token"]
        if not isinstance(token, str) or ":" not in token:
            raise RuntimeError("Brak poprawnego tokenu w konfiguracji.")
        if args.discover:
            updates = api_call(token, "getUpdates", {"timeout": 0, "limit": 20})
            chats = {u["message"]["chat"]["id"] for u in updates if "message" in u}
            print("chat_id:", ", ".join(str(x) for x in sorted(chats)) or "brak")
            return 0
        text = sys.stdin.read(16001).strip()
        if not text or len(text.encode("utf-16-le")) // 2 > 4000:
            raise RuntimeError("Podaj wiadomosc o dlugosci 1-4000 jednostek UTF-16.")
        api_call(token, "sendMessage", {"chat_id": config["chat_id"], "text": text})
        print("Telegram potwierdzil przyjecie wiadomosci.")
        return 0
    except RuntimeError as error:
        print(str(error), file=sys.stderr)
        return 1
    except (OSError, ValueError, KeyError, TypeError):
        print("Sprawdz plik konfiguracji i format danych.", file=sys.stderr)
        return 1


if __name__ == "__main__":
    sys.exit(main())

Token znajduje się w ścieżce URL, ponieważ tak działa Telegram Bot API. Dlatego skrypt nie wypisuje pełnego wyjątku sieciowego ani adresu żądania. W narzędziach monitorujących ruch również zadbaj o maskowanie tej ścieżki.

Odpowiedź z ok: true oznacza przyjęcie żądania przez API. Nie jest potwierdzeniem, że właściciel telefonu przeczytał alert. To istotne przy procedurach, w których potrzebujesz jawnego potwierdzenia reakcji.

4. Ustal chat_id i wyślij próbę

Po wysłaniu /start do własnego bota wykonaj:

python3 "$HOME/bin/telegram_notify.py" --discover

Polecenie wypisze identyfikatory rozmów widoczne w pobranych aktualizacjach. Przy nowym bocie z jedną rozmową powinien pojawić się jeden identyfikator. Nie wybieraj losowego numeru, jeśli bot ma już kilku użytkowników. Najpierw ustal, która rozmowa jest Twoja.

Wpisz właściwą liczbę do chat_id w pliku konfiguracji. Jeśli wynik mówi brak, wyślij botowi nową wiadomość i ponów odczyt. Brak aktualizacji nie oznacza awarii samej metody wysyłania.

Teraz wyślij neutralny komunikat testowy:

printf '%s\n' 'Test powiadomienia z mojego serwera' \
  | python3 "$HOME/bin/telegram_notify.py"

Sprawdź telefon oraz kod zakończenia polecenia. Sam komunikat „skrypt wystartował” nie dowodzi, że wiadomość dotarła do właściwej rozmowy.

Co sprawdzono w przykładzie

Obsługę sukcesu, odpowiedzi 429, błędu sieci i niepoprawnego JSON-a sprawdziłem na lokalnych odpowiedziach testowych. Próby nie korzystały z tokenu Telegrama i nie wysłały rzeczywistej wiadomości.

Dlatego własny test końcowy jest niezbędny: potwierdza poprawność tokenu, rozmowy oraz połączenia wychodzącego z Twojego serwera. Nie zastępuje go samo poprawne wykonanie testów kodu.

Podłączenie do istniejącego zadania

Najwięcej wartości daje wiadomość wysłana po sprawdzeniu wyniku operacji. Poniższy wzorzec zakłada, że masz już działający skrypt /home/operator/bin/backup.sh. Zmień użytkownika i ścieżki na własne:

#!/usr/bin/env bash
if /home/operator/bin/backup.sh; then
  exit 0
else
  printf '%s\n' 'BACKUP ERROR: sprawdz log zadania na serwerze' \
    | /usr/bin/python3 /home/operator/bin/telegram_notify.py \
      --config /home/operator/.config/tt-telegram/config.json
  notify_status=$?
  if [ "$notify_status" -ne 0 ]; then
    printf '%s\n' 'Nie udalo sie wyslac alertu Telegram' >&2
  fi
  exit 1
fi

Backup powinien sam zwracać niezerowy kod przy błędzie. Wrapper nie naprawi skryptu, który po nieudanym kopiowaniu zawsze kończy się sukcesem. Wzorzec pozostawia także błąd całego zadania, nawet jeśli powiadomienie zostało wysłane poprawnie.

Nie przesyłaj na Telegram pełnego zrzutu bazy, tokenów ani treści prywatnych dokumentów. Krótka etykieta usługi, rodzaj problemu i wskazanie logu zwykle wystarczą. Szczegóły pozostają w kontrolowanym środowisku.

Cron i ograniczenie liczby alertów

Do sprawdzenia samej integracji możesz dodać jeden codzienny komunikat, na przykład o 9:15:

15 9 * * * printf 'Kontrolny sygnal serwera\n' | /usr/bin/python3 /home/operator/bin/telegram_notify.py --config /home/operator/.config/tt-telegram/config.json >> /home/operator/telegram-notify.log 2>&1

Po udanym teście usuń tę linię, jeśli nie chcesz regularnego sygnału kontrolnego. Log wymaga rotacji przy długotrwałym używaniu. Składnię harmonogramu sprawdzisz w generatorze cron, a środowisko zadania opisuje poradnik o cronie.

Nie wysyłaj tego samego błędu co minutę bez końca. W monitoringu zapisuj poprzedni stan: alert przy przejściu do awarii, przypomnienie dopiero po ustalonym czasie i osobna wiadomość po powrocie do normy. Zmniejsza to hałas i ułatwia odróżnienie nowego problemu od trwającego.

Gotowy monitoring, taki jak Uptime Kuma, może obsługiwać taki scenariusz wygodniej niż własny skrypt. Nadawca w Pythonie ma sens, gdy sygnał pochodzi z Twojego niestandardowego zadania.

Dlaczego skrypt nie ponawia wysyłki automatycznie

Timeout jest niejednoznaczny. Telegram mógł przyjąć wiadomość, zanim połączenie z klientem się urwało. Natychmiastowe ponowienie może wtedy utworzyć duplikat. Przykład zgłasza niepewność dostarczenia i oddaje decyzję nadrzędnemu zadaniu.

Przy odpowiedzi 429 skrypt pokazuje retry_after, jeśli API go zwróciło. Kolejna próba powinna nastąpić nie wcześniej niż po wskazanym czasie. Nie obchodź limitu równoległymi procesami. Dla większej liczby zdarzeń lepsza będzie kolejka oraz łączenie kilku podobnych alertów.

Pamiętaj też o awarii całego VPS-a. Wyłączony serwer nie wyśle informacji o własnym wyłączeniu. Do takiego przypadku potrzebujesz obserwatora działającego poza nim, a nie tylko lokalnego skryptu.

Najczęstsze pytania

Czy potrzebuję publicznego adresu i otwartego portu?

Do samego wysyłania nie. Wystarczy wychodzące połączenie HTTPS. Publiczny endpoint jest potrzebny w innym scenariuszu, na przykład przy odbieraniu webhooków.

Co zrobić po ujawnieniu tokenu?

Unieważnij go i wygeneruj nowy przez BotFather, a następnie zaktualizuj plik konfiguracji. Usuń sekret z miejsc publikacji, ale nie traktuj samego usunięcia tekstu jako cofnięcia wycieku.

Dlaczego bot nie wysyła do prywatnej rozmowy?

Sprawdź, czy użytkownik rozpoczął rozmowę, czy bot nie jest zablokowany i czy chat_id jest właściwy. Odczytaj kod błędu z API zamiast zmieniać firewall w ciemno.

Czy mogę wysyłać na grupę?

Tak, po dodaniu bota i sprawdzeniu jego uprawnień oraz identyfikatora grupy. Nie zamieniaj identyfikatora rozmowy na nazwę wyświetlaną grupy. Ten poradnik prowadzi przez prostszy wariant prywatnej rozmowy.

Czy Telegram powinien być jedynym kanałem krytycznych alarmów?

Nie opieraj krytycznej reakcji wyłącznie na jednym kanale i jednym serwerze. Dobierz monitoring zewnętrzny, eskalację i potwierdzenie odbioru do znaczenia usługi.

Źródła

Data publikacji: 21.10.2026.

KP
O AUTORZE

Krystian Proć

Tworzę narzędzia do pracy z danymi, systemy backendowe i automatyzacje. Pracuję z SQL, PHP, TypeScriptem i Dockerem; rozwijam m.in. dragon-island.com. AI pomaga mi przyspieszać pracę, a architekturę, weryfikację i decyzje techniczne biorę na siebie. Na Trybie Technicznym dzielę się doświadczeniami z budowania i utrzymywania własnych projektów.

Dyskusja

Dodaj komentarz

Twój adres email nie zostanie opublikowany. Wymagane pola są oznaczone *