Ruby ile Telegram Botları Oluşturma Rehberi: Adım Adım Kapsamlı Bir Yaklaşım

Telegram botları, kullanıcılarla etkileşim kuran, otomatik görevler gerçekleştiren ve çeşitli servisleri Telegram platformuna entegre eden güçlü araçlardır. Ruby, esnek yapısı, okunabilir sözdizimi ve zengin gem ekosistemi sayesinde bot geliştirme için harika bir seçenektir. Bu makale, Ruby kullanarak sıfırdan bir Telegram botu oluşturma sürecini adım adım ele alacak, temelden ileri seviyeye kadar tüm konuları kapsayarak kendi botunuzu geliştirmenize yardımcı olacaktır.

Telegram Bot API ve Temel Kavramlar

Telegram botları, Telegram Bot API aracılığıyla Telegram sunucularıyla iletişim kurar. Bu API, botunuzun mesaj göndermesini, almasını, klavyeler oluşturmasını ve daha birçok işlemi gerçekleştirmesini sağlayan bir dizi HTTP tabanlı yöntem sunar.

Telegram Botları Nedir?

Telegram botları, Telegram kullanıcılarıyla sohbet eden, komutları işleyen ve çeşitli otomasyon görevlerini yerine getiren özel hesaplardır. Hava durumu bilgisi sağlamaktan, not tutmaya, oyun oynamaktan, e-ticaret işlemlerine kadar geniş bir yelpazede kullanılabilirler.

BotFather ile Yeni Bir Bot Oluşturma

Her Telegram botunun bir kimliğe ve bir API token’ına ihtiyacı vardır. Bu token, botunuzun Telegram API’sine erişimini sağlar ve BotFather adlı özel bir Telegram botu aracılığıyla oluşturulur. BotFather ile bot oluşturmak için şu adımları izleyin:

Telegram’da BotFather’ı arayın ve sohbeti başlatın.
/newbot komutunu gönderin.
Botunuz için bir isim seçin (örneğin, “Deneme Ruby Botu”).
Botunuz için benzersiz bir kullanıcı adı seçin (_bot ile bitmeli, örneğin, “deneme_ruby_bot”).
BotFather size bir API token’ı (örneğin, 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11) verecektir. Bu token’ı güvende tutun.

API Token’ının Önemi ve Güvenliği

API token’ı, botunuzun anahtarıdır. Bu token’ı ele geçiren herkes botunuzu kontrol edebilir. Bu nedenle, token’ınızı asla genel bir depoda (GitHub gibi) paylaşmamalı, ortam değişkenleri veya güvenli bir yapılandırma dosyası kullanarak saklamalısınız.

Bot API’nin Çalışma Prensibi (Webhook vs. Long Polling)

Botunuzun Telegram’dan güncellemeleri almasının iki ana yolu vardır:

Long Polling: Botunuz, yeni mesajlar için düzenli aralıklarla Telegram sunucularını sorgular. Basit botlar ve geliştirme ortamları için uygundur.
Webhook: Telegram, botunuza yeni bir güncelleme olduğunda HTTP POST isteği gönderir. Daha büyük ölçekli ve gerçek zamanlı uygulamalar için tercih edilir, ancak botunuzun herkese açık bir URL’e sahip olmasını gerektirir.

Bu makalede, başlangıç için daha kolay olan Long Polling yöntemini kullanacağız.

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

Ruby ile Telegram botu geliştirmeye başlamadan önce, gerekli araçlara sahip olduğunuzdan emin olmalısınız.

Ruby Kurulumu ve Versiyon Yönetimi

Sisteminizde Ruby kurulu değilse, öncelikle Ruby’yi kurmanız gerekir. Ruby’yi kurmanın en iyi yolu, rbenv veya RVM gibi bir versiyon yöneticisi kullanmaktır. Bu araçlar, farklı projeler için farklı Ruby versiyonlarını yönetmenizi sağlar.


# rbenv ile Ruby kurulumu (örnek)
git clone https://github.com/rbenv/rbenv.git ~/.rbenv
echo 'eval "$(~/.rbenv/bin/rbenv init -)"' >> ~/.bashrc
source ~/.bashrc

git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build

rbenv install 3.2.2 # İstediğiniz Ruby versiyonunu kurun
rbenv global 3.2.2 # Varsayılan olarak ayarlayın
ruby -v # Kurulumu doğrulayın

Proje Dizini Oluşturma ve Gemfile Hazırlığı

