Buduj teraz
PL

Jak uzyskać dostęp do API Telegrama: api_id, api_hash i tokeny botów

Przewodnik po API Telegrama

Jak uzyskać dostęp do API Telegrama: api_id, api_hash i tokeny botów

The Telegram API to nie jest jedno API, to trzy API: Bot API, Client API (MTProto) oraz Gateway API. Ten przewodnik pokazuje dokładnie, skąd wziąć swoje dane uwierzytelniające, co api_id, api_hash oraz token bota z BotFather dla każdej metod odblokowania, a trzecia opcja, którą większość poradników pomija: połączenie istniejącego konta użytkownika Telegrama przez Unipile bez pisania ani jednej linijki kodu MTProto.
Budowanie z Unipile
Zobacz dokumentację

hosted-auth.js
// Połącz istniejące konto użytkownika Telegram // Brak api_id / api_hash do samodzielnego zarządzania const połączyć = czekać unipile.uwierzytelnianie hostowane.create({   dostawcy: ["TELEGRAM"],   ważne do: "2026-12-31T23:59:59.000Z" }); // Użytkownik loguje się za pomocą kodu QR lub swojej sesji // Status konta zmienia się na "połączono"
account.status: "połączono"
Rozpoczynamy

3 interapi Telegram i której potrzebujesz

Większość poradników mówi o "API Telegrama", jakby to była jedna rzecz. Tak nie jest. Telegram udostępnia trzy różne API, z których każde ma własne dane uwierzytelniające, własne zasady i własne limity. Wybór niewłaściwego to najszybszy sposób na zmarnowanie tygodnia na budowanie pod niewłaściwymi drzwiami.

API bota

Czy potrzebujesz zautomatyzowanego bota, który reaguje na polecenia i wiadomości?
Wymagania: token bota od BotFather
  • HTTP API, bez konieczności znajomości MTProto
  • Działa jak konto bota, a nie człowieka
  • Bezpłatny w użyciu

Klient API (MTProto)

Czy musisz zbudować pełnoprawnego klienta działającego jak prawdziwy użytkownik Telegrama?
Wymagania: api_id + api_hash z my.telegram.org
  • Surowy protokół MTProto, Ty implementujesz klienta
  • Działa jak konto prawdziwego użytkownika
  • Darmowe, jeden api_id na numer telefonu

Gateway API

Czy do uwierzytelniania numeru telefonu musisz wysyłać tylko kody weryfikacyjne?
Wymagania: konto Gateway API
  • Tylko dostarczanie jednorazowych haseł (OTP), bez wiadomości ogólnych
  • Uruchomione niezależnie od Bot API i Client API
  • Poza zakresem tego przewodnika
Żadne z powyższych nie pasuje
Pomiń budowanie własnego klienta MTProto
Unipile łączy istniejące konto użytkownika Telegrama za pomocą funkcji Urządzenia w Telegramie, logowania za pomocą kodu QR lub uwierzytelniania hostowanego. Brak api_id, brak api_hash, brak ograniczeń botów.
Zbuduj to z Unipile
Klient API / MTProto

Uzyskaj swoje dane uwierzytelniające API Telegrama: api_id oraz api_hash

Oto prawdziwa ścieżka do "uzyskania API Telegrama", której większość ludzi szuka i nigdy nie znajduje jasno opisanej: my.telegram.org, sekcja Narzędzia do tworzenia API. Oto dokładna trasa, od początku do końca.
1
Wejdź na stronę my.telegram.org i zaloguj się
Musisz posiadać aktywne konto na Telegramie, zweryfikowane za pomocą tego samego numeru telefonu, którego użyjesz do uwierzytelnienia. Wprowadź swój numer telefonu oraz kod logowania wysłany do aplikacji Telegram.
2
Otwórz "Narzędzia do tworzenia interfejsów API"
Ta sekcja znajduje się w ustawieniach Twojego konta na my.telegram.org. Jest to jedyne oficjalne miejsce, w którym Telegram wydaje dane uwierzytelniające interfejsu API klienta.
3
Wypełnij formularz zgłoszeniowy
Tytuł aplikacji, krótka nazwa i platforma. Pola te opisują aplikację, która będzie korzystać z MTProto, i nie muszą być zgodne z publiczną nazwą produktu.
4
Uzyskaj swoje api_id i api_hash
Telegram wydaje parę natychmiast. api_id jest identyfikatorem numerycznym, api_hash sekret dopasowania. Przechowuj oba jak każde inne poświadczenie, uwierzytelniają one Twojego klienta MTProto względem serwerów Telegramu.
Jedno ograniczenie, wokół którego należy zaplanować plan
Numer telefonu może zawierać tylko jedno api_id. Jeśli potrzebujesz kilku aplikacji lub kilku środowisk, potrzebujesz kilku numerów telefonu lub używasz tego samego api_id w całej bazie kodu. Nie ma możliwości samodzielnego wygenerowania drugiego api_id dla tego samego numeru.

