Telegram Bot API proxy üzerinden: uzun polling, webhook ve 429 hatası yönetimi

Giriş: bu rehberden ne kazanacaksınız

Telegram'da bir bot çalıştırdıysanız, hoş olmayan bir gerçeği biliyorsunuzdur. Botun kendisi bir akşamda yazılır, ama istikrarlı çalışması ayrı bir projeye dönüşür. Mesajlar gecikmeli gelir, güncellemeler kaybolur, sunucu birden 429 hatası alır ve webhook açıklama olmadan çağrılmayı bırakır. Üstüne tüm isteklerin geçmesi gereken bir proxy ekleyin, hata noktalarının sayısı ikiye katlanır.

Bu adım adım rehber tam da bu sorunları çözüyor. Telegram Bot API'yi proxy sunucusu üzerinden öyle kullanmayı öğreneceksiniz ki bot çökmeyecek, mesaj kaybetmeyecek ve limitlere doğru tepki verecek. MTProto protokolünü incelemeyeceğiz ve proxy izleme sistemi kurmayacağız. Konumuz daha dar ve daha pratik: proxy üzerinden api.telegram.org'a HTTP istekleri, güncellemeleri alma yöntemleri ve kısıtlamalara doğru tepki.

Sonunda ne elde edeceksiniz

• Telegram Bot API'ye proxy'niz (HTTP veya SOCKS5) üzerinden istek gönderen çalışan bir bot.
• Zaman aşımlarında kopmayan ve mesajları çiftlemeyen yapılandırılmış uzun polling.
• Sunucunuzda güncellemeleri alan HTTPS ve gizli token ile webhook.
• 429 hatasında gereken süreyi kendisi bekleyen ve isteği tekrarlayan hazır bir istek sarmalayıcısı.
• Projeniz için hangi modu seçmeniz gerektiğini anlama: polling mi webhook mu.

Bu rehber kimin için

Kampanyalar için gönderim, lead bildirimleri ve istatistik botları toplayan pazarlamacılar ve arbitrajcılar için. Sunucu istekleri için sabit ve öngörülebilir bir giden IP'ye ihtiyaç duyan geliştiriciler için. Botları müşterilere hizmet veren ve bir saat boyunca susma hakkı olmayan işletme sahipleri için. Mobil proxy'lerle çalışıyorsanız ve bot trafiğini onların üzerinden geçirmek istiyorsanız, doğru yerdesiniz.

Önceden bilmeniz gerekenler

Her adımı sıfırdan açıklıyoruz, ama birkaç temel beceri hayatınızı çok kolaylaştırır. Terminal veya komut satırını açabilmek, komutları kopyalayıp Python betikleri çalıştırabilmek faydalıdır. HTTP isteği ve JSON'un ne olduğunu bilmek tercih edilir, ama basit kelimelerle hatırlatacağız. İleri düzey konular ayrı bir bölüme taşındı, yeni başlayanlar sonuç kaybetmeden onu atlayabilir.

Ne kadar zaman gerekir

Hazırlık ve bot oluşturma yaklaşık 20 dakika sürer. Proxy yapılandırması ve ilk başarılı istek 20-30 dakika daha. Uzun polling'i yarım saatte başlatırsınız. Webhook 40-60 dakika ister, çünkü HTTPS sertifikası gerekir. 429 hatası yönetimi 20 dakika daha ekler. Toplamda her adımda kontrollerle birlikte iki ila üç saatlik rahat bir çalışma.

Ön hazırlık: araçlar ve erişimler

İlk kod satırını yazmadan önce gereken her şeyi toplayalım. Böylece adımın ortasında kesintiye uğrayıp proxy şifresini nereden alacağınızı veya kütüphaneyi nasıl kuracağınızı aramayacaksınız.

Gerekli araçlar ve erişimler