Botunuz için yeni bir proje dizini oluşturun ve Gemfile adında bir dosya oluşturarak kullanacağımız gem'leri tanımlayın.


mkdir my_telegram_bot
cd my_telegram_bot
touch Gemfile

Gemfile içeriği:


source 'https://rubygems.org'

gem 'telegram-bot-ruby'
gem 'dotenv' # Ortam değişkenlerini yönetmek için

`telegram-bot-ruby` Gem'ini Kurma

Gemfile'ı oluşturduktan sonra, gerekli gem'leri kurmak için bundle install komutunu çalıştırın.


bundle install

Ayrıca, API token'ınızı güvenli bir şekilde saklamak için .env dosyasını kullanacağız. Proje dizininizde .env adında bir dosya oluşturun ve API token'ınızı içine ekleyin:


# .env dosyası
TELEGRAM_BOT_TOKEN=YOUR_API_TOKEN_HERE

YOUR_API_TOKEN_HERE kısmını BotFather'dan aldığınız token ile değiştirin. Bu dosyayı asla versiyon kontrol sisteminize (Git gibi) eklemeyin! Bunun için .gitignore dosyasına .env eklemeyi unutmayın.

Basit Bir Telegram Botu Oluşturma

Artık ortamımız hazır olduğuna göre, ilk basit botumuzu yazmaya başlayabiliriz.

Bot Nesnesini Başlatma

bot.rb adında bir dosya oluşturun ve bot nesnesini başlatın.


require 'telegram/bot'
require 'dotenv/load' # .env dosyasını yükler

token = ENV['TELEGRAM_BOT_TOKEN']

Telegram::Bot::Client.run(token) do |bot|
  bot.listen do |message|
    # Mesaj işleme kodu buraya gelecek
    case message.text
    when '/start'
      bot.api.send_message(chat_id: message.chat.id, text: "Merhaba, #{message.from.first_name}! Ben bir Ruby Telegram botuyum.")
    when '/help'
      bot.api.send_message(chat_id: message.chat.id, text: "Kullanabileceğiniz komutlar: /start, /help")
    else
      bot.api.send_message(chat_id: message.chat.id, text: "Anlamadım: #{message.text}")
    end
  end
end

İlk Mesajı Yakalama ve Yanıtlama (`/start` komutu)

Yukarıdaki örnekte, bot.listen bloğu Telegram'dan gelen her yeni mesajı dinler. message nesnesi, mesajın içeriği, gönderen bilgisi gibi detayları içerir. message.text ile mesajın metin içeriğine erişiriz.

Kullanıcı /start komutunu gönderdiğinde, bot kullanıcıya hoş geldin mesajı gönderir. bot.api.send_message metodu, Telegram API'sinin sendMessage metodunu çağırır. chat_id mesajın gönderileceği sohbetin kimliğini, text ise mesajın içeriğini belirtir.

Basit Komut İşleyicileri Yazma

case message.text yapısı, farklı komutları (/start, /help) ve diğer metin mesajlarını kolayca işlemenizi sağlar. Bu yapı, botunuzun farklı komutlara farklı yanıtlar vermesini sağlar.

Botunuzu çalıştırmak için terminalde:


ruby bot.rb

komutunu çalıştırın ve Telegram'da botunuza mesaj göndererek test edin.

Gelişmiş Bot Özellikleri

Basit bir bot oluşturduktan sonra, daha zengin özellikler ekleyerek botunuzu daha etkileşimli hale getirebiliriz.

Metin Dışı Mesajlar Gönderme (Fotoğraf, Belge, Ses)

Telegram API, sadece metin değil, fotoğraf, video, belge gibi farklı medya türlerini de göndermenize olanak tanır. Her medya türü için ayrı bir API metodu bulunur.


# ... bot.listen do |message|
  case message.text
  when '/photo'
    # Yerel bir dosyadan fotoğraf gönderme
    bot.api.send_photo(chat_id: message.chat.id, photo: Faraday::UploadIO.new('path/to/your/image.jpg', 'image/jpeg'))
    # URL'den fotoğraf gönderme
    # bot.api.send_photo(chat_id: message.chat.id, photo: 'https://example.com/image.jpg')
  when '/document'
    bot.api.send_document(chat_id: message.chat.id, document: Faraday::UploadIO.new('path/to/your/document.pdf', 'application/pdf'))
  end
# ...

Faraday::UploadIO.new, yerel dosyaları API'ye yüklemek için kullanılır. Eğer bir URL'den gönderecekseniz, doğrudan URL'yi photo: veya document: parametresine verebilirsiniz.