.env
# Z serwisu my.telegram.org, narzędzia do tworzenia aplikacji API TELEGRAM_API_ID=1234567 TELEGRAM_API_HASH=0123456789abcdef0123456789abcdef # Jeden identyfikator api_id na numer telefonu; należy go bezpiecznie przechowywać
Zbuduj połączenie swojego konta z Unipile
API bota

Uzyskaj token bota za pośrednictwem BotFather

Druga ścieżka dostępu do API Telegrama nie wymaga konta my.telegram.org, ani api_id, ani api_hash. Działa w całości wewnątrz czatu z oficjalnym botem Telegrama, @BotFather.
1
Otwórz czat z @BotFather
Wyszukaj "BotFather" w Telegramie. To oficjalny bot Telegrama służący do tworzenia i zarządzania każdym innym botem na platformie.
2
Wyślij /nowybot
BotFather przeprowadza Cię przez proces tworzenia nowego bota bezpośrednio na czacie, bez panelu sterowania i bez formularza.
3
Wybierz imię i nazwę użytkownika
Nazwa wyświetlana może być dowolna. Nazwa użytkownika musi być unikalna i kończyć się na bot, na przykład mój_bot_wsparcia.
4
Skopiuj token bota
BotFather odpowiada tokenem natychmiast. Zachowaj go w tajemnicy, ponieważ uwierzytelnia każde wywołanie Bot API wykonywane przez Twojego bota.

Obecne Bot API to wersja 10.2, opublikowane 14 lipca 2026 r. (źródło: core.telegram.org/bots/api). Każdy token bota działa z tym samym wersjonowanym interfejsem HTTP API.

terminal
# – Sprawdź token swojego bota za pomocą interfejsu API bota zwijać się "https://api.telegram.org/bot/getMe" # Przykładowa odpowiedź {   "OK prawda,   "wynik {     "id 123456789,     "jest_botem": prawda,     "nazwa użytkownika "mój_bot_wsparcia"   } }
Porównanie

Do czego tak naprawdę służy każde API Telegramu

