Telegram'da Bot Nasıl Oluşturulur? Adım Adım Kılavuz

Telegram Bot Geliştirmeye Giriş

Messenger uygulamaları içinde bot desteği sunan platformların başında gelen Telegram, esnek API'si sayesinde geliştiricilere neredeyse sınırsız otomasyon imkânı tanır. Bir Telegram botu; anlık bildirim göndermekten sohbet tabanlı bir hizmet sunmaya, veritabanı sorguları çalıştırmaktan IoT cihazlarını yönetmeye kadar birçok alanda kullanılabilir. Bu rehberde, Telegram'da bot oluşturma sürecini uçtan uca ele alıyoruz: BotFather ile kayıttan, temel bir bot yazmaya, yayınlama ve hata ayıklamaya kadar tüm aşamaları adım adım inceleyeceğiz.

Rehber, başlangıç seviyesindeki okuyucuların adımları kolayca takip edebilmesi için tasarlanmış olup, ileri düzey geliştiriciler de bot mimarisi, webhook ile polling karşılaştırması ve performans iyileştirmeleri gibi konularda faydalı içerikler bulacaktır. Örnekler ağırlıklı olarak Python ile verilecek, ancak Node.js kullananlar için de eşdeğer kod parçaları paylaşılacaktır.

BotFather ile Bot Oluşturma

Telegram'da resmî bot yönetim aracı olan BotFather, yeni bir bot yaratmak, mevcut botları düzenlemek ve botunuzun anahtarını (token) almak için kullanılır. BotFather'a Telegram'da arama yaparak veya doğrudan t.me/BotFather bağlantısına tıklayarak ulaşabilirsiniz. Tüm platformlarda (Android, iOS, Masaüstü) aynı arayüz üzerinden işlem yapılır.

Adım Adım Kayıt

Kayıt işlemi birkaç basit adımdan oluşur. BotFather ile sohbeti başlattıktan sonra aşağıdaki sırayı izleyin:

1. Sohbeti Başlatın: BotFather ile bir sohbet açın ve /start komutunu gönderin. BotFather size tüm komutların listesini dönecektir.
2. Yeni Bot Oluşturun: /newbot komutunu yazın. BotFather sırasıyla şunları isteyecektir:
   • Bot Adı: Kullanıcıların botunuzu tanıyacağı görünen ad (ör. "Hava Durumu Botu").
   • Kullanıcı Adı: Benzersiz, bot ile biten bir kullanıcı adı (ör. hava_durumu_bot).
3. Token Alma: Başarılı kaydın ardından BotFather size bir API token sağlar. Bu token, botunuzun kimliğini doğrular ve Telegram sunucularına yapacağınız tüm isteklerde kullanılır. Token'ınızı asla herkese açık depolara (GitHub vb.) eklemeyin veya paylaşmayın.

Neden BotFather ile Başlamalıyız?

BotFather, Telegram bot ekosisteminin resmî ve tek başlangıç noktasıdır; alternatif bir hizmet bulunmamaktadır. Bu merkezî yapı sayesinde botunuzun adını, profil fotoğrafını ve komut listesini dilediğiniz zaman değiştirebilirsiniz. Tüm bu ayarlar tek bir arayüzden yönetildiği için geliştirme süreci standartlaşır ve oluşabilecek karışıklıkların önüne geçilir.

Hangi Durumlarda Bu Adımı Atlamamalısınız?

Eğer başka bir geliştiricinin oluşturduğu botu devralıyor veya var olan bir botun token'ını biliyorsanız, BotFather'a ihtiyaç duymayabilirsiniz. Ancak sıfırdan yeni bir bot oluşturmanın meşru ve tek yolu BotFather'dır. Resmî olmayan kaynaklardan token almaya çalışmak ciddi güvenlik riskleri doğurur; bu nedenle kayıt işlemini mutlaka BotFather üzerinden yapmalısınız.

Geliştirme Ortamının Hazırlanması

Botunuzu yazmaya başlamadan önce bilgisayarınızda bir çalışma ortamı kurmanız gerekir. Bu rehberde iki popüler dil kullanılacaktır: Python (python-telegram-bot kütüphanesi ile) ve Node.js (node-telegram-bot-api modülü ile). Her iki dil de geniş bir topluluk desteğine sahiptir ve başlangıç seviyesi için idealdir.

