n8n ile Telegram Bot Entegrasyonu: Adım Adım Rehber

Yazar:komut.io ekibi n8n ile Görsel İş Akışı Otomasyonu
0 Yorum

Telegram botları her şirketin altyapısında bir yerde mutlaka çıkıyor karşıma. Biri sunucu alertlerini göndermek istiyor, biri deployment bildirimlerini, biri de müşteri destek ekibine otomatik mesaj atmayı. Kodla yapmak mümkün tabii, ama n8n ile bu işi hem görsel hem de bakımı kolay bir şekilde halletmek bambaşka bir deneyim. Ben de bu yazıda sıfırdan bir n8n-Telegram entegrasyonunun nasıl kurulduğunu, gerçek dünyada ne işe yaradığını ve dikkat edilmesi gereken noktaları paylaşacağım.

n8n ve Telegram: Neden Bu İkili?

n8n, açık kaynaklı bir iş akışı otomasyon aracı. Self-hosted çalıştırabiliyorsunuz, bu da Türkiye’deki pek çok şirket için kritik bir avantaj, veri dışarıya çıkmıyor. Telegram ise hem API’si son derece güçlü hem de Türkiye’de yaygın kullanılan bir mesajlaşma platformu. Bu iki araç birleşince monitoring, alerting, approval workflow, günlük rapor gönderimi gibi onlarca senaryo ortaya çıkıyor.

n8n’in Telegram node’u oldukça olgun bir noktada. Mesaj gönderme, dosya gönderme, inline keyboard ile etkileşim, webhook’tan mesaj alma… Bunların hepsi node içinde hazır geliyor. Siz sadece iş mantığını kuruyorsunuz.

Önce Altyapıyı Hazırlayalım

n8n Kurulumu (Docker ile)

Eğer n8n’i henüz kurmadıysanız Docker ile çalıştırmak en pratik yol. Bir docker-compose.yml dosyası oluşturun:

mkdir -p ~/n8n-stack && cd ~/n8n-stack
cat > docker-compose.yml << 'EOF'
version: '3.8'

services:
  n8n:
    image: n8nio/n8n:latest
    restart: unless-stopped
    ports:
      - "5678:5678"
    environment:
      - N8N_BASIC_AUTH_ACTIVE=true
      - N8N_BASIC_AUTH_USER=admin
      - N8N_BASIC_AUTH_PASSWORD=guclu_sifrenizi_buraya_yazin
      - N8N_HOST=n8n.sirketiniz.com
      - N8N_PORT=5678
      - N8N_PROTOCOL=https
      - WEBHOOK_URL=https://n8n.sirketiniz.com/
      - GENERIC_TIMEZONE=Europe/Istanbul
    volumes:
      - n8n_data:/home/node/.n8n

volumes:
  n8n_data:
EOF

docker-compose up -d

GENERIC_TIMEZONE=Europe/Istanbul ayarı önemli. Bunu yazmadığınızda schedule trigger’lar UTC üzerinden çalışıyor ve “saat 09:00’da rapor gönder” dediğinizde 12:00’de geldiğini görüyorsunuz.

Telegram Bot Oluşturma

BotFather üzerinden bot oluşturmak birkaç dakika sürüyor:

# Telegram'da @BotFather'a gidip şu komutu gönderin:
# /newbot
# Bot adını ve username'i girdikten sonra bir token alacaksınız:
# Örnek: 7123456789:AAHxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Bu token'ı bir yere not edin, n8n'de credentials olarak ekleyeceksiniz

# Chat ID'yi öğrenmek için botunuza bir mesaj gönderin, sonra:
curl "https://api.telegram.org/bot<TOKEN>/getUpdates"

getUpdates endpoint’i size JSON döndürür. İçinde chat.id alanını bulun, bu sizin chat ID’niz. Grup chat’leri için negatif sayı olur (-100xxxxxxxx formatında), bireysel chat’ler için pozitif.

n8n’de Telegram Credentials Ekleme

n8n arayüzünde sol menüden Credentials bölümüne gidin, New Credential deyip Telegram API seçin. BotFather’dan aldığınız token’ı yapıştırın. Bu kadar. n8n, token’ı güvenli şekilde saklıyor ve tüm workflow’larınızda bu credential’ı kullanabiliyorsunuz.

Senaryo 1: Sunucu Alert Bildirimleri