Cztery sposoby na interakcję z Telegramem, cztery bardzo różne zestawy uprawnień. Oto z czym każdy z nich się łączy, jakich danych uwierzytelniających potrzebuje i gdzie ma swoje granice.
KryteriaAPI botaKlient API (MTProto)Gateway APIUnipile
Co łączyszKonto botaPrawdziwe konto użytkownika, dla którego tworzysz klientaNic, tylko dostawa OTPIstniejące konto rzeczywistego użytkownika
Potrzebne dane uwierzytelniająceToken bota od BotFatherapi_id + api_hash z my.telegram.orgKonto API bramki sieciowejLogowanie za pomocą kodu QR lub uwierzytelnianie hostowane (dostawcy: "TELEGRAM")
Wysyła/odbiera jako konto użytkownikaNie, działa jak botTakNieTak
Implementacja MTProtoNieupotrzebne, tylko HTTPBudujesz to samNie dotyczyObsługiwane przez Unipile
Zarządzanie uczestnikami grupyOgraniczone do uprawnień botaJeśli go zbudujesz, przyjdzieNie dotyczyPobierz, dodaj, usuń uczestników
Złożoność konfiguracjiNiskiCześć, jesteś właścicielem klienta MTProtoNiskiNiski, brak MTProto do utrzymania
KosztDarmowyDarmowyNieobjęte tym przewodnikiemZawarte w Twoim planie Unipile
Ryzyko bana za nadużyciaUnieważnienie tokenuTrwały zakaz za spamowanieNie dotyczyZłagodzone dzięki wytycznym Unipile dotyczącym limitów częstotliwości zapytań
API bota
ŁączyKonto bota
PoświadczeniaToken bota (BotFather)
Działaj jak człowiekNie
KonfiguracjaNiski
KosztDarmowy
Klient API (MTProto)
ŁączyPrawdziwe konto użytkownika (klient typu „zrób to sam”)
Poświadczeniaapi_id + api_hash
Działaj jak człowiekTak
KonfiguracjaWysoki, MTProto zbudowany samodzielnie
KosztDarmowy
Gateway API
ŁączyNic, tylko dostawa OTP
PoświadczeniaKonto API bramki sieciowej
KonfiguracjaNiski
ZakresZ tego przewodnika
Unipile
ŁączyIstniejące konto rzeczywistego użytkownika
PoświadczeniaKod QR lub Hosted Auth
Działaj jak człowiekTak
KonfiguracjaNiski, brak MTProto do utrzymania
GrupyPobierz / dodaj / usuń uczestników
Czego Unipile nie obsługuje w serwisie Telegram
Kanały, społeczności i transmisje, motyw czatu, tajne czaty, załączniki kontaktów / lokalizacji / ankiet / wydarzeń, administracja grupami (zatwierdzanie, awansowanie, cofanie uprawnień), usuwanie czatów, archiwizowanie oraz połączenia głosowe lub wideo. Unipile łączy konto, nie odwzorowuje każdej funkcji klienta Telegrama.
Zbuduj swoją integrację Telegram z Unipile
Cennik i limity

To jest darmowe. Tutaj pojawia się problem.

Zarówno Bot API, jak i Telegram API (MTProto) są darmowe w użyciu. Nie ma żadnych faktur, opłat za wiadomość ani płatnych poziomów blokujących dane uwierzytelniające. Haczyk nie tkwi w pieniądzach, lecz w zachowaniu.
Powodznie, spam i fałszywe liczniki
Zbyt szybkie wysyłanie wiadomości, masowe wysyłanie wiadomości do niepowiązanych użytkowników lub sztuczne zwiększanie liczników wyświetleń i reakcji to najszybsza droga do uruchomienia trwały ban, zarówno w Bot API, jak i w Client API.
Nieoficjalne klienty są monitorowane
Każdy klient zbudowany przy użyciu własnego api_id i api_hash jest automatycznie objęty(-a) nadzorem przez systemy Telegrama. Niezwykłe wzorce są oznaczane szybciej niż w oficjalnych aplikacjach.
Wskazówki samego Unipile dotyczące pozostawania poza radarom
Unikaj zupełnie nowych kont na Telegramie do automatyzacji, rozgrzej je jak każde inne konto
Stopniowo zwiększaj wolumen komunikatów zamiast zaczynać od pełnej przepustowości
Zachowaj co najmniej 10 do 20 sekund przerwy między wiadomościami wysyłanymi z tego samego konta
Twórz bezpieczniejsze przepisy wiadomości z Unipile
Podejście Unipile

Trzeci sposób: połącz istniejące konto Telegram

Ani Bot API, ani samodzielnie zbudowany klient MTProto. Telegramowe API Unipile łączy istniejące konto użytkownika Telegram, poprzez sam Telegram Urządzenia funkcja, ten sam mechanizm, który pozwala na używanie Telegrama na nowym telefonie lub aplikacji desktopowej.
Logowanie odbywa się przez Skanuj kod QR, lub przez Hosted Auth z dostawcy: "TELEGRAM" jeśli chcesz mieć proces łączenia z białą etykietą we własnym produkcie. Po połączeniu konto zachowuje się jak zwykłe konto: nie jest botem i nie wymagało api_id ani api_hash wydanych przez my.telegram.org.
Ma to znaczenie, ponieważ eliminuje dwie najtrudniejsze części samodzielnego budowania na API Telegrama: implementację protokołu MTProto oraz zarządzanie sesjami i ponownymi połączeniami w przypadku usunięcia urządzenia. Jeśli urządzenie Unipile zostanie usunięte z sesji Telegrama danego konta, Unipile wykrywa to, a status konta po prostu zmienia się na rozłączony, gotowy do ponownego podłączenia.
Wysyłaj i odbieraj wiadomości bezpośrednie jako prawdziwe konto
Zarządzaj uczestnikami grupy: pobierz, dodaj, usuń
Brak kanałów, społeczności lub audycji
Brak administracji grupą (zatwierdzanie, awansowanie, odbieranie uprawnień), brak połączeń głosowych i wideo
Jak wysłać wiadomość na Telegramie za pomocą API
Strona produktu API Telegram Unipile
Zacznij budować z Unipile

