Telegram botu nasıl deploy edilir: VPS, Docker ve serverless hosting
Telegram botunu deploy etmek için kodunu sürekli açık duran ve api.telegram.org adresine erişebilen bir makinede çalıştırın, ardından güncellemeleri nasıl alacağını seçin: alan adı olmadan her sunucuda çalışan getUpdates ile long polling veya herkese açık bir HTTPS URL gerektiren webhook. Polling botları için genellikle systemd'li küçük bir VPS veya bir Docker konteyneri tercih edilir; Cloudflare Workers gibi serverless platformlar webhook botlarına uygundur. Bu rehberde her seçeneği kopyala-yapıştır yapılandırmalarla, ayrıca loglama, yeniden başlatma ve yayın kontrol listesiyle gösteriyoruz.
Sunucuda polling mi webhook mu?
Telegram güncelleme almak için birbirini dışlayan iki yol sunar ve her iki durumda da teslim edilmeyen güncellemeleri en fazla 24 saat saklar. Seçiminiz, Telegram bot hosting için neye ihtiyacınız olduğunu belirler:
Long polling (getUpdates) | Webhook (setWebhook) | |
|---|---|---|
| Ağ | Yalnızca giden HTTPS; NAT arkasında çalışır | Herkese açık HTTPS URL, 443, 80, 88 veya 8443 portu, IPv4 |
| Süreç | Sürekli çalışan döngü | HTTP handler; serverless olabilir |
| Örnek sayısı | Token başına tam olarak bir | Tek URL arkasında birden fazla olabilir |
| Uygun ortamlar | VPS, Docker, ev sunucusu | Reverse proxy'li VPS, Cloudflare Workers, AWS Lambda, Vercel |
Polling makinenizde zaten çalışıyorsa onunla devam edin: Telegram'ın kendi webhook rehberi de getUpdates kullanmakta bir sakınca olmadığını söyler. Platformunuz gerektirdiğinde veya yükü birden çok örneğe dağıtmak istediğinizde webhook'a geçin.
Deploy'a hazır bir polling botu
Üretime hazır kodun üç özelliği vardır: token'ı ortam değişkeninden okur, logları stdout'a yazar ve ağ hatalarında çökmek yerine devam eder. Bu echo botu üçünü de yapar ve başlangıçta deleteWebhook çağırır, çünkü webhook kuruluyken getUpdates çalışmaz:
import logging
import os
import time
import requests
logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s")
log = logging.getLogger("bot")
TOKEN = os.environ["BOT_TOKEN"] # token'ı asla koda gömmeyin
API = f"https://api.telegram.org/bot{TOKEN}"
def call(method, **params):
data = requests.post(f"{API}/{method}", json=params, timeout=40).json()
if not data["ok"]:
raise RuntimeError(f"{method}: {data['error_code']} {data['description']}")
return data["result"]
def main():
call("deleteWebhook") # polling ve webhook birbirini dışlar
log.info("started as @%s", call("getMe")["username"])
offset = 0
while True:
try:
updates = call("getUpdates", offset=offset, timeout=30)
except Exception:
log.exception("getUpdates failed, retrying in 5 s")
time.sleep(5)
continue
for update in updates:
offset = update["update_id"] + 1
msg = update.get("message")
if msg and "text" in msg:
try:
call("sendMessage", chat_id=msg["chat"]["id"], text="Echo: " + msg["text"])
except Exception:
log.exception("update %s failed", update["update_id"])
if __name__ == "__main__":
main()const TOKEN = process.env.BOT_TOKEN; // token'ı asla koda gömmeyin
if (!TOKEN) throw new Error("BOT_TOKEN is not set");
const API = `https://api.telegram.org/bot${TOKEN}`;
const log = (...args) => console.log(new Date().toISOString(), ...args);
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
async function call(method, params = {}) {
const res = await fetch(`${API}/${method}`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(params),
signal: AbortSignal.timeout(40_000),
});
const data = await res.json();
if (!data.ok) throw new Error(`${method}: ${data.error_code} ${data.description}`);
return data.result;
}
await call("deleteWebhook"); // polling ve webhook birbirini dışlar
log("started as @" + (await call("getMe")).username);
let offset = 0;
while (true) {
let updates;
try {
updates = await call("getUpdates", { offset, timeout: 30 });
} catch (err) {
log("getUpdates failed, retrying in 5 s:", err.message);
await sleep(5000);
continue;
}
for (const update of updates) {
offset = update.update_id + 1;
const msg = update.message;
if (!msg?.text) continue;
try {
await call("sendMessage", { chat_id: msg.chat.id, text: "Echo: " + msg.text });
} catch (err) {
log(`update ${update.update_id} failed:`, err.message);
}
}
}Bunları bot.py (requirements.txt içinde requests ile) veya bot.mjs (Node.js 18+, bağımlılık yok) olarak kaydedin. Kütüphaneler listesindeki framework'ler döngüyü sizin yerinize yönetir, ancak aşağıdaki deploy adımları aynı kalır.
systemd ile VPS'te Telegram botu
VPS size sıradan bir Linux makinesi verir. Botu açılışta systemd başlatsın ve çökerse yeniden başlatsın:
- Oturum açma yetkisi olmayan bir kullanıcı oluşturun ve kodu
/opt/mybotdizinine kopyalayın; Python için orada bir sanal ortam (venv) oluşturup bağımlılıkları kurun. - Token'ı
/etc/mybot.envdosyasınaBOT_TOKEN=123456789:AAEexampleTokenReplaceWithYourssatırı olarak yazın ve erişimichmod 600ile kısıtlayın. /etc/systemd/system/mybot.serviceunit dosyasını oluşturun:
[Unit]
Description=Telegram bot
After=network-online.target
Wants=network-online.target
[Service]
User=mybot
WorkingDirectory=/opt/mybot
EnvironmentFile=/etc/mybot.env
ExecStart=/opt/mybot/.venv/bin/python -u bot.py
# Node.js: ExecStart=/usr/bin/node bot.mjs
Restart=always
RestartSec=5
[Install]
WantedBy=multi-user.target
Servisi etkinleştirin ve logları izleyin:
sudo systemctl daemon-reload
sudo systemctl enable --now mybot
journalctl -u mybot -f # canlı loglar
sudo systemctl restart mybot # kodu güncelledikten sonra
Aynı VPS'te webhook için botu yerel bir portta HTTP sunucusu olarak çalıştırın ve önüne 443 portunda TLS'i sonlandıran nginx veya Caddy koyun; secret token kontrolü yapan bir handler webhook rehberinde var.
Docker ile Telegram bot deploy
Konteyner çalışma ortamını ve bağımlılıkları paketler; bot dizüstü bilgisayarınızda ve her Docker sunucusunda aynı şekilde çalışır. Python botu için bir Dockerfile:
FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY bot.py .
CMD ["python", "-u", "bot.py"]
# Node.js: FROM node:22-slim, COPY bot.mjs ., CMD ["node", "bot.mjs"]
İmajı oluşturun ve token'ı imaja gömmeden, çalışma anında vererek başlatın:
docker build -t mybot .
docker run -d --name mybot --restart unless-stopped --env-file .env mybot
docker logs -f mybot
--restart unless-stopped botu çökmelerden ve sunucu yeniden başlatmalarından sonra geri getirir. .env dosyasını Git'e ve imaja koymayın (.dockerignore'a ekleyin). Polling botunu yeniden deploy ederken yenisini başlatmadan önce eski konteyneri durdurun: aynı token'la polling yapan iki konteyner getUpdates'in 409 Conflict ile başarısız olmasına yol açar.
Serverless: Cloudflare Workers'ta Telegram botu
Serverless platformlar kodu yalnızca istek geldiğinde çalıştırır, bu yüzden webhook modu gerekir. Cloudflare Workers'ta varsayılan workers.dev adresi zaten 443 portunda HTTPS sunar. Bu Worker secret token başlığını kontrol eder, hemen yanıt verir ve işi ctx.waitUntil ile arka planda bitirir:
// worker.js: "npx wrangler deploy" ile deploy edin
export default {
async fetch(request, env, ctx) {
const url = new URL(request.url);
if (request.method !== "POST" || url.pathname !== "/telegram/webhook") {
return new Response("Not found", { status: 404 });
}
const enc = new TextEncoder();
const received = enc.encode(request.headers.get("X-Telegram-Bot-Api-Secret-Token") ?? "");
const expected = enc.encode(env.WEBHOOK_SECRET);
if (received.byteLength !== expected.byteLength ||
!crypto.subtle.timingSafeEqual(received, expected)) {
return new Response("Forbidden", { status: 403 });
}
const update = await request.json();
ctx.waitUntil(handleUpdate(update, env)); // şimdi 200 dön, çalışmaya devam et
return new Response("OK");
},
};
async function handleUpdate(update, env) {
const msg = update.message;
if (!msg?.text) return;
const res = await fetch(`https://api.telegram.org/bot${env.BOT_TOKEN}/sendMessage`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ chat_id: msg.chat.id, text: "Echo: " + msg.text }),
});
if (!res.ok) console.error("sendMessage failed", res.status, await res.text());
}
Her iki değeri Worker secret olarak kaydedin, deploy edin, ardından Worker URL'sini aynı secret ile kaydedin:
npx wrangler secret put BOT_TOKEN
npx wrangler secret put WEBHOOK_SECRET
npx wrangler deploy
curl -X POST "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/setWebhook" \
-H "Content-Type: application/json" \
-d '{"url": "https://mybot.example.workers.dev/telegram/webhook", "secret_token": "replace-with-your-random-secret"}'
Ya da Bot API Tester'da setWebhook formunu doldurun. Aynı yaklaşım AWS Lambda'da (HTTPS function URL veya API gateway arkasında) ve Vercel fonksiyonlarında da çalışır: JSON gövdesini ayrıştırın, başlığı doğrulayın, hızlıca 2XX dönün. Platformlar bir fonksiyonun ve arka plan işinin ne kadar çalışabileceğini sınırlar, bu yüzden yavaş işleri bir kuyruğa taşıyın. Telegram 2XX olmayan her yanıtı tekrar dener; zaman aşımına uğrayan veya çöken bir fonksiyon aynı güncellemeyi yeniden alır.
Telegram botunu ücretsiz veya düşük maliyetle barındırma
- Serverless ücretsiz katmanlar, trafiği az ve handler'ı kısa webhook botlarına uygundur.
- Küçük bir VPS en esnek seçenektir: polling veya webhook, her dil, botun yanında bir veritabanı.
- Ev sunucusu veya tek kartlı bilgisayar, gelen bağlantı gerekmediği için polling ile çalışır; çalışma süresi elektriğinize ve internetinize bağlıdır.
- Süreci sürekli çalışır tutan konteyner platformları polling botunu barındırabilir; boşta kalan uygulamaları uyku moduna almadıklarından emin olun.
Her ortam için webhook gereksinimleri
- Yalnızca HTTPS, TLS 1.2 veya üstü, alan adınızla eşleşen ve zinciri eksiksiz bir sertifika ya da
certificateile yüklenen kendinden imzalı sertifika. - 443, 80, 88 veya 8443 portu; IPv4 (webhook'larda IPv6 desteklenmez); yönlendirme yok.
- İstekler
149.154.160.0/20ve91.108.4.0/22aralıklarından gelir; Telegram bu aralıkların değişebileceğini belirtir. secret_tokenayarlayın (1–256 karakter,A-Z a-z 0-9 _ -) veX-Telegram-Bot-Api-Secret-Tokenbaşlığını doğrulayın.
Her deploy'dan sonra Bot API Tester'da getWebhookInfo metodunu açın: artan bir pending_update_count veya yeni bir last_error_message, Telegram'ın güncellemeleri teslim edemediği anlamına gelir.
Ortam değişkenleri, loglama ve yeniden başlatma
- Token: yalnızca ortam değişkeni veya secret deposu; asla Git'te, imajda ya da istemci kodunda değil. Sızarsa bot token rehberinde anlatıldığı gibi iptal edin ve sunucuyu güncelleyin.
- Loglar: stdout/stderr'e yazın, toplamayı journald, Docker veya platform yapsın. İstek URL'lerinin tamamını loglamayın, çünkü token içerirler.
- Yeniden başlatma: çökmeleri bir süreç yöneticisi (
Restart=always,--restart unless-stopped) halleder. Telegram onaylanan güncellemeleri kendi tarafında takip eder:getUpdatesdaha yüksek biroffsetile çağrıldığında güncelleme onaylanmış sayılır, bu yüzden yeniden başlatmadan sonra bot yalnızca onaylanmamış olanları alır. Çökmeden önceki son paket iki kez gelebilir; önemli olduğu yerdeupdate_idile tekrarları ayıklayın. - Hız limitleri:
429 Too Many Requestsyanıtındaretry_aftersaniye bekleyin; bkz. Telegram Bot API limitleri.
Deploy kontrol listesi
- Token ortam değişkeninden veya secret'tan geliyor;
getMesunucuda başarılı. - Token başına tam olarak bir polling örneği ya da
secret_token'lı bir webhook var, ikisi birden asla. - Süreç çökme ve yeniden başlatmalardan sonra otomatik olarak ayağa kalkıyor.
- Loglar toplanıyor ve token içermiyor.
- Tek bir güncellemedeki hata loglanıyor, botu durdurmuyor; webhook handler'ları hızlıca 2XX dönüyor.
- Webhook'ta
getWebhookInfodoğru URL'yi gösteriyor ve yakın tarihli hata yok. - Denemeler için üretim token'ı değil, ayrı bir test botu veya Telegram test sunucusu kullanılıyor.
Deploy sorunlarını giderme
| Belirti | Neden ve çözüm |
|---|---|
409 Conflict: terminated by other getUpdates request | İki örnek aynı token'la polling yapıyor (eski konteyner, dizüstü bilgisayarınız). Biri hariç hepsini durdurun. |
Aktif webhook'tan bahseden 409 Conflict | Webhook hâlâ kurulu. Polling'den önce deleteWebhook çağırın. |
401 Unauthorized | Token değişkeni boş, hatalı yazılmış veya iptal edilmiş. getMe ile kontrol edin. |
| Yerelde çalışıyor, sunucuda ses yok | api.telegram.org adresine giden HTTPS engellenmiş ya da ortam dosyası yüklenmemiş. Loglara bakın. |
| Webhook botuna hiçbir şey gelmiyor | getWebhookInfo'daki last_error_message alanına bakın: TLS, yanlış port, secret uyuşmazlığından 403 veya çöken handler. |
Botlara yeni mi başlıyorsunuz? Önce Telegram bot oluşturma rehberiyle başlayın, sonra deploy için buraya dönün.
Sık sorulan sorular
Telegram botu nerede barındırabilirim?
Dışarıya HTTPS isteği atabilen her yerde: VPS, Docker sunucusu, ev sunucusu veya serverless platform. getUpdates kullanan bot herkese açık bir adrese ihtiyaç duymaz; webhook botu ise 443, 80, 88 veya 8443 portunda herkese açık bir HTTPS URL ister.
Deploy edilen bot polling mi webhook mu kullanmalı?
İkisi de üretimde çalışır. getUpdates ile long polling, alan adı ve sertifika gerekmediği için VPS'te veya Docker'da en basit yoldur. Yalnızca istek geldiğinde kod çalıştıran serverless platformlarda webhook zorunludur.
Botu deploy ettikten sonra neden 409 Conflict alıyorum?
Ya bot getUpdates ile polling yaparken hâlâ bir webhook kurulu (deleteWebhook çağırın), ya da botun iki kopyası aynı anda polling yapıyor: ör. deploy sırasında eski ve yeni konteyner veya dizüstü bilgisayarınız ve sunucu. Token başına tam olarak bir polling örneği çalıştırın.
Telegram botunu 7/24 çalışır halde nasıl tutarım?
Çökme ve yeniden başlatmalardan sonra botu tekrar ayağa kaldıran bir süreç yöneticisi kullanın: VPS'te Restart=always içeren bir systemd servisi veya --restart unless-stopped ile çalışan bir Docker konteyneri. Logları stdout'a yazın ve journalctl ya da docker logs ile izleyin.
Telegram botu Cloudflare Workers'ta çalıştırılabilir mi?
Evet, webhook modunda. Worker her güncellemeyi POST isteği olarak alır, X-Telegram-Bot-Api-Secret-Token başlığını kontrol eder ve Bot API'yi fetch ile çağırır. workers.dev HTTPS adresini setWebhook ile kaydedin. Long polling döngüsü bu modele uymaz.
Sunucuda bot token'ını nerede saklamalıyım?
Yalnızca bot kullanıcısının okuyabildiği bir dosyadan yüklenen ortam değişkeninde veya platformun gizli anahtar deposunda (ör. Worker secret). Token'ı asla Git'e commit etmeyin veya Docker imajına gömmeyin. Sızarsa @BotFather'da iptal edin.
İlgili rehberler
Telegram bot nasıl yapılır? BotFather ile adım adım bot oluşturma
Telegram bot yapma rehberi: BotFather'da /newbot ile bot oluşturun, token'ı getMe ile test edin, chat ID'yi bulun ve Python ile ilk mesajı gönderin.
Telegram Bot API 10.0–10.5: bot ayarları, widget'lar, rich mesajlar, ephemeral mesajlar, misafir modu ve dahası
Telegram Bot API 10.0–10.5'teki yenilikler: setMySettings ve BotFullInfo, HTML widget'lar, rich ve ephemeral mesajlar, misafir modu; JSON örnekleriyle.
Telegram Bot API hataları: her hata ne anlama gelir ve nasıl çözülür
Telegram Bot API hataları: 400 chat not found, 403 bot was blocked by the user, 409 Conflict, 429 retry_after. Nedenleri, çözümleri ve hata yönetimi kodu.
Telegram Bot API limitleri: mesaj gönderme hızı, 429 hatası, dosya boyutu ve mesaj uzunluğu
Telegram Bot API limitleri: saniyede 30 mesaj, sohbet başına 1 mesaj/sn, grupta dakikada 20, 429 retry_after yönetimi, dosya boyutu ve mesaj uzunluğu.
Telegram bot komutları: setMyCommands, komut kapsamları ve /start deep link
Telegram bot komutları nasıl eklenir: @BotFather /setcommands, kapsam ve dil destekli setMyCommands, /start deep link parametresi, gruplarda /komut@bot.
Telegram bot klavyeleri: inline klavye, callback butonları ve reply klavye
Telegram bot butonu ekleme: callback_data ile inline klavye, answerCallbackQuery, basıştan sonra mesajı düzenleme, reply klavye ve ForceReply örnekleri.
n8n Telegram entegrasyonu: botu bağlama, workflow tetikleme ve mesaj gönderme
n8n'i Telegram'a bağlayın: bot token'ı Access Token olarak girin, Telegram Trigger webhook'u için HTTPS kurun, chat id ile mesaj gönderin, hataları çözün.
Telegram Bot API ile mesaj gönderme (send message): curl, Python ve JavaScript
Telegram Bot API send message rehberi: curl, Python ve JavaScript ile sendMessage, HTML ve MarkdownV2 biçimlendirme, inline butonlar ve sık hatalar.
Telegram bot token nasıl alınır, nerede bulunur ve nasıl iptal edilir?
Telegram bot token nedir, BotFather'dan nasıl alınır, mevcut botun token'ı nerede bulunur? getMe ile test, 401 hatası ve sızan token'ı iptal etme.
Telegram bot webhook kurulumu: URL, secret token, getWebhookInfo ve sorun giderme
Telegram bot webhook kurulumu: setWebhook ile HTTPS URL ve secret_token ayarlayın, getWebhookInfo ile hataları görün; 409 Conflict ve n8n localhost çözümü.
Telegram chat ID nasıl bulunur: kullanıcı, grup, kanal ve konu için adım adım
Telegram chat ID nasıl bulunur? getUpdates ile kullanıcı, grup, süper grup ve kanal ID'sini öğrenin; -100 ön eki, konu ID'si ve boş result sorunu.
Telegram inline bot: inline modu açma ve inline sorguları yanıtlama
Telegram inline bot nasıl yapılır: inline modu @BotFather veya setMySettings ile açın, inline_query güncellemelerini answerInlineQuery ile yanıtlayın.
Telegram botlarında Stars ile ödeme: fatura, ön onay, iade ve abonelikler
Telegram botunuzda Stars ile ödeme alın: XTR ile sendInvoice, pre_checkout_query, successful_payment, iade ve abonelikler; Python ve JS kodu.
Telegram test sunucusu: Telegram botunu test ortamında nasıl test edersiniz?
Telegram test sunucusu nedir? Test ortamına giriş, test botu oluşturma, Bot API'yi /test/ ile çağırma ve Bot API Tester'da TEST modu adım adım.
Web siteniz için Telegram widget'ları: Telegram ile giriş, gönderi gömme, yorumlar ve paylaş butonu
Sitenize Telegram ile giriş ekleyin: yeni Telegram Login (OIDC), eski Login Widget ve hash kontrolü, gönderi gömme, yorumlar ve paylaş butonu.
TelegramWidget JavaScript API: özellikler, olaylar, hata kodları ve sınırlar
Telegram widget API başvurusu: TelegramWidget özellikleri, request(), olaylar, hata kodları, CSS değişkenleri, widget_query, answerWidgetQuery ve sınırlar.
Telegram widget örnekleri: eksiksiz HTML ve Python bot kodu
Çalışan Telegram widget örnekleri: statik sipariş kartı, widget_query ile sayaç, paylaşılan canlı anket ve yerel önizleme; HTML ve Python bot kodu.
Telegram widget: bot mesajının içinde çalışan etkileşimli HTML
Telegram widget nedir: Bot API 10.4'teki sendWidget, chat_data ve public_data nasıl çalışır, bugün nerede kullanılabilir, Mini App'ten farkı nedir?
Telegram Mini App nasıl test edilir: tarayıcıdaki mock'tan gerçek Telegram'a
Telegram Mini App test rehberi: tarayıcıda mock mod, HTTPS tünelle localhost, test ortamı, platformlara göre DevTools ve sunucuda initData doğrulama.