Bu en klasik kullanım senaryosu. Bir şeylerin patladığını Telegram’dan öğrenmek email’den çok daha hızlı ve pratik.

Webhook Tabanlı Alert Sistemi

n8n’de yeni bir workflow oluşturun. Trigger olarak Webhook node ekleyin. Bu size bir URL verecek, örneğin: https://n8n.sirketiniz.com/webhook/server-alert

Alertmanager, Grafana, Zabbix ya da kendi scriptle bu URL’e POST atabilirsiniz. Ben genellikle basit bir bash scripti ile test ederim:

#!/bin/bash
# test_alert.sh
WEBHOOK_URL="https://n8n.sirketiniz.com/webhook/server-alert"
HOSTNAME=$(hostname)
CPU_USAGE=$(top -bn1 | grep "Cpu(s)" | awk '{print $2}' | cut -d'%' -f1)
MEMORY_USAGE=$(free | grep Mem | awk '{print int($3/$2 * 100)}')
DISK_USAGE=$(df / | tail -1 | awk '{print $5}' | sed 's/%//')

curl -s -X POST "$WEBHOOK_URL" 
  -H "Content-Type: application/json" 
  -d "{
    "hostname": "$HOSTNAME",
    "cpu": $CPU_USAGE,
    "memory": $MEMORY_USAGE,
    "disk": $DISK_USAGE,
    "timestamp": "$(date '+%Y-%m-%d %H:%M:%S')"
  }"

n8n workflow’unda Webhook node’undan sonra bir Function node ile veriyi işleyebilirsiniz. Telegram node’una bağlamadan önce mesajı formatlamak için:

// n8n Function Node - Alert Mesajı Formatla
const data = $input.first().json;

const emoji = data.cpu > 80 ? '🔴' : data.cpu > 60 ? '🟡' : '🟢';

const message = `${emoji} *Sunucu Alert - ${data.hostname}*

📊 *Sistem Durumu*
CPU Kullanımı: `${data.cpu}%`
RAM Kullanımı: `${data.memory}%`
Disk Kullanımı: `${data.disk}%`

🕐 ${data.timestamp}

${data.cpu > 80 ? '⚠️ CPU kullanımı kritik seviyede!' : ''}
${data.memory > 90 ? '⚠️ Bellek dolmak üzere!' : ''}
${data.disk > 85 ? '⚠️ Disk alanı azalıyor!' : ''}`;

return [{ json: { message } }];

Bu node’un çıktısını Telegram node’una bağladığınızda Send Message action’ını seçin, Chat ID alanına grup veya kişi ID’nizi yazın, Text alanına {{ $json.message }} ifadesini, Parse Mode olarak da Markdown seçin.

Senaryo 2: Günlük Rapor Otomasyonu

Sabah 09:00’da günlük sistem raporunu Telegram grubuna otomatik atmak, ekibin güne hazırlıklı başlaması açısından oldukça değerli. Bunun için Cron trigger kullanacağız.

# n8n'de Schedule Trigger yerine
# Execute Command node ile bu scripti çalıştırabilirsiniz:

#!/bin/bash
# daily_report.sh
echo "{"
echo "  "date": "$(date '+%d.%m.%Y')","
echo "  "uptime": "$(uptime -p)","
echo "  "load": "$(uptime | awk -F'load average:' '{print $2}' | xargs)","
echo "  "disk_free": "$(df -h / | tail -1 | awk '{print $4}')","
echo "  "memory_free": "$(free -h | grep Mem | awk '{print $7}')","
echo "  "failed_services": $(systemctl list-units --state=failed --no-legend | wc -l)"
echo "}"

Workflow şu şekilde kurulur:

  • Schedule Trigger (Her gün 09:00)
  • Execute Command Node (bash scripti çalıştır)
  • Function Node (JSON parse et, mesaj formatla)
  • Telegram Node (gruba gönder)

Schedule Trigger’da Cron expression olarak 0 9 1-5 yazarsanız sadece hafta içi günler çalışır. Türk sysadmin’ler hafta sonu mesajla uyanmak istemez.

Senaryo 3: İki Yönlü Komut Sistemi (Bot’a Komut Göndermek)