Python Kurulumu

Python 3.8 veya üzeri bir sürümün yüklü olduğundan emin olun. Terminal veya komut satırınıza aşağıdaki komutu girin:

Bu işlem, bot geliştirmek için gerekli olan python-telegram-bot kütüphanesini yükler. Projenizi bağımlılıklardan izole etmek için sanal bir ortam kullanmanız önerilir (python -m venv venv ve ardından aktifleştirme).

Node.js Kurulumu

Node.js 18 (veya daha yeni bir LTS sürümü) yüklüyse, proje klasörünüzde aşağıdaki komutu çalıştırın:

Alternatif olarak, resmî Telegram Bot API'sine doğrudan HTTP istekleri de gönderebilirsiniz (axios, fetch gibi araçlarla). Ancak bu yaklaşım daha fazla manuel iş gerektirir ve hata yönetimi açısından daha dikkatli olmanız gerekir.

İlk Botunuzu Kodlama: Echo Bot

Echo bot, kullanıcıdan gelen her mesajı aynen geri gönderen basit bir bottur. Bu örnek, botun temel çalışma mantığını anlamak için idealdir.

Python ile Echo Bot

Aşağıdaki kod, python-telegram-bot kütüphanesini kullanarak bir echo bot oluşturur:

import logging
from telegram import Update
from telegram.ext import Application, MessageHandler, filters, CommandHandler

TOKEN = "YOUR_TOKEN_HERE"

async def start(update: Update, context):
    await update.message.reply_text("Merhaba! Ben bir echo botuyum.")

async def echo(update: Update, context):
    user_text = update.message.text
    await update.message.reply_text(f"Siz dediniz ki: {user_text}")

def main():
    app = Application.builder().token(TOKEN).build()
    app.add_handler(CommandHandler("start", start))
    app.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, echo))
    app.run_polling()

if __name__ == "__main__":
    logging.basicConfig(level=logging.INFO)
    main()

Kodu çalıştırmadan önce YOUR_TOKEN_HERE yerine BotFather'dan aldığınız token'ı yazın.

Node.js ile Echo Bot

Node.js için benzer bir örnek:

const TelegramBot = require('node-telegram-bot-api');
const TOKEN = 'YOUR_TOKEN_HERE';
const bot = new TelegramBot(TOKEN, {polling: true});

bot.onText(/\/start/, (msg) => {
    bot.sendMessage(msg.chat.id, 'Merhaba! Ben bir echo botuyum.');
});

bot.on('message', (msg) => {
    const chatId = msg.chat.id;
    const text = msg.text;
    if (text && !text.startsWith('/')) {
        bot.sendMessage(chatId, `Siz dediniz ki: ${text}`);
    }
});

Python ve Node.js örnekleri arasında işlevsel fark yoktur; hangi dili tercih edeceğiniz tamamen alışkanlık ve ekosistem ihtiyaçlarınıza bağlıdır.

Polling mi, Webhook mu?

Telegram botları, mesajları almak için iki yöntem kullanır: Polling ve Webhook. Her ikisinin de avantajları ve kullanım senaryoları farklıdır.

Polling (Uzun Yoklama)

Polling yönteminde bot, Telegram sunucularını sürekli sorgular ve yeni mesaj var mı diye kontrol eder. run_polling() veya {polling: true} seçeneğiyle etkinleştirilir. Geliştirme aşamasında idealdir çünkü herhangi bir public IP veya SSL sertifikası gerektirmez; ortamdan bağımsız çalışır.

Ne zaman kullanılmamalı: Yüksek trafikli botlar için polling, uzun süreli bağlantılar nedeniyle ölçeklenebilirlik sorunu çıkarabilir. Ayrıca tek bir sunucuya bağımlı kalmanız gerekir.

Webhook