1. Telegram hesabı ve bağlı bir telefon numarası. Bununla resmi BotFather botu üzerinden bot oluşturacaksınız.
2. Proxy erişimi: sunucu adresi, port, kullanıcı adı ve şifre. mobileproxy.space kişisel panelinde bu bilgiler satın aldığınız proxy'nin kartında görünür. Genellikle iki port sunulur: biri HTTP bağlantısı, diğeri SOCKS5 için. İkisini de not edin.
3. Python 3.10 veya üstü kurulu bir bilgisayar ya da sunucu. Webhook için genel IP adresli ve alan adlı bir sunucu gerekir, ev bilgisayarında webhook çalışmaz.
4. curl aracı. Windows 10 ve 11, macOS ve Linux'ta zaten yerleşiktir. curl --version komutuyla kontrol edin.
5. Metin düzenleyici: VS Code, Notepad++ veya kod yazmak için rahat olan herhangi biri.

Sistem gereksinimleri

Polling için neredeyse hiç gereksinim yok: internet erişimi olan herhangi bir makine, dizüstü dahil. Bot birkaç düzine megabayt bellek tüketir. Webhook için minimum yapılandırmalı bir VPS gerekir: 1 çekirdek, 1 GB RAM, Ubuntu 22.04 veya 24.04. Sunucunun IP'sine yönlendirilmiş bir alan adı ve güvenlik duvarında açık 443 portu zorunludur.

Ne kurmalı

1. Terminali açın.
2. Python'u python3 --version komutuyla kontrol edin. Windows'ta komut python --version olabilir.
3. Proje klasörü oluşturun: mkdir tgbot-proxy, ardından içine girin cd tgbot-proxy.
4. Sanal ortam oluşturun: python3 -m venv venv. Etkinleştirin: Linux ve macOS'ta source venv/bin/activate, Windows'ta venv\Scripts\activate.
5. Kütüphaneleri kurun: pip install requests[socks] flask. requests paketi Telegram Bot API'ye isteklerden sorumludur, socks eklentisi SOCKS5 protokollü proxy için gereklidir ve Flask webhook'u karşılar.

Yedekler ve veri güvenliği

Bot tokenını banka uygulamanızın şifresi gibi düşünün. Onu ele geçiren kişi botunuz adına müşterilerinize yazabilir. Token ve proxy verilerini içeren bir .env dosyası oluşturun ve asla genel bir depoya göndermeyin. Bot zaten çalışıyorsa ve onu proxy'ye taşıyorsanız, mevcut yapılandırmayı kaydedin, varsa veritabanını yedekleyin ve getWebhookInfo yönteminin sonucunu not edin. Böylece geri dönüş iki dakika sürer.

İpucu: Deneyler için ayrı bir test botu oluşturun. Bu rehberdeki tüm adımları önce onun üzerinde uygulayın, canlı bota yalnızca test edilmiş yapılandırmayı taşıyın. Böylece gerçek müşterilerle iletişimi bozmazsınız.

Temel kavramlar: Telegram Bot API nasıl çalışır

Anahtar terimleri basit kelimelerle açıklayalım. Onlar olmadan sonraki adımlar sihir gibi görünür, onlarla mantıklı ve öngörülebilir hale gelir.

Telegram Bot API

Bu sıradan bir HTTP arayüzüdür. Kodunuz https://api.telegram.org/bot<TOKEN>/<metot> biçimindeki adrese istek gönderir ve Telegram sunucusu JSON nesnesiyle yanıt verir. Örneğin getMe yöntemi bot hakkında bilgi döndürür, sendMessage ise sohbete metin gönderir. Çalışmak için özel kütüphane gerekmez, curl veya requests yeterlidir. İşte bu yüzden Telegram Bot API'yi proxy üzerinden geçirmek çok kolaydır: bu HTTPS üzerinden herhangi bir siteyle aynı trafiktir.

Güncellemeler (updates)

Bot için her olay, ister mesaj, ister buton tıklaması, ister gruba eklenme olsun, benzersiz update_id numaralı bir update nesnesi olarak gelir. Numaralar sırayla artar. Kodunuzun görevi bu nesneleri alıp işlemektir. Alma yöntemi tam olarak iki tanedir ve birbirini dışlar.

Uzun polling (long polling)

Botunuz Telegram'a kendisi sorar: benim için yeni güncelleme var mı? Bunu getUpdates yöntemiyle yapar. "Uzun" kelimesi, sunucunun hemen boş liste döndürmediği, bağlantıyı belirtilen zaman aşımına kadar, genellikle 30-60 saniye açık tuttuğu ve bir olay oluşur oluşmaz yanıt verdiği anlamına gelir. Bu isteklerden tasarruf sağlar ve neredeyse anlık tepki verir. Polling genel adres gerektirmez, router arkasından ve herhangi bir proxy üzerinden çalışır. Başlangıç ve küçük yüklü botlar için idealdir.

