Python ile Telegram API: Bot API, MTProto ve Bağlı Hesaplar

Python Uygulama Kılavuzu

Bu Telegram API Python rehber: her yaklaşım için çalışan kod

Kod öncelikli bir rehberi Python Telegram Bot API: sendMessage ile ara istekleri, minimal bir bot python-telegram-bot, Telethon, Pyrogram veya Unipile SDK ile gerçek, bağlanmış bir hesap ve komut dosyanızın ilk anda çökmesini önlemek için istek sınırlarının (rate limits) nasıl yönetileceği 429. İster buraya bir arayışla gelmiş olun Telegram bot API Python örnek veya tamamı telegram api python resim, aşağıdaki her yaklaşım çalışan kodla birlikte sunulmaktadır.



telegram_bot.py
İthalat istekleri TOKEN = "123456:ABC-your-bot-token" url = f"https://api.telegram.org/bot{TOKEN}/sendMessage" yük = { "sohbet_kimliği": 123456789, "metin": "Python'dan merhaba", "ayirma_modu": "MarkdownV2" } response = istemler.POST(url, json=payload) print(Yanıt.json())
200 OK: mesaj gönderildi
Karar Rehberi

Python'da Telegram API'sini oluşturmanın üç yolu ve hangisini seçmeniz gerektiği

Kimlik bilgilerine sahip olduğunuzda, bir Python kod tabanından Telegram ile iletişim kurmanın üç somut yolu vardır. Bunlar aynı iş için birbirinin yerine geçebilen kütüphaneler değildir; her biri farklı bir kod ve farklı kısıtlamalarla farklı türde bir gönderici olarak kimlik doğrulaması yapar.
Python Telegram Bot API
BotFather'dan alınan bir bot token'ı, Python ile şu şekilde çağrılır: istekleri veya benzeri bir sarmalayıcı kütüphane python-telegram-bot. Göndermenin en hızlı yolu, ancak bir bot yalnızca kendisine ilk başta yazmış olan bir kullanıcıya mesaj gönderebilir.
Bildirimler ve destek botları için en iyisi
Telethon / Pyrogram (MTProto)
Kendi [altyapınızı/hesabınızı] kullanarak ham Telegram protokolüyle iletişim kuran bir Python istemci kütüphanesi api_id ve api_hash. Gerçek bir hesap olarak oturum açar, ancak oturum depolaması, yeniden bağlanmalar ve 2FA akışı size aittir.
Tamamen özel bir Python istemcisi için en iyisi
Unipile Python SDKUnipile
Ham bir MTProto istemcisi yerine, yalnızca birkaç satırlık SDK koduyla Python'dan çağrılan bağlı bir hesap. Kalıcı hale getirilecek oturum dosyaları yok, kendinizin yazması gereken bir 2FA dalı yok.
MTProto'ya sahip olmadan hızlı kargolama için en iyisi
Bu bölüm, kimlik bilgilerinize sahip olduktan sonra Python kodu ile ilgilidir. Bot API ile Telegram Client API arasındaki tam yetki paylaşımı ve karşılaştırma (sınırlar, kimlik, her birinin yapabildikleri ve yapamadıkları) için özel karşılaştırma sayfamıza bakın: Telegram Bot API ve Telegram API. Bot tokenınızı almak için veya api_id / api_hash her şeyden önce, bakın adım adım erişim kılavuzu.


Python entegrasyonunuzu oluşturun
Kod Eğitimi

Requests kütüphanesi ile Python Telegram Bot API'si

Çağırmanın en doğrudan yolu Python ile Telegram Bot API ile düz bir HTTP çağrısıdır istekleri, hiçbir sarmalayıcı (wrapper) kütüphane dahil değildir. Bot API 10.2 (14 Temmuz 2026) itibarıyla, BotFather'dan alınan bir bot token'ı ve iki parametre gereklidir sendMessage gerektirir.
1
Bir bot token'ı alın, ardından sendMessage'ı çağırın
BotFather, şu biçimde bir token verir: 123456:ABC-your-bot-token. Şunu da içeren her Bot API çağrısı: sendMessage, bir POSTA için https://api.telegram.org/bot<TOKEN>/sendMessage JSON gövdesi ile.