Powiązane konto
DostawcaTelegram
Metoda uwierzytelnianiaKod QR / Uwierzytelnianie hostowane
Statuspołączony
Urządzenie zostało usunięte z Telegramarozłączony
Obsługa ponownej synchronizacjiTak
Przypadki użycia

Przypadki użycia interfejsu API Telegrama w systemach CRM i ATS

Gdy konto Telegram zostanie połączone jako prawdziwe powiązane konto, a nie bot, u klientów Unipile stale pojawiają się dwa główne zastosowania: zespoły sprzedaży centralizujące konwersacje oraz rekruterzy docierający do kandydatów tam, gdzie oni już są.

CRM: unifikacja konwersacji z Telegrama

Zespoły sprzedaży i obsługi, które już rozmawiają z potencjalnymi i obecnymi klientami na Telegramie, nie chcą korzystać w tym celu z osobnej aplikacji. Dzięki połączeniu konta za pośrednictwem Unipile każda konwersja na Telegramie trafia do tej samej skrzynki odbiorczej co rozmowy e-mail, LinkedIn czy WhatsApp, przypisana do odpowiedniego rekordu kontaktu w CRM.
Zunifikowana skrzynka odbiorczaPołączone kontaSynchronizacja kontaktów

ATS: docieraj do kandydatów na Telegramie

W regionach, gdzie Telegram jest głównym kanałem komunikacji, rekruterzy łączą swoje własne konta Telegram, aby docierać do kandydatów bezpośrednio z poziomu ATS, zachowywać pełną historię wiadomości w profilu kandydata oraz przekazywać sobie konwersacje bez utraty kontekstu.
Pozyskiwanie kandydatówHistoria wiadomościPrzekazanie zespołu
Klient API / MTProto

Zaloguj się za pomocą kodu QR: proces urządzeń krok po kroku

Logowanie za pomocą kodu QR to mechanizm kryjący się za Telegramem Urządzenia funkcja, dokładnie ta sama, której używasz, aby dodać Telegram Desktop lub Telegram Web do swojego konta. Jest to również proces, w ramach którego Unipile działa w Twoim imieniu, gdy łączy istniejące konto użytkownika Telegrama. Jeśli zbudujesz to samodzielnie, wdrażasz dwustronny uścisk dłoni między urządzeniem, które już ufa kontu, a urządzeniem proszącym o dołączenie do niego, a nie pojedyncze wywołanie typu żądanie/odpowiedź. Oto dokładnie, co dzieje się między dwiema aplikacjami, metoda po metodzie.
1
Poproś o token logowania
Urządzenie, które chce się zalogować, dzwoni auth.exportLoginToken. Telegram odpowiada za pomocą auth.loginTokenbiparny token plus ważność, ogólnie rzecz biorąc 30 sekund.
2
Zakoduj to w kodzie QR
Token jest zakodowany w base64url i umieszczone wewnątrz tg://login?token=<base64url> URL. Ten adres URL jest wyświetlany na ekranie jako kod QR, który można zeskanować.
3
Skanowanie z aplikacji, w której jesteś już zalogowany
Zalogowana już aplikacja Telegram skanuje kod i wywołuje auth.acceptLoginToken z odszyfrowanym tokenem.
4
Ankieta dotycząca wyniku
Urządzenie, które się loguje, otrzymuje aktualizujTokenLogowania aktualizuj, a następnie wywołaj auth.exportLoginToken ponownie, aby pobrać wynik skanowania.
5
Potwierdź lub migruj centrum danych
Jeśli centrum danych pasuje, Telegram zwraca auth.loginTokenSuccess, logowanie zostało wykonane. Jeśli nie pasuje, odpowiedź to auth.loginTokenMigrateTo, a klient musi zadzwonić auth.importLoginToken z tym samym tokenem przeciwko wskazanemu centrum danych.