Webhook

Ters yaklaşım. Sunucunuzun adresini setWebhook yöntemiyle Telegram'a bildirirsiniz ve Telegram her güncellemeyi bu adrese POST isteğiyle kendisi gönderir. Hiçbir şeyi sorgulamanıza gerek yok. Gereksinimler: genel alan adı, HTTPS sertifikası ve 443, 80, 88 veya 8443 portlarından biri. Webhook daha iyi ölçeklenir ve beklemeye kaynak harcamaz.

Önemli: Proxy yalnızca botunuzun Telegram'a giden isteklerini etkiler. Webhook'un gelen istekleri doğrudan sunucunuza gelir ve proxy bu zincirde yer almaz. Bu nedenle "proxy üzerinden webhook" ifadesi pratikte şu anlama gelir: bot yanıtları ve API çağrılarını proxy üzerinden yapar, güncellemeleri ise kendi genel adresinde alır.

429 Too Many Requests hatası

Telegram istek sıklığını sınırlar. 2026 için referanslar: bir sohbete saniyede birden fazla mesaj değil, bir gruba dakikada 20'den fazla mesaj değil ve bot genelinde toplam saniyede yaklaşık 30 mesaj. Aşıldığında sunucu HTTP 429 durumu ve yanıt gövdesinde parameters.retry_after alanıyla beklenecek saniye sayısını döndürür. Bunu görmezden gelmek olmaz: duraklama olmadan tekrar denemeler kilit süresini artırır.

Bot için proxy neden gerekli

Nedenler tamamen pratik. Birincisi, sabit ve öngörülebilir giden IP: sunucular çok, ama dış adres tek olması gerektiğinde kullanışlı. İkincisi, trafiği projelere göre ayırma: her müşteri veya her kampanya için ayrı kanal. Üçüncüsü, tüm dış bağlantıların bir ağ geçidinden geçmesi gereken kurumsal politikalar. Mobil proxy'ler burada istikrar ve zamanlanmış veya bağlantı ile IP değiştirme yeteneğiyle değerlidir.

Adım 1: Botu oluşturup tokenı alıyoruz

Bu aşamanın amacı: Telegram Bot API erişim tokenını almak ve botun var olduğundan emin olmak.

1. Telegram'ı telefon veya bilgisayarda açın.
2. Arama alanına BotFather yazın. Mavi doğrulama onaylı botu seçin, sahtelerinde onay yoktur.
3. Start düğmesine basın veya /start komutunu gönderin. Mevcut komutların listesini göreceksiniz.
4. /newbot komutunu gönderin.
5. BotFather bot adı isteyecek. Görünen adı girin, örneğin Proxy Test Bot. Boşluk ve Türkçe karakter içerebilir.
6. Ardından username isteyecek. Benzersiz, Latin harflerle ve bot ile bitmeli, örneğin proxy_test_2026_bot. Ad alınmışsa BotFather bunu bildirir, başka bir ad düşünün.
7. Yanıt olarak tebrik mesajı ve 123456789:AAExampleTokenLettersAndDigits biçiminde bir satır gelir. Bu tokendır. İki nokta üst üste öncesi rakamlar dahil tamamını kopyalayın.
8. Proje klasöründe .env dosyası oluşturun ve içine BOT_TOKEN=sizin_tokeniniz satırını yazın.

Dikkat: Tokenı asla sohbetlerde, ekran görüntülerinde ve açık depolarda yayınlamayın. Token sızdıysa derhal BotFather'a /revoke komutunu gönderin, botu seçin ve yeni token alın. Eskisi hemen çalışmayı durdurur.

Proxy olmadan ilk istek

Şemayı karmaşıklaştırmadan önce tokenın çalıştığını makinenizden sıradan bir istekle doğrulayalım. Terminalde kendi tokenınızı yerleştirerek çalıştırın:

curl https://api.telegram.org/bot123456789:AAExampleToken/getMe