Bu senaryo biraz daha eğlenceli. Telegram’dan n8n workflow’una komut gönderip yanıt almak. Bunun için Telegram Trigger node’unu kullanıyoruz, bu node Telegram’ın webhook’una dinleyici kuruyor.

Önce botunuza webhook set etmeniz gerekiyor. n8n bunu otomatik yapıyor ama manuel kontrol etmek isterseniz:

# Webhook durumunu kontrol et
curl "https://api.telegram.org/bot<TOKEN>/getWebhookInfo"

# Manuel set etmek isterseniz (n8n normalde bunu halleder):
curl -X POST "https://api.telegram.org/bot<TOKEN>/setWebhook" 
  -H "Content-Type: application/json" 
  -d '{"url": "https://n8n.sirketiniz.com/webhook/telegram-bot"}'

n8n’de Telegram Trigger node’u ekleyip activate ettiğinizde webhook otomatik register oluyor. Sonraki adımda bir Switch node ile gelen komutu yönlendirin:

// Function Node - Gelen mesajı parse et
const message = $input.first().json.message;
const text = message?.text || '';
const chatId = message?.chat?.id;
const from = message?.from?.username || 'Bilinmeyen';

// Komutu normalize et
const command = text.split(' ')[0].toLowerCase().replace('@botusername', '');

return [{
  json: {
    command,
    chatId,
    from,
    rawText: text
  }
}];

Switch node’da /durum, /disk, /servisler gibi komutları farklı dallara yönlendirip her dal için farklı bir Execute Command node çalıştırabilirsiniz. Sonuçları tekrar Telegram node ile geri gönderirsiniz.

# /disk komutuna karşılık gelen script
df -h | awk 'NR==1 || /^/dev/' | while read line; do echo "$line"; done
# /servisler komutuna karşılık gelen script
systemctl list-units --type=service --state=running --no-legend 
  | awk '{print $1, $3, $4}' 
  | head -20

Senaryo 4: Deployment Bildirimleri

CI/CD pipeline’larında deployment başladığında ve bittiğinde Telegram’a bildirim atmak takımın koordinasyonu açısından hayat kurtarıyor. GitLab CI örneği:

# .gitlab-ci.yml içinde notify stage
notify_deploy_start:
  stage: notify
  script:
    - |
      curl -s -X POST "https://n8n.sirketiniz.com/webhook/deploy-notify" 
        -H "Content-Type: application/json" 
        -d "{
          "event": "deploy_started",
          "project": "$CI_PROJECT_NAME",
          "branch": "$CI_COMMIT_BRANCH",
          "commit": "$CI_COMMIT_SHORT_SHA",
          "user": "$GITLAB_USER_NAME",
          "environment": "$CI_ENVIRONMENT_NAME"
        }"
  when: always

n8n tarafında bu webhook’u karşılayan workflow, deployment event türüne göre farklı mesajlar oluşturabiliyor. deploy_started geldiğinde sarı emoji, deploy_success geldiğinde yeşil, deploy_failed geldiğinde kırmızı ve ilgili kişiyi mention’layan bir mesaj.

Hata Yönetimi ve Güvenilirlik

Gerçek dünyada workflow’lar zaman zaman patlıyor. n8n’de hata yönetimi için birkaç kritik ayar var:

Error Trigger Node: Herhangi bir workflow hata verdiğinde devreye giren ayrı bir workflow tanımlayabilirsiniz. Bu workflow yine Telegram’a hata bildirimi atabilir. Biraz recursive geliyor ama çalışıyor.

Retry Mekanizması: Her node’un ayarlarında Retry On Fail seçeneği var. Özellikle Telegram API bazen rate limit döndürüyor. 3 retry, 5 saniye bekleme ile çoğu geçici sorun kendiliğinden çözülüyor.

Rate Limiting: Telegram botlarının mesaj gönderme limiti var. Bir gruba saniyede 1 mesaj, dakikada 20 mesaj gibi bir kısıt söz konusu. Yüksek hacimli alert senaryolarında n8n içinde bir Wait node koyarak mesajları throttle etmeniz gerekebilir.

// Toplu alert'leri birleştirmek için Function Node örneği
const items = $input.all();

if (items.length === 0) return [];

// Birden fazla alert varsa tek mesajda birleştir
const alertList = items.map((item, i) => 
  `${i + 1}. ${item.json.hostname}: ${item.json.message}`
).join('n');

