Telegram Bot API

n8n Telegram entegrasyonu: botu bağlama, workflow tetikleme ve mesaj gönderme

· 8 dk okuma

n8n'i Telegram'a bağlamak için Telegram'dan tek bir şeye ihtiyacınız var: bot token'ı. Onu n8n'de bir Telegram credential'ının Access Token alanına kaydedin, ardından gelen mesajlarla workflow başlatmak için Telegram Trigger node'unu, bir chat id'ye mesaj göndermek için Telegram node'unu kullanın. Tetikleyici Bot API webhook'u üzerinden çalıştığı için n8n örneğinizin herkese açık bir HTTPS URL'den erişilebilir olması gerekir. Bu rehberde kurulumu, self-hosted n8n'in ihtiyaç duyduğu yapılandırmayı ve en sık karşılaşılan hataları anlatıyoruz.

n8n Telegram entegrasyonu nasıl çalışır?

NodeNe yaparArka planda Bot APIHerkese açık HTTPS gerekir mi?
Telegram TriggerBir güncellemeyle workflow'u başlatır: mesaj, buton basışı, kanal gönderisi vb.setWebhook, ardından Telegram güncellemeleri n8n'e POST ederEvet
TelegramMesaj gönderir ve düzenler, dosya gönderir, callback query'leri yanıtlar, sohbet bilgisi okursendMessage, sendPhoto, editMessageText, answerCallbackQuery…Hayır, yalnızca giden istekler

Tetikleyici webhook kullandığı için Bot API'nin webhook kuralları n8n için de geçerlidir: yalnızca HTTPS, 443, 80, 88 veya 8443 portu, bot başına tek webhook URL'si ve webhook kuruluyken getUpdates yok.

1. adım: bot oluşturun ve token'ı alın

  1. @BotFather'ı açın, /newbot gönderin, bir görünen ad ve bot ile biten bir kullanıcı adı seçin.
  2. BotFather'ın verdiği token'ı kopyalayın. 123456789:AAEexampleTokenReplaceWithYours gibi görünür. Mevcut bir bot için /mybots → botunuz → API Token yolunu izleyin.
  3. Token'ı bir yere yapıştırmadan önce kontrol edin:
curl "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/getMe"

Geçerli token botun bilgileriyle birlikte "ok": true döndürür; yanlış token 401 Unauthorized döndürür. Aynı kontrolü Bot API Tester'da getMe ile de yapabilirsiniz. Token bulma, kontrol etme ve iptal etme ayrıntıları Telegram bot token rehberinde; henüz botunuz yoksa Telegram bot oluşturma rehberiyle başlayın.

2. adım: n8n'de Telegram credential ekleyin

n8n, Telegram'a yalnızca bot token'ıyla kimlik doğrular. Yeni bir Telegram credential oluşturun ve token'ı Access Token alanına yapıştırın. Telegram node'u ve Telegram Trigger node'u aynı credential türünü kullanır, bu yüzden bot başına bir credential yeterlidir.

Token'a parola gibi davranın: ona sahip olan herkes botu kontrol eder. Sızarsa @BotFather'da iptal edin ve n8n'deki credential'ı güncelleyin.

3. adım: n8n Telegram Trigger webhook'u ile güncelleme alın

Bir Telegram Trigger node'u ekleyin, credential'ınızı seçin ve workflow'u hangi güncellemelerin başlatacağını belirleyin. Tipik seçimler gelen mesajlar için Message ve inline buton basışları için Callback Query'dir; * sohbet üyesi ve tepki (reaction) güncellemeleri hariç tüm güncellemeler demektir ve Bot API varsayılanıyla aynıdır. Node belirli chat id'leri veya user id'lerle sınırlandırılabilir, ekli görselleri ve dosyaları da indirebilir.