Webhook yönteminde, Telegram sunucuları botunuza gelen her mesajı önceden belirlediğiniz bir HTTPS endpoint'ine gönderir. Bu yöntem polling'e göre daha verimlidir ve ölçeklenmesi kolaydır. Ancak geçerli bir SSL sertifikası (Let's Encrypt ücretsiz sağlanabilir) ve genel bir IP adresi veya domain gerektirir.

Webhook ayarlamak için Telegram API'nin setWebhook metodunu kullanırsınız. Python tarafında örnek bir kullanım:

from telegram.ext import Application
app = Application.builder().token(TOKEN).build()
await app.bot.set_webhook('https://sizin-domaininiz.com/webhook')

Webhook kullanırken, mesajları almak için bir HTTP sunucusu (Flask, FastAPI, Express.js vb.) çalıştırmanız gerekir. Bot, gelen POST isteklerini işler. Bu yöntem sayesinde botunuz sunucusuz (serverless) fonksiyonlarla da çalıştırılabilir (ör. AWS Lambda, Cloudflare Workers).

Hata Ayıklama ve Sorun Giderme

Bot geliştirirken karşılaşabileceğiniz yaygın sorunları ve çözümlerini bu bölümde bulabilirsiniz.

Sorun: Bot Çalışmıyor / Yanıt Vermiyor

Olası Nedenler: Token hatalı, bot kod çalışmıyor (durdurulmuş), polling veya webhook yanlış yapılandırılmış olabilir.
Doğrulama: Terminal'de botu çalıştırın ve log mesajlarını kontrol edin. Telegram'da botunuza bir mesaj gönderip yanıt alıp almadığınıza bakın.
Çözüm: Token'ı yeniden kontrol edin, botu yeniden başlatın, getUpdates API'sini manuel çağırarak mesajların gelip gelmediğini test edin.

Sorun: Bot Yalnızca /start Komutuna Yanıt Veriyor

Olası Neden: Filtreler yanlış tanımlanmış olabilir; flood kontrolü veya handler sırası sorunu söz konusu olabilir.
Doğrulama: Handler'ların doğru sırada tanımlandığını ve gerekli filtrelerin uygulandığını kontrol edin.
Çözüm: MessageHandler filtresinde ~filters.COMMAND kullanarak komut dışı mesajları yakaladığınızdan emin olun.

Sorun: Webhook Hataları (SSL, Timeout)

Olası Neden: Geçersiz SSL sertifikası, yanlış port yapılandırması veya endpoint'e erişilememesi.
Doğrulama: curl -k https://sizin-domaininiz.com/webhook ile endpoint'in erişilebilir olduğunu test edin.
Çözüm: Let's Encrypt ile geçerli bir sertifika oluşturun; geliştirme ortamında self-signed sertifika kullanmayın (Telegram kabul etmez). Test yaparken polling'e dönmek daha pratik olabilir.

Sorun: API Limit Hatası (429 Too Many Requests)

Olası Neden: Çok hızlı istek gönderiyorsunuz; Telegram'ın rate limitine takılıyorsunuz.
Doğrulama: Bot loglarında 429 hata kodunu arayın.
Çözüm: İstekler arasında 1 saniye gecikme koyun. Python'da time.sleep(1), Node.js'de setTimeout kullanabilirsiniz. Ayrıca bir retry (yeniden deneme) mantığı eklemeniz önerilir.

Bot Yayınlama ve Paylaşma

Botunuz tamamen çalışır duruma geldiğinde, onu kullanıma sunmak için birkaç adım daha vardır. BotFather üzerinden botunuzun profilini zenginleştirerek kulllanıcı deneyimini iyileştirebilirsiniz.

BotFather Ayarları

• /setcommands: Botunuzun desteklediği komutları ve açıklamalarını tanımlayın. Kullanıcılar mesaj kutusuna / yazdığında bu liste görünür.
• /setdescription: Bot hakkında kısa bir açıklama ekleyin (maksimum 512 karakter).
• /setabouttext: Bot profilinde görünen "Hakkında" bölümünü belirleyin.
• /setuserpic: Botunuz için bir profil fotoğrafı yükleyin.
• /setprivacy: Varsayılan olarak bot, gruplarda yalnızca komut mesajlarını görür. Eğer gruptaki tüm mesajları okumasını istiyorsanız bu ayarı Disable yapın.

Botunuzu Tanıtma

Telegram'da botlar için ayrı bir mağaza bulunmaz. Botunuzu kullanıcılarla buluşturmak için doğrudan bot kullanıcı adı (@botusername) üzerinden sohbet başlatabilir veya t.me/botusername bağlantısını paylaşabilirsiniz. Botunuzu gruplara ekleyerek de işlevselliğini sergileyebilir ve geri bildirim alabilirsiniz.

İleri Düzey Konular

Temel bot yapısını öğrendikten sonra, aşağıdaki konular botunuzu daha güçlü ve kullanışlı hale getirecektir.

Inline Mod

Kullanıcıların herhangi bir sohbette @botusername yazıp botunuzdan sonuç almasını sağlar. BotFather üzerinden /setinline ile etkinleştirilir. Bu modda bot, gelen inline sorguları işler ve seçenekleri gösterir. Örneğin, bir GIF botu yazarsanız kullanıcı @gifbot kediler yazdığında kedi GIF'lerini görür.

Callback Query ve Düğmeler

Mesajlarınıza Inline Keyboard ekleyerek kullanıcılardan tıklama yoluyla geri bildirim alabilirsiniz. Callback query işleyicisi, tıklanan düğmeye göre farklı işlemler yapar. Bu özellik özellikle anket botları, sıralı menüler veya onay kutuları için oldukça kullanışlıdır.

Veritabanı Entegrasyonu

Kullanıcı verilerini kalıcı olarak saklamak için SQLite, PostgreSQL veya MongoDB gibi veritabanları kullanabilirsiniz. Bot her yeniden başladığında durumu korumak istiyorsanız bir veritabanı bağlantısı şarttır. Özellikle kullanıcı ayarları, puan tabloları veya istatistikler içeren botlarda bu ihtiyaç daha da belirginleşir.

En İyi Uygulamalar Kontrol Listesi

Aşağıdaki maddeler, botunuzu üretime almadan önce gözden geçirmeniz gereken genel kabul görmüş uygulamalardır. Her projenin ihtiyacı farklı olsa da, bu öneriler güvenlik ve sürdürülebilirlik açısından kritik öneme sahiptir.

• Hiyerarşik Yapılandırma: Tüm sabitleri (token, URL'ler, izin verilen kullanıcı ID'leri) merkezi bir yapılandırma dosyası veya çevre değişkeni ile yönetin.
• Loglama: Python'da logging modülünü, Node.js'de winston paketini kullanarak yeterli log seviyesi ayarlayın. Hata logları (ERROR) ayrı bir dosyaya yazılmalıdır.
• Hata Yakalama: Tüm async fonksiyonların içinde try-except blokları kullanarak beklenmedik istisnaları loglayın ve kullanıcıya dostça bir hata mesajı gösterin.
• Rate Limiting Desteği: Botunuz yüksek trafik alacaksa, gelen istekleri kuyruğa alın veya bir throttle mekanizması kurun. Telegram'ın saniyede 30 mesaj sınırına dikkat edin.
• Sürekli Çalışma: Botunuzu bir systemd servisi veya Docker konteyneri olarak çalıştırın. Beklenmedik durmalarda otomatik yeniden başlatma ayarlayın.
• Veri Yedekleme: Veritabanı kullanıyorsanız düzenli yedekleme stratejisi oluşturun.

Sıkça Sorulan Sorular

Sonuç

Bu rehber kapsamında, Telegram'da bot oluşturma sürecini uçtan uca ele aldık. BotFather ile kayıt, geliştirme ortamı hazırlığı, temel bir botun kodlanması, polling/webhook seçimi, sık karşılaşılan hataların giderilmesi ve botun yayına hazırlanması gibi adımları pratik örneklerle destekledik. Artık kendi bot fikrinizi hayata geçirmek için gerekli donanıma sahipsiniz.

Bir sonraki adımda, botunuzun işlevselliğini artırmak için Telegram Bot API belgelerini inceleyebilir, bir veritabanı entegrasyonu ekleyebilir veya botunuzu sunucusuz bir mimariye taşıyabilirsiniz. Unutmayın: bot geliştirme, deneme-yanılma ve sürekli öğrenme gerektiren bir süreçtir. İyi kodlamalar!