Inline Klavye ve Özel Klavye Oluşturma

Klavye seçenekleri, kullanıcı etkileşimini büyük ölçüde artırır. İki tür klavye vardır:

Özel Klavyeler (Reply Keyboards): Kullanıcının metin giriş alanının altında görünen ve önceden tanımlanmış yanıtlar sunan klavyelerdir.
Inline Klavyeler: Mesajın altına gömülü olan ve bir URL'e yönlendirebilen veya bir "callback" sorgusu tetikleyebilen düğmelerdir.


# ... bot.listen do |message|
  case message.text
  when '/keyboard'
    # Özel Klavye (Reply Keyboard)
    kb = [
      Telegram::Bot::Types::KeyboardButton.new(text: 'Seçenek 1'),
      Telegram::Bot::Types::KeyboardButton.new(text: 'Seçenek 2')
    ]
    markup = Telegram::Bot::Types::ReplyKeyboardMarkup.new(keyboard: kb, one_time_keyboard: true)
    bot.api.send_message(chat_id: message.chat.id, text: 'Bir seçenek seçin:', reply_markup: markup)
  when '/inline_keyboard'
    # Inline Klavye
    kb = [
      Telegram::Bot::Types::InlineKeyboardButton.new(text: 'Google', url: 'https://www.google.com'),
      Telegram::Bot::Types::InlineKeyboardButton.new(text: 'Veri Gönder', callback_data: 'data_sent')
    ]
    markup = Telegram::Bot::Types::InlineKeyboardMarkup.new(inline_keyboard: [kb])
    bot.api.send_message(chat_id: message.chat.id, text: 'Inline klavye:', reply_markup: markup)
  end
# ...

Geri Çağrı Sorgularını (Callback Queries) İşleme

Inline klavyelerdeki callback_data ile gönderilen verileri yakalamak için bot.listen bloğunda callback_query tipindeki mesajları dinlemeniz gerekir.


# ...
bot.listen do |message|
  case message
  when Telegram::Bot::Types::CallbackQuery
    if message.data == 'data_sent'
      bot.api.answer_callback_query(callback_query_id: message.id, text: 'Veri başarıyla alındı!')
      bot.api.send_message(chat_id: message.from.id, text: 'Inline klavye verisi işlendi.')
    end
  when Telegram::Bot::Types::Message
    # ... (önceki mesaj işleme kodları)
  end
end
# ...

answer_callback_query, kullanıcının düğmeye tıkladıktan sonra gördüğü küçük bildirim (toast) mesajını gösterir.

Bot Komutları ve Durum Yönetimi

Daha karmaşık botlar, kullanıcıların durumunu yönetmeli ve birden fazla komutu daha düzenli bir şekilde işlemelidir.

Birden Fazla Komutu Etkin Bir Şekilde Yönetme

Çok sayıda komutunuz olduğunda, case yapısı karmaşık hale gelebilir. Daha modüler bir yaklaşım, her komut için ayrı bir metod veya sınıf kullanmaktır.


# lib/commands/start_command.rb
module Commands
  class StartCommand
    def self.call(bot, message)
      bot.api.send_message(chat_id: message.chat.id, text: "Merhaba, #{message.from.first_name}! Ben bir Ruby botuyum.")
    end
  end
end

# bot.rb (ana dosya)
# ...
require_relative 'lib/commands/start_command'

bot.listen do |message|
  case message.text
  when '/start'
    Commands::StartCommand.call(bot, message)
  when '/help'
    # ...
  end
end

Kullanıcı Durumunu Kaydetme ve Yönetme (Örn: Bir Form Doldurma)

Bir kullanıcının bir dizi adımı takip etmesini gerektiren (örneğin, bir form doldurma) durumlarda, kullanıcının mevcut durumunu takip etmeniz gerekir. Bunu basitçe bir Ruby hash'i veya daha kalıcı bir çözüm için bir veritabanı ile yapabilirsiniz.


# Basit bir durum yönetimi örneği (bellekte)
user_states = {} # { chat_id: :waiting_for_name, ... }

# ... bot.listen do |message|
  chat_id = message.chat.id
  case message.text
  when '/register'
    user_states[chat_id] = :waiting_for_name
    bot.api.send_message(chat_id: chat_id, text: 'Lütfen adınızı girin:')
  else
    case user_states[chat_id]
    when :waiting_for_name
      user_name = message.text
      # Adı kaydet, sonraki adıma geç
      user_states[chat_id] = :waiting_for_email
      bot.api.send_message(chat_id: chat_id, text: "Adınız #{user_name} olarak kaydedildi. Şimdi e-posta adresinizi girin:")
    when :waiting_for_email
      user_email = message.text
      # E-postayı kaydet, işlemi tamamla
      user_states.delete(chat_id) # Durumu temizle
      bot.api.send_message(chat_id: chat_id, text: "E-posta adresiniz #{user_email} olarak kaydedildi. Kayıt tamamlandı!")
    else
      # ... (diğer komutlar)
    end
  end