proces logowania za pomocą kodu QR
// Urządzenie żądające logowania auth.exportLoginToken(api_id, api_hash) // -> auth.loginToken { token, expires } // Wyrenderowano jako kod QR tg://login?token=<base64url(token)> // Urządzenie, które jest już uwierzytelnione, skanuje to auth.acceptLoginToken(token) // Logujące się urządzenie odpytuje ponownie auth.exportLoginToken() // -> auth.loginTokenSuccess // lub auth.loginTokenMigrateTo { dc_id }
Krótkie okno, zaplanuj ponowną próbę
Token jest zazwyczaj ważny tylko przez 30 sekund. Jeśli straci ważność przed zeskanowaniem, klient musi zadzwonić auth.exportLoginToken jeszcze raz i wygeneruj nowy kod, a nie tylko ponów stary.
NIEPOPRAWNY_TOKEN_AUTORYZACJI
TOKEN_AUTORYZACJI_WYGASL
TOKEN_AUTORYZACJI_ZOSTAŁ_JUŻ_ZAWŁASZCZONY
To jest dokładnie taka wymiana wiadomości, jaką Unipile obsługuje w Twoim imieniu, gdy łączysz konto Telegram za pośrednictwem swojego Urządzenia integracja: kod QR, wymiana tokena, obsługa centrum danych oraz ponowna próba w przypadku wygaśnięcia tokena. Wywołujesz jeden endpoint, a Unipile obsługuje wyżej opisaną konwersację MTProto, w tym przypadek, w którym podłączane konto znajduje się w innym centrum danych niż to, z którym Twoja aplikacja połączyła się jako pierwsza. Obsługę tego centrum danych łatwo pominąć przy budowaniu procesu od zera, ponieważ pojawia się ona tylko w przypadku podzbioru kont i po cichu przerywa logowanie dla tych, których dotyczy, jeśli auth.loginTokenMigrateTo gałąź nie jest obsługiwana.
Zbuduj swój proces logowania za pomocą kodu QR przy użyciu Unipile
Klient API / MTProto

Zaloguj się za pomocą numeru telefonu oraz zapory 2FA

Klasyczne logowanie za pomocą numeru telefonu to moment, w którym większość samodzielnie budowanych klientów Telegrama utyka. Nie dlatego, że jest skomplikowane, ale dlatego, że proces ten cicho rozgałęzia się w momencie włączenia uwierzytelniania dwuskładnikowego, a to rozgałęzienie nie jest opcjonalne. Klient, który implementuje wyłącznie optymistyczny scenariusz (wyślij kod, zatwierdź kod, gotowe), działa poprawnie na koncie testowym, a następnie zawodzi na produkcji przy pierwszym spotkaniu z prawdziwym użytkownikiem, który ma włączone hasło w chmurze.
1
Wyślij kod logowania
auth.sendCode wysyła kod na numer telefonu i zwraca auth.sentCode obiekt zawierający hash_kodu_telefonu, wymagane na następną rozmowę.
2
Zweryfikuj kod
auth.signIn sprawdza kod pod kątem hash_kodu_telefonu. Jeśli numer telefonu nie ma jeszcze konta, Telegram zwraca Wymagana rejestracja autoryzacji zamiast autoryzacji.
3
Napotkać ścianę weryfikacji dwuetapowej
Jeśli włączona jest weryfikacja dwuetapowa na koncie, auth.signIn odpowiada literą a Błąd 400: Wymagane hasło sesji. Jest to oczekiwana odpowiedź dla każdego konta z hasłem w chmurze, a nie błąd w obsłudze jako wyjątek.
4
Uzgodnij to z SRP
Zakończenie logowania oznacza uruchomienie protokołu SRP: zbuduj InputCheckPasswordSRP obiekt z parametrów hasła konta, a następnie wywołaj auth.checkPassword. Sukces zwraca auth.authorization; błędne hasło zwraca NIEPRAWIDŁOWY_HASH_HASŁA.
Tylko oficjalne aplikacje otrzymują wiadomości SMS z Firebase
Dozwolone jest używanie wyłącznie oficjalnych aplikacji mobilnych samego Telegrama Dostarczanie kodów SMS oparty na Firebase. Aplikacje firm trzecich muszą przekierowywać kod za pośrednictwem innego kanału dostarczania lub zapisywać w sms@telegram.org aby omówić dostęp.
Błędy, których można się spodziewać na tej ścieżce
WYMAGANE_HASŁO_SESJI
NIEPRAWIDŁOWY_HASH_HASŁA
Wymagana rejestracja autoryzacji
Integracja Telegrama firmy Unipile obsługuje dla Ciebie całą tę gałąź: dostarczanie kodu, WYMAGANE_HASŁO_SESJI sprawdź i wymianę SRP, gdy ustawione jest hasło w chmurze, czy konto łączy się za pomocą numeru telefonu, kodu QR lub Hosted Auth. Obejmuje to powyższe ograniczenie dotyczące dostarczania wiadomości SMS: ponieważ aplikacje innych firm nie mogą polegać na dostarczaniu opartym na Firebase, jest to jedno z miejsc, w których samodzielne zarządzanie procesem obsługi numerów telefonów generuje realne obciążenie operacyjne, a nie tylko kod, zanim wyślesz choćby jedną wiadomość.
Limity wysyłania