send_message.py
İthalat işletim sistemi İthalat istekleri TOKEN = işletim sistemi.çevresinde["TELEGRAM_BOT_TOKEN"] URL = f"https://api.telegram.org/bot{TOKEN}/sendMessage" yük = { "sohbet_kimliği": 123456789, "metin": ""#4821 numaralı siparişiniz kargoya verildi."", "ayirma_modu": "MarkdownV2" } response = istemler.POST(URL, json=payload, timeout=10)
2
Yanıtı kontrol edin, çalıştığını varsaymayın
Bot API, her zaman şu içeriğe sahip bir JSON gövdesiyle yanıt verir: Tamam boolean. 200 olmayan bir durum kodu veya tamam: yanlış mesajın gönderilmediği anlamına gelir ve yük, okunabilir bir metin içerir Açıklama giriş yapmak.



send_message.py
veri = cevap.json() eğer yanit.durum_kodu == 200 ve veri.olsun("tamam"): mesaj_id = veri["sonuç"]["mesaj_id"] print(gönderildi, message_id={message_id}") aksi takdirde: print(f"başarısız: {data.get('description')}")
ParametreTipAçıklama
chat_id Gerekliint veya strHedef sohbet tanımlayıcısı veya @kullaniciadi genel bir kanal için.
text GereklidiziMesaj metni, varlık ayrıştırmasından sonra 1 ila 4096 karakter.
ayrıştırma_modu İsteğe bağlıdiziMarkdownV2 veya HTML, metindeki kalın, bağlantı ve kod biçimlendirmesini uygulamak için.
bildirimi_devre_disa_birak İsteğe bağlıboolMesajı, anında bildirim sesi olmadan sessizce gönderir.
yanıt_parametreleri İsteğe bağlısözlükMesajı, sohbetteki mevcut bir mesaja yanıt olarak gönderir.


Bot sınırının ötesine geçin
Kod Eğitimi

python-telegram-bot ile Python'da Telegram Bot API

Çiğ istekleri aramalar tek bir giden mesaj için sorunsuz çalışıyor. Bunun ötesinde, çoğu Python kod tabanı şunu sarmalar: Telegram Bot API'si içinde python-telegram-bot, aynı HTTP uç noktalarını, yerleşik güncelleme yoklamasına sahip asenkron bir Python nesne modeline dönüştüren bir kütüphane.
Kütüphanenin ham isteklere (requests) kıyasla ekledikleri
Bir Uygulama güncelleme döngüsünü sizin için yöneten nesne (yoklama veya webhook)
Tür güvenli metotlar gibi bot.send_message() elle oluşturulmuş JSON veri yükleri yerine
Komut ve mesaj işleyicileri, yani yanıtlama /başla bir döngü değil, bir dekoratördür
Parametreler yukarıda ele alınanlarla aynıdır: chat_id, text, ayrıştırma_modu. Kütüphane hâlâ bir botun bir kullanıcıya ilk mesajı atmasını sağlayamaz; bu kısıtlama, onu çağırmak için kullandığınız istemcide değil, Telegram'ın platform kurallarında yer almaktadır.



bot.py
itibaren telgraf İthalat Güncelleme itibaren telegram.ext İthalat ApplicationBuilder, CommandHandler, ContextTypes Eşzamansız fonksiyon başla(update: Update, context: ContextTypes.DEFAULT_TYPE): bekliyor context.bot.mesaj_gönder( chat_id=update.effective_chat.id, metin="python-telegram-bot'tan merhaba", parse_mode="MarkdownV2" ) uygulama = ApplicationBuilder().belirteç("123456:ABC-your-bot-token").inşa etmek() app.add_handler(Komut İşleyicisi("başla", başlat)) uygulama.ankete_başla()
İstemci API'sı / MTProto

Python'da gerçek bir kullanıcı hesabı: Telethon ve Pyrogram

Python'dan bir bot olarak değil, gerçek bir Telegram hesabı olarak gönderim yapmak, şu araçla İstemci API'si üzerinden gitmek anlamına gelir: api_id ve api_hash my.telegram.org sitesinden. İki Python kütüphanesi MTProto’nun ağır iş yükünü üstleniyor: Telethon ve Pyrogram.
Python

Telethon

async/await etrafında kurulmuş, ham protokol çağrıları yerine saf Python'a yakın bir istemci API'sine sahip, saf Python bir MTProto uygulaması.
Python

Pyrogram

Oturum yönetimi konusunda kendine özgü bir yaklaşımı olan ve bir protokol kütüphanesinden ziyade geleneksel bir SDK gibi hissettirmek için tasarlanmış bir istemci yüzeyine sahip başka bir Python MTProto istemcisi.



telethon_client.py
itibaren telethon İthalat TelegramClient itibaren telethon.errors İthalat SessionPasswordNeededError api_id = 1234567 api_hash = "my.telegram.org_adresinden_alacaginiz_api_hash_degeriniz" # "my_account", diskteki oturum dosyasının adıdır ve her çalıştırmada yeniden kullanılır müşteri = TelegramClient("hesabım", api_id, api_hash) Eşzamansız fonksiyon ana(): bekliyor müşteri.başla(telefon="+15551234567") bekliyor müşteri.mesaj_gönder("kullanıcı_adı_veya_id", "Telethon'dan merhaba") ile müşteri: client.loop.tamamlanana_kadar_çalıştır(main())
Her kendi yapımınız giriş ekranının aşması gereken 2FA engeli
1
Giriş kodunu gönder
client.start(phone=...) dürüm auth.sendCode, telefon numarasına bir giriş kodu gönderen ve döndüren phone_code_hash bir sonraki arama için kullanıldı.
2
Kodu doğrula
Kütüphane kod için bilgi isteminde bulunuyor ve çağırıyor auth.signIn bununla. Mutlu yol (happy-path) uygulamalarının bittiği yer tam olarak burasıdır.
3
OTURUM_PAROLASI_GEREKLI
Hesapta iki aşamalı doğrulama etkinleştirilmişse Telegram şu yanıtı verir: 400 hatası: SESSION_PASSWORD_NEEDED. Telethon bunu şu şekilde gündeme getiriyor: SessionPasswordNeededError, yakalanıp göz ardı edilecek bir hata değil, beklenen bir dal.
4
Bulut şifresiyle onaylat
Hesabın bulut şifresini şuraya geçirme: client.start(password=...) SRP değişimini çalıştırır ve auth.checkPassword sizin için. Ham MTProto katmanını doğrudan çağırmak, şunu oluşturmak anlamına gelir: InputCheckPasswordSRP itiraz et.
Oturumu kalıcı hale getirin veya her çalıştırmada oturum açın
Telethon ve Pyrogram, yerel bir oturum dosyası (veya bellek içi) yazar. StringSession) ilk başarılı oturum açmadan sonra. Onu kaybedin veya kalıcı hale getirmeden dağıtın; komut dosyanız her yeniden başlatmada telefon kodu ve 2FA akışını yeniden çalıştırmak zorunda kalacaktır.
Bu yolda karşılaşabileceğiniz hatalar
OTURUM_PAROLASI_GEREKLİ
GEÇERSİZ_ŞİFRE_ÖZETİ
API_ID_YAYINLANDI_AKIN
Yalnızca Telegram'ın kendi resmi uygulamaları Firebase tabanlı SMS kodu teslimi alır. Bir Python betiğinin de kendi (kod teslimine) ihtiyacı var api_id my.telegram.org adresinden: açık kaynaklı örnek kodda verilen örnek ID'yi yeniden kullanmak tetikler API_ID_YAYINLANDI_AKIN son kullanıcılarınız için ve sadece bir tane api_id telefon numarası başına verilir.
Unipile yaklaşımı
Unipile tarafından sunulan Telegram yeteneklerinin tam listesi için bkz. Telegram API ürün sayfası.

Python'da MTProto yazmadan gerçek bir Telegram hesabı

Unipile Python SDK, mevcut bir Telegram kullanıcı hesabını Telegram'ın kendi Cihazlar özellik, ister QR kod taraması veya şu özellikle Barındırılan Kimlik Doğrulama sağlayıcılar: "TELEGRAM". Yok. api_id, kalıcı hale getirilecek oturum dosyası yok ve OTURUM_PAROLASI_GEREKLİ kendinize yazılacak dal: bağlı hesap ya da şu şekilde görünüyor bağlı ya da etmez.
Bir hesap bağlandıktan sonra, Python'dan mesaj göndermek, tamamı Unipile üzerinde çalışan birkaç SDK çağrısından ibarettir v2 Alttaki API. Sohbeti başlat bağlı hesabın kimliğini ve bir kullanıcı_idleri liste, alıcı ile halihazırda bir sohbet varsa ya yeni bir sohbet açar ya da mevcut olanı teslim eder.
Hayır api_id / api_hash istekte bulunmak veya döndürmek için eşleştir
Kodunuzda oturum dosyası yok, SRP el sıkışması yok, 2FA dalı yok
Grup katılımcı yönetimi için aynı hesap durumu yönetimi
SDK'nın kurulumu burada ele alınmamıştır, çünkü en doğru paket adı güncel belgelerden teyit edilmelidir, bkz. developer.unipile.com/docs/getting-started kurulum adımı ve tam Python referansı için.
Burada gösterilen her bir yetenek uç nokta uç nokta listelenmiştir: Unipile Telegram API ürün sayfası, neyin desteklenip neyin desteklenmediği dahil.



send_telegram.py
İthalat unipile yapılandırma = unipile.Yapılandırma() configuration.api_key["API anahtarı"] = "api anahtarı" api_istemcisi = unipile.ApiClient(yapılandırma) mesajlaşma_api = unipile.Mesajlaşma API'si(api_istemcisi) sohbet = mesajlaşma_api.Sohbeti başlat( "acc_123456789", {"kullanici_idleri": ["0123456789"], "metin": "Merhaba, talebinizle ilgili takipteyim."} )
Unipile Telegram entegrasyonunun kapsamadığı şeyler
Kanallar, topluluklar ve yayınlar
Grup yönetimi: üyeleri onaylama veya terfi ettirme
Sohbeti arşivleme
Sesli ve görüntülü aramalar
Python SDK ile geliştirme yapın
Hatalar ve sınırlar

Python'da hataları ve oran sınırlarını (rate limit) yönetme

Test sohbetinde tek bir mesaj gönderen bir betik ile canlı ortamda çalışan bir betik farklı sorunlarla karşılaşıyor. İkincisi sonunda bir 429 veya bir SEL_BEKLEME_SÜRESİ_X, ve Python kodunuzun bundan sonra ne yaptığı, bunun beş saniyelik bir duraklama mı yoksa yasaklanmış bir hesap mı olacağını belirler.
1/san
Aynı bireysel sohbete gönderilebilecek maksimum Bot API mesajı
dk/20
Tek bir gruptaki maksimum Bot API mesajı
~30/sn
Sohbetler arasında yayın yaparken yaklaşık Bot API sınırı
429
Bu limitlerden herhangi biri aşıldığında dönen durum
API'nin her iki tarafı için yeniden deneme döngüleri
Bot API ve İstemci API'si, aynı sorunu iki farklı biçimde bildirir. Her ikisinin de körü körüne loglanıp yeniden denenmesi değil, açıkça yakalanması gerekir.



bot_api_retry.py
İthalat zaman İthalat istekleri fonksiyon yeniden_dene_ile_gönder(url, payload, max_retries=3): için deneme içinde menzil(maksimum_denemeler): r = istemler.POST(url, json=payload) eğer r.status_code != 429: return r tekrar_deneme_suresi = r.json().olsun("parametreler", {}).olsun("yeniden_dene", 1) Zaman.uyku(yeniden_deneme_süresi) yükseltmek Çalışma Zamanı Hatası("çok fazla 429 yanıtı")



telethon_flood_wait.py
itibaren telethon.errors İthalat Sel Bekleme Hatası İthalat asyncio Eşzamansız fonksiyon güvenli_gönder(müstamili, varlık, metin) denemek: bekliyor müşteri.mesaj_gönder(varlık, metin) hariç Sel Bekleme Hatası olarak e: # e.saniye, Telegram’ın geri gönderdiği FLOOD_WAIT_X değeridir bekliyor asenkron.uyku(e.seconds) bekliyor müşteri.mesaj_gönder(varlık, metin)
Sizi baştan sınırların altında tutan tempo rehberliği
Şuradan yüksek hacimli gönderim yapmaktan kaçının: yepyeni hesaplar, köklü olanlara kıyasla daha hızlı işaretlenirler.
Gönderim hacmini artırın giderek bir betiği tam kapasiteyle başlatmak yerine.
En azından tut 10 ila 20 saniye aynı hesaptan gönderilen mesajlar arasında bu, yalnızca bir Bot API üst sınırı değil, bağlı hesaplar için Unipile'ın kendi tavsiyesidir.
Özet

Python Telegram Bot API vs Telethon/Pyrogram vs Unipile SDK

Aynı özet tablo biçiminde: her bir Python yolunun gerçekten ne gerektirdiği ve nerede durduğu.
BoyutBot API (requests / python-telegram-bot)Telethon / Pyrogram (MTProto)Unipile Python SDK
Bir kullanıcıya ilk mesajı gönderebilirHayırEvet, gizliliğe bağlıEvet
Kurulum gereksinimiBotFather'dan bot token'ıapi_id / api_hash my.telegram.org adresindenQR kod veya Barındırılan Kimlik Doğrulama ile bağlanan hesap
Oturum yönetimiToken tabanlı, kalıcı hale getirilecek hiçbir şey yokOturum dosyasını kendiniz kalıcı hale getiriyorsunuzTelegram'ın kendi Cihazlar özelliğiyle yönetilir
2FA / OTURUM_ŞİFRESİ_GEREKLİGeçerli değilSRP değişimini sen yönetirsinSizin için halledildi
Grup katılımcıları (görüntüle / ekle / çıkar)Bot izinleriyle sınırlıdırEvet, kendim yaptımEvet, özel v2 uç noktaları
Kanallar, topluluklar, yayınlarEvet, yönetici olarak eklenirseEvetDesteklenmiyor
En iyisiBildirimler ve destek botlarıTamamen özel bir Python MTProto istemcisiMTProto'ya sahip olmadan hızlı bir şekilde kargo gönderimi
Bir kullanıcıya ilk mesajı gönderebilir
Bot APIHayır
Telethon / PyrogramEvet, gizliliğe bağlı
Unipile SDKEvet
Kurulum gereksinimi
Bot APIBot belirteci
Telethon / Pyrogramapi_id / api_hash
Unipile SDKBağlı hesap
Oturum yönetimi
Bot APIKalıcı hale getirilecek bir şey yok
Telethon / PyrogramKendi kendine kalıcı hale gelen oturum
Unipile SDKCihazlar üzerinden yönetilen
2FA / OTURUM_ŞİFRESİ_GEREKLİ
Bot APIGeçerli değil
Telethon / PyrogramKendi kendine kurulan SRP
Unipile SDKSizin için halledildi
Grup katılımcıları (görüntüle / ekle / çıkar)
Bot APIBot izinleriyle sınırlıdır
Telethon / PyrogramKendi kendine inşa edilen
Unipile SDKÖzel v2 uç noktaları
Kanallar, topluluklar, yayınlar
Bot APIEvet, yönetici olarak
Telethon / PyrogramEvet
Unipile SDKDesteklenmiyor
En iyisi
Bot APIBildirimler, destek botları
Telethon / PyrogramTamamen özel istemci
Unipile SDKHızlı kargo, MTProto yok

Python'da Telegram API - SSS

Python Telegram Bot API, python-telegram-bot, Telethon, Pyrogram hakkında sık sorulan sorular ve Unipile ile gerçek bir hesabı bağlama.

Evet. Telegram Bot API'si düz bir HTTP arayüzüdür, bu yüzden tek bir POSTA Python ile istek istekleri kütüphaneye https://api.telegram.org/bot<TOKEN>/sendMessage, ile bir chat_id ve text JSON gövdesinde olması yeterlidir. Bu çağrı için hiçbir SDK veya sarmalayıcı kütüphane gerekmez.

Bu Telegram Bot API'si Telegram'ın Python ile çağrılabilen kendi HTTP arayüzü, istekleri veya herhangi bir HTTP istemcisi. python-telegram-bot asenkron bir nesne modelindeki aynı HTTP uç noktalarını sarmalayan üçüncü taraf bir Python kütüphanesidir, bir Uygulama sınıf, ... gibi türü belirlenmiş metodlar bot.send_message, ve yerleşik güncelleme yoklama (polling) veya webhook yönetimi.

Bu, kodunuzdaki bir hata değil, Bot API'nin yapısal bir kuralıdır. Bir bot çağrı yapamaz sendMessage karşı chat_id o kullanıcı bota ilk başta en az bir mesaj gönderene kadar. Hiçbir parametre veya Python kütüphanesi bunu aşamaz. Telethon, Pyrogram veya başka bir araç aracılığıyla gerçek bir bağlı Telegram hesabı, Unipile SDK, bu kısıtlamaya sahip değildir.

Hayır. Bot API, yalnızca BotFather tarafından verilmiş bir bot belirtecine (token) ihtiyaç duyar. api_id ve api_hash my.telegram.org adresinden alınan bilgiler, Telethon, Pyrogram ve bir bot yerine gerçek bir kullanıcı hesabı olarak oturum açan herhangi bir istemci tarafından kullanılan protokol olan İstemci API'si (MTProto) için gereklidir.

OTURUM_PAROLASI_GEREKLİ Telegram'dan dönen bir 400 hatasıdır auth.signIn hesap iki aşamalı doğrulamayı etkinleştirdiğinde. Telethon bunu şu şekilde fırlatır: SessionPasswordNeededError. Temizlemek, SRP protokolünü çalıştırmak ve şunu çağırmak anlamına gelir: auth.checkPassword Telethon ve Pyrogram'ın her ikisinin de şifreyi oturum açma yöntemine geçirdiğinizde işlediği, hesabın bulut şifresiyle.

Bot API döndürür: 429 Durum, aynı sohbete saniyede yaklaşık bir mesajı, bir grupta dakikada 20 mesajı veya sohbetler arası yayın yaparken saniyede yaklaşık 30 mesajı aştığınızda ortaya çıkar. Yanıt şunları içerir: tekrar_deneme_suresi saniye cinsinden değer. MTProto tarafında bunun karşılığı 420 TAŞKINI hata veya SEL_BEKLEME_SÜRESİ_X istisna; burada X, yeniden denemeden önce beklenecek saniye sayısıdır.

Evet. Unipile Python SDK Mevcut bir Telegram kullanıcı hesabını, Telegram'ın kendi Cihazlar özelliği aracılığıyla (bir QR kod taraması veya Barındırılan Kimlik Doğrulama ile) bağlar ve mesajlaşmayı, örneğin şu gibi birkaç SDK çağrısı yoluyla sunar: Sohbeti başlat. Yok. api_id talep etmek için, MTProto uygulaması yok ve kendinizin yazacağı bir oturum dosyası veya 2FA dalı yok.

Grup katılımcısı yönetimi desteklenmektedir: özel olarak listeleme, ekleme ve çıkarma işlemleri v2 uç noktaları. Kanallar, topluluklar, yayınlar, üyeleri onaylama veya terfi ettirme gibi grup yönetim eylemleri, sohbet arşivleme ve sesli veya görüntülü aramalar desteklenmez.

Hala sorularınız mı var? Ekibimiz yardım etmek için burada.

Bir uzmanla konuşun
Doğru şekilde Telegram API Python

Unipile ile Telegram bot API Python entegrasyonunuzu oluşturun

MTProto oturum dosyalarını atlayın, yalnızca bot olma kısıtlamasını atlayın. Mevcut bir Telegram hesabını Unipile'ın Python SDK'sı aracılığıyla bağlayın ve bunu WhatsApp, LinkedIn, Instagram, Gmail, Outlook ve IMAP ile tek bir API'de birleştirin.
tr_TRTR