Workflow'u test ettiğinizde veya yayınladığınızda n8n, kendi örneğine ait bir URL ile botunuz için setWebhook çağırır. Bundan sonra Telegram her güncellemeyi n8n'e HTTPS POST olarak gönderir. Bunun iki sonucu vardır:

Self-hosted n8n'i HTTPS ile erişilebilir yapma

n8n Cloud'un zaten herkese açık bir HTTPS adresi vardır. Self-hosted bir örnek webhook URL'lerini kendi protokol, host ve portundan oluşturur; bu da reverse proxy arkasında veya localhost'ta genellikle Telegram'ın reddettiği bir http:// adresidir. Çözüm:

  1. n8n'i, 443 portunda geçerli bir sertifikayla TLS'i sonlandıran bir reverse proxy'nin (nginx, Caddy, Traefik vb.) arkasına koyun.
  2. n8n'e herkese açık adresini bildirin. Güncel n8n sürümleri N8N_WEBHOOK_URL kullanır; eski WEBHOOK_URL n8n 2.35.0'dan beri kullanımdan kalkmıştır (deprecated) ama hâlâ okunur, 2.30.0'dan önceki sürümler ise yalnızca WEBHOOK_URL'yi tanır.
  3. N8N_PROXY_HOPS=1 ayarlayın ve proxy'den X-Forwarded-For, X-Forwarded-Host ve X-Forwarded-Proto başlıklarını iletin.
  4. WebSocket proxy'lemeyi açın, aksi halde editör test tetikleyici olayını beklerken takılmış gibi görünebilir.
  5. n8n'i yeniden başlatın ve tetikleyicinin yeni HTTPS URL'sini kaydetmesi için workflow'u yeniden etkinleştirin.
# https://n8n.example.com adresini sunan bir reverse proxy arkasında n8n
export N8N_WEBHOOK_URL=https://n8n.example.com/
export N8N_PROXY_HOPS=1
# 2.30.0'dan önceki n8n sürümleri: bunun yerine WEBHOOK_URL kullanın
# export WEBHOOK_URL=https://n8n.example.com/

Yerel geliştirmede, size herkese açık bir HTTPS host adı veren bir tünel de aynı şekilde çalışır: o host adını N8N_WEBHOOK_URL'ye yazın. Tünel adresi her değiştiğinde webhook'un bozulacağını unutmayın.

Telegram'da botunuz için hangi webhook'un kayıtlı olduğunu kontrol edin

Tetikleyici sessiz kalıyorsa doğrudan Telegram'a getWebhookInfo ile sorun. Kayıtlı URL'yi, bekleyen güncelleme sayısını ve son teslim hatasını gösterir. Bu betik kısa bir teşhis yazdırır:

import os
import requests

TOKEN = os.environ["BOT_TOKEN"]  # n8n credential'ındaki token'ın aynısı
API = f"https://api.telegram.org/bot{TOKEN}"

data = requests.get(f"{API}/getWebhookInfo", timeout=10).json()
if not data["ok"]:
    raise SystemExit(f"{data['error_code']} {data['description']}")  # 401: yanlış token

info = data["result"]
print("Webhook URL:", info["url"] or "(yok: aktif Telegram Trigger bulunmuyor)")
print("Bekleyen güncellemeler:", info["pending_update_count"])
if info["url"] and not info["url"].startswith("https://"):
    print("Sorun: Telegram HTTPS URL istiyor")
if "last_error_message" in info:
    print("Son teslim hatası:", info["last_error_message"])
const TOKEN = process.env.BOT_TOKEN; // n8n credential'ındaki token'ın aynısı
const API = `https://api.telegram.org/bot${TOKEN}`;

const data = await (await fetch(`${API}/getWebhookInfo`)).json();
if (!data.ok) {
  console.error(`${data.error_code} ${data.description}`); // 401: yanlış token
  process.exit(1);
}