Limity zapytań API Telegramu w liczbach

Sekcja 5 dotyczyła zachowań, które prowadzą do banowania kont. Oto rzeczywiste, udokumentowane limity po stronie Bot API oraz koszty ich zwiększenia.
1/s
Maksymalna liczba wiadomości w tym samym czacie indywidualnym
20/min
Maksymalna liczba wiadomości w jednej grupie
~30/s
Przybliżony limit nadawania w różnych czatach
429
Błąd jest zwracany po przekroczeniu któregokolwiek z tych limitów
Płatne transmisje podnoszą poprzeczkę, pod dwoma warunkami
Boty mogą włączyć płatne audycje przez BotFather, co podnosi limit wysyłania do 1000 wiadomości na sekundę. Wiadomości wysłane powyżej darmowego progu kosztują 0,1 Gwiazdki Telegrama każdy. Jest to ograniczone dwoma wymaganiami na poziomie konta, z których oba muszą być spełnione jednocześnie.
Saldo 100 000 gwiazdek
100 000 aktywnych użytkowników miesięcznie
Przekrocz indywidualny, grupowy lub transmisyjny limit powyżej, a Bot API odpowie za pomocą 429 status ujęty w odniesienie do błędu poniżej, obok POWÓDŹ 420 oraz FLOOD_WAIT_X kody używane po stronie MTProto. Oba mechanizmy istnieją z tego samego powodu: aby zmusić Cię do zwolnienia tempa, zanim Telegram zdecyduje się je zwolnić za Ciebie.

Te numery są specyficzne dla Bot API. Dla połączonego konto użytkownika, nie ma opublikowanego limitu, są tylko własne wytyczne Unipile dotyczące tempa zawarte w to nic nie kosztuje, oto gdzie się psuje: rozgrzej nowe konta, zwiększaj aktywność stopniowo, zachowuj co najmniej 10 do 20 sekund przerwy między wiadomościami.
Odniesienie do błędu

Błędy API Telegrama, które musisz znać