Beklenen yanıt: {"ok":true,"result":{"id":123456789,"is_bot":true,... ile başlayan JSON. İçinde az önce düşündüğünüz bot username'ini göreceksiniz.

Kontrol: Yanıtta "ok":true ve doğru username var. Bunun yerine "error_code":401 geldiyse token hatalı kopyalanmıştır, kenarlardan karakter kaybolup kaybolmadığını kontrol edin.

Olası sorunlar

• Username alınmış. Rakam veya proje kısaltması ekleyin, önemli olan bot sonunu korumak.
• BotFather yanıt vermiyor. Doğrulama onaylı botu açtığınızdan emin olun, adaşı değil.
• 404 Not Found hatası. Adreste token öncesi bot kelimesi eksik. Biçim kesinlikle /bot<TOKEN>/metot.

Adım 2: Proxy'yi bağlıyoruz ve API erişimini kontrol ediyoruz

Bu aşamanın amacı: Telegram Bot API'ye isteklerin proxy'nizden geçmesini sağlamak ve bunu sözde değil fiilen doğrulamak.

Proxy adres biçimini anlıyoruz

Proxy tek satırla tanımlanır: protokol://kullanıcı:şifre@host:port. Verileri kişisel panelden alın. Diyelim ki size host proxy-host, HTTP portu 8080, SOCKS5 portu 1080, kullanıcı adı user ve şifre pass verildi. O zaman satırlar şöyle olur:

• HTTP proxy: http://user:pass@proxy-host:8080
• SOCKS5 proxy: socks5h://user:pass@proxy-host:1080

socks5h içindeki h harfine dikkat edin. Bu, api.telegram.org alan adının makinenizde değil proxy tarafında çözüleceği anlamına gelir. Mobil proxy'ler için doğru seçenek budur: DNS istekleri ve trafik aynı yoldan gider. h olmadan yerel DNS sorunlarında istekler proxy sağlam olsa bile başarısız olur.

Şifrede @, : veya / karakterleri varsa kodlanmalıdır: @ %40 olur, iki nokta %3A, eğik çizgi %2F. Aksi halde satır yanlış ayrıştırılır.

curl ile kontrol

1. Önce dış servislerin proxy'niz üzerinden hangi IP'yi gördüğünü öğrenin. Çalıştırın: curl -x http://user:pass@proxy-host:8080 https://api.ipify.org. Yanıtta bir IP adresi gelir. Bu, ev veya sunucu adresinizden farklı olmalıdır.
2. Şimdi Telegram Bot API'ye aynı istek: curl -x http://user:pass@proxy-host:8080 https://api.telegram.org/bot123456789:AAExampleToken/getMe.
3. SOCKS5 için parametreyi değiştirin: curl -x socks5h://user:pass@proxy-host:1080 https://api.telegram.org/bot123456789:AAExampleToken/getMe.
4. Yanıt süresini ölçün: komut sonuna -w " süre: %{time_total}" ekleyin. Mobil proxy için 1-2 saniyeye kadar değer normaldir.

Kontrol: İki istek de "ok":true döndürdü ve ilk komuttan gelen IP kendinizinkinden farklı. Bu, proxy üzerinden yolun çalıştığı ve Telegram Bot API'nin bu yoldan yanıt verdiği anlamına gelir.

Python'da proxy yapılandırması

Değerleri kendinizinkiyle değiştirerek config.py dosyasını oluşturun:

import os
TOKEN = os.getenv('BOT_TOKEN', '123456789:AAExampleTokenReplaceMe')
PROXY = os.getenv('BOT_PROXY', 'http://user:pass@proxy-host:8080')
PROXIES = {'http': PROXY, 'https': PROXY}
BASE = f'https://api.telegram.org/bot{TOKEN}'

Sözlükteki https anahtarı zorunludur, çünkü Telegram Bot API yalnızca HTTPS üzerinden çalışır. Yeni başlayanların sık hatası yalnızca http belirtip trafiğin neden doğrudan gittiğine şaşırmaktır.

Şimdi test betiği check.py:

import requests
from config import PROXIES, BASE
ip = requests.get('https://api.ipify.org', proxies=PROXIES, timeout=15).text
print('Giden IP:', ip)
me = requests.get(f'{BASE}/getMe', proxies=PROXIES, timeout=15).json()
print('Bot:', me['result']['username'])

Çalıştırın: python check.py. Ekranda proxy IP'si ve bot username'i görünecek.

İpucu: Zaten kullandığınız kütüphanenin kodunu değiştirmek istemiyorsanız, HTTPS_PROXY=http://user:pass@proxy-host:8080 ortam değişkenini tanımlayın. requests kütüphanesi ve çoğu HTTP istemcisi onu otomatik alır. Bu, mevcut botu kod değişikliği olmadan proxy'ye taşımanın kullanışlı yoludur.

Popüler çatılarda yapılandırma

• aiogram 3.x: AiohttpSession(proxy='http://user:pass@proxy-host:8080') oturumu oluşturun ve Bot(token=TOKEN, session=session) oluştururken iletin. SOCKS5 için aiohttp-socks paketi gerekir.
• python-telegram-bot 21.x: HTTPXRequest(proxy='http://user:pass@proxy-host:8080') kullanın ve ApplicationBuilder().token(TOKEN).request(request) içine iletin.
• Node.js: https-proxy-agent veya socks-proxy-agent paketi, HTTP istemcisinin seçeneklerine veya bot kütüphanesinin kurucusuna iletilen bir ajan oluşturur.

Olası sorunlar

• 407 Proxy Authentication Required. Yanlış kullanıcı adı veya şifre ya da özel karakterler kodlanmamış. Paneldeki verileri kontrol edin.
• Connection refused. Port yanlış veya HTTP ile SOCKS5 portları karışmış. Diğer portu deneyin.
• İstek doğrudan gidiyor. Sözlükte https anahtarı yok veya ortam değişkeni başka bir terminal penceresinde tanımlanmış.
• SSL hatası. Sertifika doğrulamasını kapatmayın. pip install -U certifi komutuyla certifi paketini güncelleyin ve sistem saatini kontrol edin.

Adım 3: Proxy üzerinden uzun polling başlatıyoruz

Bu aşamanın amacı: proxy üzerinden getUpdates yöntemiyle güncellemeleri alan ve mesajlara kaybetmeden, çiftlemeden yanıt veren çalışan bir bot elde etmek.

Polling döngüsü nasıl doğru kurulur

Mantık basit, ama ayrıntılar önemli. getUpdates'i offset parametresiyle çağırırsınız, değer son işlenen update_id artı birdir. Böylece Telegram önceki güncellemelerin alındığını anlar ve kendi tarafında siler. Offset'i unutursanız aynı mesaj tekrar tekrar gelir ve bot birkaç kez yanıt vermeye başlar.

timeout parametresi sunucunun olayları bekleyerek bağlantıyı kaç saniye açık tutacağını belirler. Proxy'ye özgü durum burada başlar. Her proxy'nin kendi boşta bağlantı zaman aşımı vardır, mobil proxy'lerde genellikle 60-120 saniye civarındadır. Polling zaman aşımı bundan büyükse proxy, Telegram yanıt vermeden bağlantıyı keser ve güncellemeler yerine hata alırsınız. HTTP istemcisi zaman aşımı 60 saniye iken güvenli değer timeout=50'dir. İstemci zaman aşımı her zaman polling zaman aşımından büyük olmalıdır, aksi halde istemci önce kopar.

Botu yazıyoruz

1. polling.py dosyasını oluşturun.
2. Aşağıdaki kodu kopyalayın.
3. python polling.py komutuyla çalıştırın.
4. Telegram'da bota herhangi bir mesaj yazın.

import time, requests
from config import PROXIES, BASE
offset = 0
print('Polling proxy üzerinden başlatıldı')
while True:
try:
r = requests.get(f'{BASE}/getUpdates', params={'offset': offset, 'timeout': 50}, proxies=PROXIES, timeout=60)
data = r.json()
except requests.RequestException as e:
print('Ağ hatası:', e)
time.sleep(3)
continue
if not data.get('ok'):
print('API hatası:', data)
time.sleep(3)
continue
for upd in data['result']:
offset = upd['update_id'] + 1
msg = upd.get('message')
if msg and 'text' in msg:
requests.post(f'{BASE}/sendMessage', json={'chat_id': msg['chat']['id'], 'text': 'Aldım: ' + msg['text']}, proxies=PROXIES, timeout=15)

Burada ne olduğunu inceleyelim. Dış döngü hiçbir zaman kendi kendine bitmez. try bloğu ağ hatalarını yakalar: proxy kopması, zaman aşımı, IP değişimi. Hata durumunda betik üç saniye bekleyip yeniden dener, çökmez. data.get('ok') kontrolü API düzeyindeki hataları yakalar. İç döngü her güncellemeyi işler ve offseti hemen kaydırır.

Kontrol: Konsolda başlatma satırı göründü ve mesaj gönderdikten sonra bot "Aldım: metniniz" diye yanıt verdi. Arka arkaya üç mesaj gönderin, bot her birine tam bir kez yanıt vermeli. Ctrl+C ile betiği durdurun, mesaj gönderin, yeniden başlatın: bot kaçırılan mesaja yanıt verecek, çünkü Telegram işlenmemiş güncellemeleri 24 saat saklar.

Polling'de mobil proxy özellikleri

Mobil proxy'ler IP adresini değiştirebilir: zamanlayıcıyla veya panelden özel bağlantıyla. IP değişim anında açık polling bağlantısı kopar. Bu kodunuzun hatası değil, ağın normal davranışıdır. Döngümüz buna zaten hazır: istisnayı yakalar, bekler ve aynı offsetten devam eder. Hiçbir güncelleme kaybolmaz.

Yine de sık rotasyon loglarda gereksiz gürültü ve mikro gecikmeler yaratır. Öneri: polling modundaki bot için panelde rotasyon aralığını 10 dakika ve üstü yapın ya da otomatik değişimi kapatıp IP'yi yalnızca gerçekten gerektiğinde bağlantıyla değiştirin. Bot bir kazıyıcı değildir, her dakika taze adrese ihtiyacı yoktur.

İpucu: Loga her güncellemenin zamanını ve update_id'sini ekleyin. Bir hafta sonra biri botun yanıt vermediğini söylediğinde mesajın kodunuza ulaşıp ulaşmadığını yoksa sorunun ağ tarafında mı olduğunu bir dakikada bulursunuz.

Olası sorunlar

• 409 Conflict hatası. En sık görülen. Bota webhook ayarlıdır ve polling ile webhook aynı anda çalışamaz. curl -x proxy_adresiniz https://api.telegram.org/botTOKEN/deleteWebhook komutunu çalıştırıp betiği yeniden başlatın. İkinci neden: iki kopya betik çalışıyor, fazlasını kapatın.
• Bot her mesaja iki kez yanıt veriyor. Offset kaymıyor veya iki kopya bot çalışıyor.
• Sürekli Read timed out. Polling zaman aşımı proxy zaman aşımından büyük. timeoutu 30-40 saniyeye düşürün.
• Yanıt gecikmesi 5-10 saniye. Proxy yanıt süresini curl ile kontrol edin. Kanalın kendisi yavaşsa çıkış noktasını veya tarifeyi değiştirin.

Adım 4: HTTPS ve gizli token ile webhook kuruyoruz

Bu aşamanın amacı: Telegram güncellemeleri sunucunuza kendisi gönderir, bot ise proxy üzerinden yanıt verir. Bu adım alan adlı VPS gerektirir, bu yüzden şu an yalnızca polling varsa ve sizi memnun ediyorsa 5. adıma geçip sonra buraya dönebilirsiniz.

Sunucu ve alan adı hazırlığı

1. Ubuntu'lu bir VPS kiralayın. Genel IP'sini not edin.
2. Alan adı panelinde sunucunun IP'sine işaret eden bir A kaydı oluşturun, örneğin bot.ornek.com. DNS güncellemesini bekleyin, genellikle 5-30 dakika. nslookup bot.ornek.com komutuyla kontrol edin.
3. SSH ile sunucuya bağlanın ve paketleri güncelleyin: sudo apt update.
4. nginx ve certbot kurun: sudo apt install nginx certbot python3-certbot-nginx.
5. 80 ve 443 portlarını açın: sudo ufw allow 80, sudo ufw allow 443.
6. Ücretsiz sertifika alın: sudo certbot --nginx -d bot.ornek.com. İpuçlarını izleyin, email girin, koşulları kabul edin. Bir dakika içinde sertifika verilir.

Telegram webhook'ları yalnızca güvenilir bir merkezden geçerli sertifikayla HTTPS üzerinden kabul eder. certbot sertifikası bu gereksinime uyar. Kendinden imzalı sertifika da mümkündür ama o zaman genel kısmını setWebhook'un certificate parametresiyle yüklemeniz gerekir ve bu ek zahmet yaratır. Yeni başlayanlar için certbot daha kolaydır.

nginx'i giriş noktası olarak yapılandırıyoruz

Nginx, Telegram'dan gelen HTTPS isteklerini kabul edip yerel 8080 portunu dinleyen Flask uygulamanıza iletecek. certbot'un oluşturduğu site yapılandırmasını sudo nano /etc/nginx/sites-available/default komutuyla açın ve 443 portlu server bloğunun içine şu location'ı ekleyin:

location /tg/webhook {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_read_timeout 30s;
}

Dosyayı kaydedin, sözdizimini sudo nginx -t ile kontrol edin ve yeniden yükleyin sudo systemctl reload nginx.

İpucu: Webhook yolunu belirsiz yapın, örneğin /tg/webhook/k8s7d2f. Bu gizli tokenın yerine geçmez, ek bir katmandır: rastgele tarayıcılar giriş noktanızı bulamaz.

Webhook işleyicisini yazıyoruz

Sunucuda webhook.py dosyasını oluşturun. Telegram'dan POST alır, gizli başlığı kontrol eder ve kullanıcıya proxy üzerinden yanıt verir. call fonksiyonunu bir sonraki adımda yazacağız, şimdilik proxies ile sıradan requests.post kullanın.

import requests
from flask import Flask, request, abort
from config import PROXIES, BASE
app = Flask(__name__)
SECRET = 'MySecret123'
@app.post('/tg/webhook')
def webhook():
if request.headers.get('X-Telegram-Bot-Api-Secret-Token') != SECRET:
abort(403)
update = request.get_json(silent=True) or {}
msg = update.get('message')
if msg and 'text' in msg:
requests.post(f'{BASE}/sendMessage', json={'chat_id': msg['chat']['id'], 'text': 'Webhook ile aldım'}, proxies=PROXIES, timeout=15)
return 'ok', 200
if __name__ == '__main__':
app.run(host='127.0.0.1', port=8080)

Kilit nokta: X-Telegram-Bot-Api-Secret-Token başlığı. Webhook kurarken secret_token belirttiyseniz Telegram bunu her isteğe ekler. Doğru değeri olmayan her istek 403 koduyla reddedilir. Böylece kimse bota sahte mesaj gönderemez.

Uygulamayı çalıştırın: python webhook.py. Kalıcı çalışma için sonradan systemd servisi yapın, ama kontrol için doğrudan çalıştırma yeterlidir.

Webhook'u proxy üzerinden kaydediyoruz

setWebhook çağrısı da proxy üzerinden gider, çünkü bu Telegram Bot API'ye giden bir istektir. Proxy erişimi olan herhangi bir makinede çalıştırın:

curl -x http://user:pass@proxy-host:8080 -F "url=https://bot.ornek.com/tg/webhook" -F "secret_token=MySecret123" -F "max_connections=40" -F "drop_pending_updates=true" https://api.telegram.org/bot123456789:AAExampleToken/setWebhook

Parametreleri inceleyelim. url — işleyicinizin adresi. secret_token — Latin harfleri, rakamlar, tire ve alt çizgiden oluşan 1 ile 256 karakter arası dizi; koddaki SECRET ile eşleşmelidir. max_connections — Telegram'ın size kaç eşzamanlı istek açabileceği, 1 ile 100 arası, varsayılan 40. drop_pending_updates — birikmiş güncellemeleri sıfırla, böylece geçiş anında bot eski yanıt yağmuru yapmaz.

Beklenen yanıt: {"ok":true,"result":true,"description":"Webhook was set"}.

getWebhookInfo ile teşhis

Bu, webhook hata ayıklamanın ana aracıdır. Çalıştırın:

curl -x http://user:pass@proxy-host:8080 https://api.telegram.org/bot123456789:AAExampleToken/getWebhookInfo

Yanıtta şu alanlara bakın: url sizinkiyle eşleşmeli, pending_update_count işlenmemiş güncelleme kuyruğunu gösterir, last_error_date ve last_error_message Telegram güncellemeyi teslim edemediğinde görünür. Test mesajı gönderdikten sonra hata alanı boşsa tam başarı anlamına gelir.

Kontrol: Bota yazın. "Webhook ile aldım" diye yanıt verdi. getWebhookInfo'da last_error_message yok ve pending_update_count sıfır. Flask loglarında POST /tg/webhook ve 200 kodlu satır görünüyor.

Dikkat: Webhook işleyicisi hızlı yanıt vermeli, birkaç saniye içinde. Kodunuz uzun düşünürse, örneğin veritabanına veya yavaş proxy üzerinden dış servise ağır istek yaparsa, Telegram teslimi başarısız sayar ve tekrarlar. Ağır işi arka plan görevine taşıyın, webhook'a hemen 200 döndürün.

Olası sorunlar

• last_error_message: SSL error. Sertifika geçerli değil, süresi dolmuş veya başka alan adına verilmiş. sudo certbot certificates komutuyla kontrol edin.
• Connection timed out. 443 portu güvenlik duvarında veya sağlayıcıda kapalı. sudo ufw status ve VPS panel ayarlarını kontrol edin.
• Wrong response from the webhook: 403. Koddaki ve setWebhook'taki gizli token eşleşmiyor. Harf büyüklüğünü kontrol edin.
• Wrong response from the webhook: 502. Flask çalışmıyor veya başka portu dinliyor. ss -tlnp | grep 8080 komutunu kontrol edin.
• Bad webhook: port not allowed. Yalnızca 443, 80, 88 veya 8443 kullanın.

Adım 5: 429 hatasını yönetiyoruz ve istekleri dayanıklı hale getiriyoruz

Bu aşamanın amacı: tüm Telegram Bot API çağrıları için tek bir fonksiyon yazmak; 429'da kendisi duraklayan, ağ ve proxy arızalarında isteği tekrarlayan ve botu asla çökertmeyen bir fonksiyon.

429 neden görmezden gelinemez

Bin kullanıcıya gönderim yaptığınızda saniyede 30 mesaj limiti anında doluyor. Telegram 429 ile yanıt verir ve retry_after belirtir. Sunucuya vurmaya devam ederseniz mesajlar gitmez ve sonraki yanıtlarda bekleme süresi artar. Proxy üzerinden çalışırken bir incelik var: Telegram limitleri IP'ye değil bota bağlıdır. Rotasyonla IP değiştirmek kısıtlamayı aşmaya yardımcı olmaz ve bunun için kullanılmamalıdır. Tek doğru yol retry_after'a saygı göstermek ve gönderim hızını kontrol etmektir.

Evrensel sarmalayıcıyı yazıyoruz

config.py veya ayrı bir api.py dosyasına şu fonksiyonu ekleyin:

import time, requests
from config import PROXIES, BASE
def call(method, payload, retries=6):
for attempt in range(retries):
try:
r = requests.post(f'{BASE}/{method}', json=payload, proxies=PROXIES, timeout=15)
except requests.RequestException as e:
print('Ağ veya proxy:', e)
time.sleep(min(2 ** attempt, 30))
continue
if r.status_code == 429:
wait = r.json().get('parameters', {}).get('retry_after', 1)
print('429 Too Many Requests, bekliyoruz', wait, 'sn'
time.sleep(wait + 0.5)
continue
if 500 <= r.status_code < 600:
print('Telegram sunucu hatası', r.status_code)
time.sleep(min(2 ** attempt, 30))
continue
data = r.json()
if not data.get('ok'):
print('API hatası:', data.get('description'))
return data
raise RuntimeError('Telegram Bot API: ' + method + ' için denemeler tükendi')

Bu fonksiyon ne yapar. Ağ hatasında üstel olarak bekler: 1, 2, 4, 8 saniye, ancak 30'u geçmez. Böylece bot proxy'deki IP değişimini veya kısa kanal arızasını atlatır. 429'da retry_after'ı okur, yarım saniye pay ekler ve tekrarlar. Telegram tarafındaki 5xx hatalarında da duraklamayla tekrarlar. 400 veya 403 hatalarında, örneğin kullanıcı botu engellediyse, tekrar yararsızdır, bu yüzden fonksiyon yanıtı olduğu gibi döndürür ve ne yapacağınıza siz karar verirsi