end

Veritabanı Entegrasyonu (Basit bir örnek)

Daha kalıcı ve ölçeklenebilir durum yönetimi için bir veritabanı kullanmak idealdir. Ruby'de SQLite için sqlite3 gem'ini veya PostgreSQL için pg gem'ini ActiveRecord ile kullanabilirsiniz.


# Gemfile'a ekleyin:
# gem 'activerecord', '~> 7.0'
# gem 'sqlite3', '~> 1.4'

# config/database.yml
# development:
#   adapter: sqlite3
#   database: db/development.sqlite3

# db/migrate/20231027120000_create_users.rb
# class CreateUsers < ActiveRecord::Migration[7.0]
#   def change
#     create_table :users do |t|
#       t.bigint :telegram_chat_id, null: false, index: { unique: true }
#       t.string :name
#       t.string :email
#       t.string :state # Örneğin: 'waiting_for_name', 'waiting_for_email'
#       t.timestamps
#     end
#   end
# end

# app/models/user.rb
# class User < ActiveRecord::Base
#   # ...
# end

Ardından, botunuzda kullanıcı durumunu veritabanından okuyup güncelleyebilirsiniz.

Botu Dağıtma ve Canlıya Alma

Botunuzu geliştirdikten sonra, onu sürekli çalışır durumda tutmak için bir sunucuya dağıtmanız gerekir.

Long Polling ile Yerel Çalıştırma

Geliştirme aşamasında botunuzu yerel makinenizde ruby bot.rb komutuyla çalıştırabilirsiniz. Ancak bu, makineniz açık olduğu sürece çalışır ve internet bağlantınız kesildiğinde durur.

Webhook ile Dağıtımın Avantajları

Canlı bir ortamda, Webhook kullanmak genellikle daha verimlidir. Telegram, yeni bir mesaj geldiğinde botunuzun belirli bir URL'sine HTTP POST isteği gönderir. Bu, botunuzun sürekli Telegram sunucularını sorgulamasına gerek kalmadan sadece bir olay tetiklendiğinde çalışmasını sağlar.

Webhook kullanmak için, botunuzun bir HTTP sunucusu (örneğin Sinatra veya Rails ile) çalıştırması ve Telegram'a bu sunucunun URL'sini bildirmesi gerekir.


# Sinatra ile basit bir Webhook sunucusu örneği
# Gemfile'a ekleyin: gem 'sinatra'

# app.rb
require 'sinatra'
require 'telegram/bot'
require 'dotenv/load'

token = ENV['TELEGRAM_BOT_TOKEN']

post "/#{token}" do
  # Telegram'dan gelen JSON verisini ayrıştır
  update = Telegram::Bot::Types::Update.new(JSON.parse(request.body.read))
  message = update.message

  Telegram::Bot::Client.run(token) do |bot|
    if message && message.text == '/start'
      bot.api.send_message(chat_id: message.chat.id, text: "Merhaba Webhook!")
    end
  end
  'OK' # Telegram'a başarılı yanıt gönder
end

# Telegram'a webhook URL'ini bildirme (bir kez çalıştırılmalı)
# require 'net/http'
# uri = URI("https://api.telegram.org/bot#{token}/setWebhook?url=https://YOUR_DOMAIN/YOUR_BOT_TOKEN")
# Net::HTTP.get(uri)

Bu örnekte YOUR_DOMAIN yerine botunuzun canlıda çalıştığı alan adını, YOUR_BOT_TOKEN yerine de botunuzun token'ını yazmalısınız.

Hosting Seçenekleri (Heroku, Render, VPS)

Heroku/Render: PaaS (Platform as a Service) sağlayıcıları, Ruby uygulamalarını dağıtmak için popüler ve kullanımı kolay seçeneklerdir. Ücretsiz katmanları başlangıç için yeterli olabilir. Webhook kullanmak için idealdir.
VPS (Virtual Private Server): Daha fazla kontrol ve esneklik sağlar. Kendi sunucunuzu kurar ve botunuzu bir arka plan süreci olarak (örneğin, systemd veya pm2 ile) çalıştırırsınız. Long Polling veya Webhook için kullanılabilir.