Błędy MTProto mają taki sam trzycyfrowy format jak kody statusu HTTP, które większość programistów już zna, w parze z krótkim ciągiem znaków czytanym przez maszynę. Oto tabela referencyjna oraz jeden błąd, który pojawia się tylko u użytkowników końcowych, a nie u Ciebie. Znajomość tej listy przed wdrożeniem ma większe znaczenie niż po nim: kilka z tych kodów, 303 oraz 420 w szczególności nie są wyjątkowymi błędami, są częścią normalnych warunków pracy klienta MTProto i muszą być obsługiwane w ścieżce kodu, a nie logowane i ignorowane.
KodZnaczenie
303 Zobacz inneŻądanie musi zostać powtórzone, kierując je do innego centrum danych.
400 BAD_REQUESTZapytanie zawiera błędy. Nieprawidłowy identyfikator API jest powszechnym przykładem tego kodu.
401 BRAK AUTORYZACJITa metoda wymaga funkcji, która jest zarezerwowana dla upoważnionych użytkowników.
403 ZABRONIONENaruszenie prywatności, na przykład próba napisania do użytkownika, który Cię zablokował.
404 NIE_ZNALEZIONOŻądany obiekt lub metoda nie istnieje.
420 FLOOD / FLOOD_WAIT_XPrzekroczono maksymalną liczbę dozwolonych wywołań, odczekaj X sekund przed ponowieniem próby.
303 Zobacz inneŻądanie musi zostać powtórzone, kierując je do innego centrum danych.
400 BAD_REQUESTZapytanie zawiera błędy. Nieprawidłowy identyfikator API jest powszechnym przykładem tego kodu.
401 BRAK AUTORYZACJITa metoda wymaga funkcji, która jest zarezerwowana dla upoważnionych użytkowników.
403 ZABRONIONENaruszenie prywatności, na przykład próba napisania do użytkownika, który Cię zablokował.
404 NIE_ZNALEZIONOŻądany obiekt lub metoda nie istnieje.
420 FLOOD / FLOOD_WAIT_XPrzekroczono maksymalną liczbę dozwolonych wywołań, odczekaj X sekund przed ponowieniem próby.
Jeszcze jeden, po stronie użytkownika końcowego
API_ID_PUBLISHED_FLOOD pojawia się u użytkowników końcowych, gdy opublikowana aplikacja ponownie wykorzystuje przykład api_id wysłane wewnątrz otwartego kodu źródłowego zamiast żądania własnego. Każda publikowana przez Ciebie aplikacja potrzebuje własnego api_id oraz api_hash z my.telegram.org.
Klient zbudowany bezpośrednio na Client API (MTProto) musi samodzielnie obsługiwać każdy z tych kodów: ponowić próbę połączenia z właściwym centrum danych w 303, odpuść sobie 420, i traktuj 401 oraz 403 jako sygnały o stanie konta zamiast ogólnych błędów. Połączenie istniejącego konta przez Unipile przenosi tę obsługę błędów za pojedynczy status powiązanego konta, zamiast zestawu kodów MTProto, które Twój własny kod musi poprawnie interpretować przy każdym wywołaniu.
Klient API / MTProto

Wybór biblioteki MTProto i czego ona dla Ciebie nie zrobi

Jeśli zdecydujesz się zbudować ścieżkę API klienta samodzielnie, nie wdrażasz MTProto ze specyfikacji. Kilka bibliotek obsługuje już ten protokół, więc sam klient rzadko jest trudną częścią. Wybór jednej z nich rozwiąże tylko część problemu, i to zazwyczaj tę mniejszą.
Python

Telethon

Czysto pythonowa implementacja protokołu MTProto, oparta na mechanizmie async/await, z interfejsem API klienta przypominającym zwykłego Pythona zamiast surowych wywołań protokołu.
Python

Pyrogram

Kolejny klient MTProto w Pythonie, z własnym podejściem do obsługi sesji i interfejsem zaprojektowanym tak, aby bardziej przypominać konwencjonalne SDK niż bibliotekę protokołu.
Node.js

GramJS

Najbliższy odpowiednik Telethon dla baz kodu w JavaScript i TypeScript, implementujący tę samą konwersację MTProto dla środowiska wykonawczego Node.js.
Oficjalny

TDLib