const combinedMessage = `🚨 *${items.length} Alert Alındı*nn${alertList}nn🕐 ${new Date().toLocaleString('tr-TR')}`;

return [{ json: { message: combinedMessage, count: items.length } }];

Güvenlik Notları

Telegram botları internet üzerinden erişilebilir durumda olduğu için birkaç önlem şart:

Whitelist uygulamak: Gelen mesajları işlemeden önce chat ID’yi kontrol edin. Sadece bilinen chat ID’lerden gelen komutlara yanıt verin. n8n’de bunu bir IF node ile kolayca yapabilirsiniz.

Webhook URL’lerini gizli tutun: n8n webhook URL’lerinize rastgele path ekleyin. /webhook/alert yerine /webhook/alert-x7k9m2p4 gibi tahmin edilmesi zor bir path kullanın. Token gibi davranın bu URL’lere.

n8n’i reverse proxy arkasına alın: Nginx veya Traefik ile HTTPS termination yapın, n8n’i doğrudan dışarıya açmayın.

# Nginx basit reverse proxy konfigürasyonu
# /etc/nginx/sites-available/n8n
server {
    listen 443 ssl;
    server_name n8n.sirketiniz.com;

    ssl_certificate /etc/letsencrypt/live/n8n.sirketiniz.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/n8n.sirketiniz.com/privkey.pem;

    location / {
        proxy_pass http://localhost:5678;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_cache_bypass $http_upgrade;
    }
}

Workflow’ları Dışa Aktarma ve Versiyon Kontrolü

n8n workflow’larını JSON olarak export edip Git’e atabilirsiniz. Bu özelliği çok az kişinin kullandığını görüyorum ama son derece değerli. n8n arayüzünde workflow’u açıp Export deyince JSON dosyası iniyor. Bu dosyayı repo’nuzda n8n-workflows/ klasöründe tutun. Ekip üyeleri kendi ortamlarına import edebilir, değişiklikler commit mesajlarıyla takip edilebilir.

# n8n CLI ile workflow'ları export etmek (n8n container içinde)
docker exec -it n8n-stack_n8n_1 n8n export:workflow --all --output=/home/node/.n8n/workflows/

# Veya belirli bir workflow'u:
docker exec -it n8n-stack_n8n_1 n8n export:workflow --id=5 --output=/home/node/.n8n/workflows/alert-workflow.json

Performans ve İzleme

n8n’in kendi execution history’si var ama uzun vadede bu tablo şişiyor. Production ortamında execution history retention’ı sınırlamak önemli:

# docker-compose.yml'e eklenecek environment değişkenleri
environment:
  - EXECUTIONS_DATA_MAX_AGE=168        # 7 gün (saat cinsinden)
  - EXECUTIONS_DATA_PRUNE=true
  - EXECUTIONS_DATA_PRUNE_MAX_COUNT=5000

Yoğun kullanımda n8n’in SQLite yerine PostgreSQL ile çalışmasını öneririm. Özellikle aynı anda çok fazla webhook geldiğinde SQLite’ın dosya kilitleme sorunu çıkabiliyor.

Sonuç

n8n ve Telegram kombinasyonu, bir sistem yöneticisinin araç kutusunda kesinlikle bulunması gereken bir çift. Kod yazmadan ya da minimal kod ile karmaşık otomasyon senaryoları kurabiliyorsunuz. Alert sistemi, günlük raporlar, deployment bildirimleri, interactive bot komutları… Bunların hepsini tek bir platform üzerinde yönetmek bakım maliyetini ciddi ölçüde düşürüyor.

Başlangıç için şunu öneririm: İlk olarak basit bir sunucu ping kontrolü yapın, başarısızsa Telegram’a yazsın. Tek node, beş dakika. Çalıştığını görünce gerisi kendiliğinden geliyor. n8n’in görsel arayüzü o “bir şeyleri birleştirme” isteğini tetikliyor, bir bakmışsınız on tane workflow yazmışsınız.

Self-hosted çalıştırdığınız için veriniz sizde kalıyor, Telegram token’ınız üçüncü parti bir servise gitmiyor ve aylık abonelik ödemenize gerek yok. Açık kaynak dünyasının güzel taraflarından biri bu.

Bir yanıt yazın

E-posta adresiniz yayınlanmayacak. Gerekli alanlar * ile işaretlenmişlerdir