const info = data.result;
console.log("Webhook URL:", info.url || "(yok: aktif Telegram Trigger bulunmuyor)");
console.log("Bekleyen güncellemeler:", info.pending_update_count);
if (info.url && !info.url.startsWith("https://")) {
  console.log("Sorun: Telegram HTTPS URL istiyor");
}
if (info.last_error_message) {
  console.log("Son teslim hatası:", info.last_error_message);
}

JavaScript sürümünü check.mjs olarak kaydedin ve Node.js 18 veya üstüyle çalıştırın. Sonucu şöyle okuyun: başka bir servise ait URL, botun webhook'unu başka bir şeyin devraldığı anlamına gelir; last_error_message ile birlikte artan bir pending_update_count ise Telegram'ın n8n'e ulaşamadığını veya n8n'in hata döndürdüğünü gösterir. Kod yazmadan Bot API Tester'da getWebhookInfo kullanın.

4. adım: n8n'den Telegram mesajı gönderin

Bir Telegram node'u ekleyin, Message kaynağını ve Send Message işlemini seçin, credential'ı belirleyin ve iki alanı doldurun:

İki varsayılan ayar insanları şaşırtır. Node mesajın sonuna This message was sent automatically with n8n satırını ekler; kaldırmak için ek alanlardaki Append n8n Attribution seçeneğini kapatın. Ayrıca node'un parse mode'u varsayılan olarak HTML'dir; dinamik metindeki <, > ve & karakterlerini &lt;, &gt; ve &amp; olarak kaçışlayın, aksi halde Telegram mesajı can't parse entities hatasıyla reddeder.

Bir chat id'yi workflow'a bağlamadan önce Bot API Tester'da sendMessage ile tek bir istekle çalıştığını doğrulayabilirsiniz. Bir kanala gönderi yapmak için önce botu kanal yöneticisi olarak ekleyin. Telegram toplu gönderimde saniyede yaklaşık 30, tek bir sohbette saniyede yaklaşık bir mesaja izin verir; toplu gönderim döngülerini yavaşlatın, bkz. Telegram Bot API limitleri.

Chat id'yi bulma

En kolay kaynak tetikleyicinin kendisidir: workflow'u çalıştırın, bota mesaj atın ve tetikleyici çıktısında message.chat.id değerini okuyun. Kullanıcıların id'leri pozitif, grupların negatiftir; süper gruplar ve kanallar -1001234567890 gibi görünür. getUpdates tercih ediyorsanız bu bot için herhangi bir Telegram Trigger aktif olmadan önce çağırın; webhook kuruluyken 409 Conflict ile başarısız olur. Gruplar, kanallar ve forum konuları dahil tüm yöntemler Telegram chat id nasıl bulunur rehberinde.

n8n Telegram hatalarını giderme

BelirtiNedenÇözüm
Bad Request: bad webhook: An HTTPS URL must be provided for webhookn8n bir http:// URL'si kaydetti: localhost veya TLS'siz proxyTLS'i proxy'de sonlandırın ve N8N_WEBHOOK_URL (veya WEBHOOK_URL) değerini HTTPS adresine ayarlayın
Porttan bahseden bad webhook hatasıHerkese açık URL 443, 80, 88 veya 8443 dışında bir port kullanıyorn8n'i proxy üzerinden 443 portunda yayınlayın
getUpdates'ten 409 ConflictBir Telegram Trigger webhook'u kayıtlı tutuyorWorkflow'u devre dışı bırakıp deleteWebhook çağırın veya chat id'leri tetikleyiciden alın
Workflow yalnızca testte ya da yalnızca yayındayken çalışıyorTest ve üretim webhook URL'leri birbirinin yerine geçiyorTest ederken yayından kaldırın veya ayrı bir test botu kullanın
Başka bir workflow etkinleşince tetikleyici durduİkinci bir tetikleyici veya başka bir servis aynı token'la setWebhook çağırdıBot başına bir tetikleyici; URL'yi getWebhookInfo ile kontrol edin
Editör “waiting for trigger event” durumunda takılıWebSocket desteği olmayan reverse proxyWebSocket proxy'lemeyi açın, ardından workflow'u yeniden açın
Grup mesajları için güncelleme gelmiyorGizlilik modu: gruplarda bot yalnızca kendisine yönelik komutları, kendisine verilen yanıtları ve servis mesajlarını alır/setprivacy ile gizliliği kapatın veya botu yönetici yapın
401 UnauthorizedCredential'da yanlış veya iptal edilmiş tokengetMe ile kontrol edin ve güncel token'ı yapıştırın
Gönderirken 400 Bad Request: chat not foundYanlış chat id veya botun erişemediği bir sohbet: kullanıcı botu hiç başlatmamış ya da bot grupta değilid'yi yeniden kontrol edin; kullanıcıdan /start göndermesini isteyin veya botu gruba ekleyin