Hata Yönetimi ve Güvenlik İpuçları

Her yazılım projesinde olduğu gibi, botunuzda da hata yönetimi ve güvenlik önemlidir.

Hata Yakalama ve Loglama

Botunuzun beklenmedik durumlarda çökmesini önlemek ve sorunları tespit etmek için hata yakalama (begin...rescue) ve loglama kullanın.


# ...
bot.listen do |message|
  begin
    # ... mesaj işleme kodu ...
  rescue => e
    puts "Bir hata oluştu: #{e.message}"
    # Hata detaylarını bir log dosyasına yazabilir veya size Telegram üzerinden bildirebilirsiniz.
    bot.api.send_message(chat_id: YOUR_ADMIN_CHAT_ID, text: "Botta bir hata oluştu: #{e.message}")
  end
end
# ...

API Token'ını Güvende Tutma

Daha önce de belirtildiği gibi, API token'ınızı asla doğrudan kodunuzda sabit bir değer olarak tutmayın. Daima ortam değişkenleri (ENV['TELEGRAM_BOT_TOKEN']) veya güvenli bir yapılandırma servisi kullanın. .env dosyasını .gitignore'a eklemeyi unutmayın.

Kullanıcı Verilerini İşleme ve Gizlilik

Botunuz kullanıcı verilerini (mesajlar, kullanıcı ID'leri, isimler vb.) topluyorsa, bu verileri nasıl sakladığınız ve işlediğiniz konusunda dikkatli olun. GDPR ve diğer gizlilik düzenlemelerine uyun. Yalnızca ihtiyacınız olan verileri toplayın ve güvenli bir şekilde saklayın.

Sonuç

Bu kapsamlı rehberde, Ruby ile bir Telegram botu oluşturmanın temel adımlarını, gelişmiş özelliklerini, durum yönetimini ve dağıtım stratejilerini öğrendiniz. Ruby'nin esnekliği ve telegram-bot-ruby gem'inin sunduğu kolaylıklar sayesinde, hayal gücünüzle sınırlı çeşitli botlar geliştirebilirsiniz. Unutmayın, pratik yapmak ve farklı API metodlarını denemek, bot geliştirme becerilerinizi ilerletmenin en iyi yoludur. Kendi botunuzu oluştururken iyi eğlenceler!

SSS (Sık Sorulan Sorular)

Telegram botu nedir?

Telegram botları, Telegram platformunda kullanıcılarla etkileşim kuran, otomatik görevler gerçekleştiren ve çeşitli servisleri entegre eden özel hesaplardır. Birçok farklı amaç için kullanılabilirler.

Ruby ile bot yapmak neden iyi bir fikir?

Ruby, okunabilir sözdizimi, geliştirici dostu yapısı ve zengin gem (kütüphane) ekosistemi sayesinde hızlı ve etkili bot geliştirme için harika bir dildir. telegram-bot-ruby gem'i, API ile etkileşimi oldukça basitleştirir.

BotFather nedir ve neden gereklidir?

BotFather, Telegram'da yeni botlar oluşturmanıza ve mevcut botlarınızı yönetmenize olanak tanıyan resmi bir Telegram botudur. Her yeni bot için benzersiz bir API token'ı sağlar ve bu token, botunuzun Telegram API'sine erişimi için hayati öneme sahiptir.

Botum neden çalışmıyor?

Botunuzun çalışmamasının birkaç nedeni olabilir:

API token'ınız yanlış veya eksik.
İnternet bağlantınız yok veya kararsız.
Kodunuzda bir hata var (konsol çıktılarını kontrol edin).
Gerekli gem'ler (telegram-bot-ruby, dotenv) kurulu değil.
Long Polling veya Webhook yapılandırmanızda bir sorun var.

Hata mesajlarını dikkatlice okuyarak ve kodunuzu adım adım kontrol ederek sorunu bulmaya çalışın.

Botumu nasıl canlıya alabilirim?

Botunuzu canlıya almak için onu sürekli çalışır durumda tutacak bir sunucuya ihtiyacınız vardır. Heroku veya Render gibi PaaS (Platform as a Service) sağlayıcıları veya kendi sanal sunucunuz (VPS) kullanabilirsiniz. Webhook yöntemini kullanmak, genellikle canlı ortamlar için daha verimli bir yaklaşımdır.

Ruby ile Telegram Botları Oluşturma Rehberi: Adım Adım Kapsamlı Bir Yaklaşım