Oficjalna biblioteka Telegrama, napisana w C++, z powiązaniami udostępnionymi dla kilku języków. Implementuje pełny stos MTProto w taki sam sposób, jak robią to własne aplikacje Telegrama.
To, co zazwyczaj pasuje, sprowadza się do stosu technologii, który już posiadasz, a nie do porównania funkcji: zaplecze w Pythonie wskazuje na Telethon lub Pyrogram, backend w Node.js lub TypeScript wskazuje na GramJS, i zespół, który chce pozostać tak blisko oficjalnych aplikacji Telegrama, jak to możliwe, wskazuje na TDLib i jego powiązań. Żaden z tych wyborów nie usuwa drugiej połowy poniższego dzieła.
Co daje ci biblioteka
Warstwa szyfrowania MTProto i surowe wywołania metod
Aktualizacja obsługi przychodzących zdarzeń z serwerów Telegrama
Interfejs API po stronie klienta do wywoływania metod uwierzytelniania, przesyłania wiadomości i obsługi konta
Co nadal budujesz sam
Nniezawodne utrwalanie sesji w pamięci trwałej między restartami a wdrożeniami
Obsługa przepływu SESSION_PASSWORD_NEEDED i SRP od początku do końca dla Twoich użytkowników
Płynne ponowne łączenie i śledzenie statusu konta w przypadku usunięcia urządzenia
Lub pomiń klienta całkowicie
Unipile uruchamia już klienta MTProto dla Ciebie
Trwałość sesji, zapora 2FA, ponowne łączenie i cykl życia konta są obsługiwane za pomocą jednego interfejsu API. Łączysz istniejące konto Telegram, nie musisz utrzymywać biblioteki.
Buduj z Unipile

API Telegrama: Często zadawane pytania

Konkretne odpowiedzi na temat api_id, api_hash, tokenów botów z BotFather oraz łączenia istniejącego konta Telegram z Unipile.

Telegram nie ma jednego API, ma trzy. Bot API to interfejs HTTP dla kont botów. API Telegrama, nazywane również API klienta, działa na protokole MTProto i na nim opierają się pełne klienty Telegrama. Gateway API wysyła wyłącznie kody weryfikacyjne. To, którego potrzebujesz, zależy od tego, czy automatyzujesz bota, czy działasz jako prawdziwe konto użytkownika.
Nie ma jednego klucza API Telegrama. W przypadku API klienta logujesz się na stronie my.telegram.org, otwierasz narzędzia programistyczne API i wypełniasz formularz, aby otrzymać api_id oraz api_hash. W przypadku API bota piszesz do BotFather wewnątrz Telegrama, a on zwraca token bota. Zwróć uwagę, że Telegram zezwala tylko na jedno api_id na numer telefonu.
Tak. Telegram twierdzi, że zarówno Bot API, jak i Telegram API są dostępne bezpłatnie, bez opłat za wiadomość. Prawdziwy koszt tkwi w infrastrukturze, którą utrzymujesz, obsłudze sesji oraz ryzyku zbanowania w przypadku zbyt agresywnego wysyłania wiadomości.
Bot API to prosty interfejs HTTPS: wywołujesz metody takie jak sendMessage pod adresem api.telegram.org przy użyciu tokenu swojego bota. Client API to binarny protokół MTProto, dlatego większość deweloperów korzysta z biblioteki takiej jak Telethon, Pyrogram lub GramJS zamiast implementować go samodzielnie.
Bot API 10.2, opublikowane 14 lipca 2026 r. Nastąpiło po wersji 10.1 z 11 czerwca 2026 r. oraz wersji 10.0 z 8 maja 2026 r.
Tak. Możesz połączyć istniejące konto Telegram za pomocą wbudowanej funkcji Urządzenia w Telegramie (w ten sposób Unipile powiązuje konta), korzystając z logowania za pomocą kodu QR lub hostowanego procesu uwierzytelniania. Zyskujesz dostęp do konta użytkownika bez konieczności samodzielnego wdrażania protokołu MTProto, przechowywania sesji czy obsługi weryfikacji dwuetapowej.

Masz jeszcze jakieś pytania? Nasz zespół służy pomocą.

Porozmawiaj z ekspertem
API Telegrama, jak należy

Zbuduj integrację z API Telegrama za pomocą Unipile

Pomiń klienta MTProto, pomiń ograniczenia botów. Połącz istniejące konto Telegram przez Unipile i zintegruj je z WhatsApp, LinkedIn, Instagramem, Gmailem, Outlookiem i protokołem IMAP w jednym API.
Budowanie z Unipile
Przeczytaj dokumentację Zobacz stronę API Telegrama
Wyślij wiadomość na Telegramie za pomocą API
Strona produktu API Telegram Unipile