Temiz bir başlangıç için workflow'u devre dışı bırakın, deleteWebhook çağırın, getWebhookInfo'nun boş bir url gösterdiğini kontrol edin, ardından n8n'in URL'sini baştan kaydetmesi için workflow'u yeniden etkinleştirin. Genel webhook mekaniği (secret token, tekrar denemeler, sertifikalar) için Telegram bot webhook rehberine bakın.

Sık sorulan sorular

Telegram'ı n8n'e nasıl bağlarım?

@BotFather ile bir bot oluşturun, token'ını kopyalayın ve n8n'de bir Telegram credential'ının Access Token alanına kaydedin. Mesaj almak için Telegram Trigger node'unu, göndermek için Telegram node'unu kullanın; ikisi de aynı credential'ı kullanır.

n8n Telegram Trigger neden “An HTTPS URL must be provided for webhook” diyor?

Tetikleyici setWebhook ile bir webhook kaydeder ve Telegram yalnızca herkese açık HTTPS URL'leri kabul eder. n8n http://localhost üzerinde veya TLS'siz bir proxy arkasında çalışıyorsa örneğinizin herkese açık HTTPS adresini N8N_WEBHOOK_URL değişkenine (eski sürümlerde WEBHOOK_URL) yazın ve TLS'i reverse proxy'de sonlandırın.

İki n8n workflow'u aynı Telegram bot tetikleyicisini kullanabilir mi?

Güvenilir şekilde hayır. Bir botun tam olarak bir webhook URL'si vardır; her etkinleştirme öncekinin üzerine yazar ve güncellemeleri yalnızca son workflow alır. Bot başına bir tetikleyici kullanın, yönlendirmeyi tek workflow içinde yapın veya ayrı bir bot oluşturun.

n8n'i kurduktan sonra getUpdates neden 409 Conflict döndürüyor?

Aktif bir Telegram Trigger bot için kayıtlı bir webhook tutar ve webhook kuruluyken getUpdates çalışmaz. Polling'e ihtiyacınız varsa workflow'u devre dışı bırakıp deleteWebhook çağırın ya da chat id'leri tetikleyicinin çıktısından okuyun.

n8n'den sadece Telegram mesajı göndermek için herkese açık HTTPS URL gerekir mi?

Hayır. Telegram node'u yalnızca api.telegram.org adresine giden istekler yapar, bu yüzden yerel bir n8n'den de mesaj gönderebilirsiniz. Herkese açık HTTPS yalnızca Telegram Trigger ile güncelleme almak için gereklidir.

n8n Telegram node'u için chat id'yi nereden bulurum?

Tetikleyici çıktısından (message.chat.id) alın veya tetikleyici aktif olmadan önce bota mesaj atıp getUpdates çağırın. Herkese açık kanallar @channelusername biçimini de kabul eder.

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 botu nasıl deploy edilir: VPS, Docker ve serverless hosting

Telegram botu sunucuya kurma: polling mi webhook mu, VPS'te systemd servisi, Docker, secret_token ile Cloudflare Workers ve yayın öncesi kontrol listesi.

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.

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.