Telegram bot komutları: setMyCommands, komut kapsamları ve /start deep link
Telegram bot komutları, Telegram uygulamalarının mesajlarda vurguladığı, kullanıcı / yazdığında önerdiği ve bot menüsünde listelediği /start veya /help gibi anahtar kelimelerdir. Listeyi @BotFather'da /setcommands ile veya setMyCommands metoduyla ayarlarsınız; metot ayrıca kapsamları (gruplar, yöneticiler ya da tek bir sohbet için farklı komutlar) ve dile göre listeleri destekler. Botunuz komutu sıradan bir metin mesajı olarak alır, /start ise bir deep link parametresi taşıyabilir. Bu rehberde hepsini curl, Python ve JavaScript örnekleriyle anlatıyoruz.
Telegram bot komutları nasıl çalışır?
Komut, metni / ile başlayan bir mesajdan ibarettir. Komutları kaydetmek botunuzun aldığı şeyi değiştirmez; yalnızca Telegram uygulamalarına neyi önereceklerini söyler. setMyCommands ile kaydettiğiniz liste (BotCommand nesnesi) için kurallar:
command: 1–32 karakter, yalnızca küçük İngilizce harfler, rakamlar ve alt çizgi; baştaki eğik çizgi olmadan yazılır.description: 1–256 karakter, öneri listesinde komutun yanında görünür.- Liste başına en fazla 100 komut.
Telegram her bottan genel komutları desteklemesini ister: /start (etkileşimi başlatır, deep link parametrelerini de alır) ve /help (botun neler yapabildiği ve komut listesi); botun ayarları varsa /settings. Ek argüman gerektiren genel bir /new yerine /newlocation gibi net komutları tercih edin.
@BotFather ile komut ekleme
Kod gerektirmeyen yol, sabit bir liste için idealdir:
- @BotFather'ı açın ve
/setcommandsgönderin. - Botunuzu seçin.
- Listeyi her satıra bir komut gelecek şekilde
komut - açıklamabiçiminde gönderin:
start - Botu başlat
help - Bot nasıl kullanılır
settings - Ayarlarınız
Henüz botunuz yoksa Telegram bot oluşturma rehberiyle başlayın.
setMyCommands ile komut ayarlama
setMyCommands aynı işi koddan yapar; böylece komut listesi deponuzda durur ve her deploy'da güncellenir. Parametreler: commands (zorunlu, BotCommand dizisi), scope (isteğe bağlı, varsayılan kapsam default) ve language_code (isteğe bağlı, iki harfli ISO 639-1 kodu). Metot true döndürür:
curl "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/setMyCommands" \
-H "Content-Type: application/json" \
-d '{"commands":[{"command":"start","description":"Botu başlat"},{"command":"help","description":"Bot nasıl kullanılır"}]}'
Kod yazmadan denemek için Bot API Tester'da setMyCommands metodunu açın, token'ınızı yapıştırın, komutları doldurup Execute'a basın. Ardından kayıtlı listeyi görmek için getMyCommands çağırın.
Komut kapsamları ve diller
Kapsam (scope), listeyi kimin göreceğini belirler. 7 BotCommandScope türü vardır:
Kapsam type | Listeyi kim görür | Ek alanlar |
|---|---|---|
default | Daha dar bir liste yoksa herkes | — |
all_private_chats | Botla yapılan tüm özel sohbetler | — |
all_group_chats | Tüm gruplar ve süper gruplar | — |
all_chat_administrators | Tüm grup ve süper grupların yöneticileri | — |
chat | Belirli bir sohbet | chat_id |
chat_administrators | Tek bir grup veya süper grubun yöneticileri | chat_id |
chat_member | Tek bir grup veya süper gruptaki tek bir üye | chat_id, user_id |
chat_id sayısal bir id veya süper grubun @username değeridir; kanallar ve kanal mesaj (direct messages) sohbetleri desteklenmez. Her kapsamın dile göre listeleri de olabilir: language_code verilirse liste o uygulama diline sahip kullanıcılara, verilmezse kapsamda kendi dili için ayrı listesi olmayan herkese gider.
Telegram en dar kapsamdan başlayarak tanımlanmış ilk listeyi gösterir. Özel sohbette sıra chat → all_private_chats → default; gruplarda chat_member → chat_administrators → chat → all_chat_administrators → all_group_chats → default şeklindedir (yönetici kapsamları yalnızca yöneticilere uygulanır). Her adımda kullanıcının language_code değerine ait liste, dilsiz listeye üstün gelir.
Bu betik varsayılan bir liste, İngilizce bir çeviri ve grup yöneticileri için ek komutlar ayarlar, ardından birini geri okur:
import os
import requests
TOKEN = os.environ["BOT_TOKEN"]
API = f"https://api.telegram.org/bot{TOKEN}"
def call(method, **params):
data = requests.post(f"{API}/{method}", json=params, timeout=10).json()
if not data["ok"]:
raise RuntimeError(f"{method}: {data['error_code']} {data['description']}")
return data["result"]
# Herkes için varsayılan liste
call("setMyCommands", commands=[
{"command": "start", "description": "Botu başlat"},
{"command": "help", "description": "Bot nasıl kullanılır"},
{"command": "settings", "description": "Ayarlarınız"},
])
# Telegram uygulaması İngilizce olan kullanıcılar için aynı komutlar
call("setMyCommands", language_code="en", commands=[
{"command": "start", "description": "Start the bot"},
{"command": "help", "description": "How to use the bot"},
{"command": "settings", "description": "Your settings"},
])
# Tüm grupların yöneticileri için ek komutlar
call("setMyCommands", scope={"type": "all_chat_administrators"}, commands=[
{"command": "help", "description": "Bot nasıl kullanılır"},
{"command": "stats", "description": "Grup istatistikleri"},
])
print(call("getMyCommands", scope={"type": "all_chat_administrators"}))const TOKEN = process.env.BOT_TOKEN;
const API = `https://api.telegram.org/bot${TOKEN}`;
async function call(method, params = {}) {
const res = await fetch(`${API}/${method}`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(params),
});
const data = await res.json();
if (!data.ok) throw new Error(`${method}: ${data.error_code} ${data.description}`);
return data.result;
}
// Herkes için varsayılan liste
await call("setMyCommands", {
commands: [
{ command: "start", description: "Botu başlat" },
{ command: "help", description: "Bot nasıl kullanılır" },
{ command: "settings", description: "Ayarlarınız" },
],
});
// Telegram uygulaması İngilizce olan kullanıcılar için aynı komutlar
await call("setMyCommands", {
language_code: "en",
commands: [
{ command: "start", description: "Start the bot" },
{ command: "help", description: "How to use the bot" },
{ command: "settings", description: "Your settings" },
],
});
// Tüm grupların yöneticileri için ek komutlar
await call("setMyCommands", {
scope: { type: "all_chat_administrators" },
commands: [
{ command: "help", description: "Bot nasıl kullanılır" },
{ command: "stats", description: "Grup istatistikleri" },
],
});
console.log(await call("getMyCommands", { scope: { type: "all_chat_administrators" } }));Kapsamlar yalnızca kullanıcıların ne gördüğünü belirler. Güncellemeler komutun hangi kapsamdan geldiğini söylemez ve kullanıcılar hiç kaydetmediğiniz komutlar dahil her şeyi yazabilir. Komutun var olduğunu ve kullanıcının onu çalıştırma yetkisi olduğunu her zaman sunucuda kontrol edin (ör. yönetici yetkisini getChatMember ile).
getMyCommands ve deleteMyCommands
getMyCommands, verilen scope ve language_code için BotCommand dizisini, hiç komut yoksa boş bir dizi döndürür. deleteMyCommands o kapsam ve dile ait listeyi siler; etkilenen kullanıcılar arama sırasındaki bir sonraki listeyi görür:
curl "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/deleteMyCommands" \
-H "Content-Type: application/json" \
-d '{"scope":{"type":"all_chat_administrators"}}'
Komutları ve /start parametresini işleme
Komutlar, yazıldığı haliyle metni içeren normal message güncellemeleri olarak gelir. Gruplarda bir komut /command@your_bot şeklinde belirli bir bota yönelik olabilir; @username kısmını ayırın ve başka botlara yazılan komutları yok sayın. Deep link şöyle çalışır:
https://t.me/your_bot?start=airplanebotunuzla sohbeti açar, bot/start airplanealır.https://t.me/your_bot?startgroup=spaceshipkullanıcıdan botu eklemek için bir grup seçmesini ister; bot/start@your_bot spaceshipalır.- Parametre en fazla 64 karakter olabilir; yalnızca
A-Z,a-z,0-9,_ve-kullanılabilir. İkili veya başka veriler için Telegram base64url önerir.
Komutları ayrıştıran, /start komutunu parametreli ve parametresiz işleyen ve base64url deep link üreten bir long polling botu:
import base64
import os
import re
import requests
TOKEN = os.environ["BOT_TOKEN"]
API = f"https://api.telegram.org/bot{TOKEN}"
BOT_USERNAME = requests.get(f"{API}/getMe", timeout=10).json()["result"]["username"]
COMMAND_RE = re.compile(r"^/([A-Za-z0-9_]+)(?:@([A-Za-z0-9_]+))?(?:\s+(.*))?$", re.S)
def make_start_link(payload: str) -> str:
# "=" dolgusu olmadan base64url: yalnızca A-Z a-z 0-9 _ - kalır (en fazla 64 karakter)
code = base64.urlsafe_b64encode(payload.encode()).decode().rstrip("=")
return f"https://t.me/{BOT_USERNAME}?start={code}"
def read_start_param(code: str) -> str:
return base64.urlsafe_b64decode(code + "=" * (-len(code) % 4)).decode()
def parse_command(text):
m = COMMAND_RE.match(text)
if not m or (m[2] and m[2].lower() != BOT_USERNAME.lower()):
return None # komut değil veya başka bir bota yazılmış komut
return m[1].lower(), (m[3] or "").strip()
def send(chat_id, text):
requests.post(f"{API}/sendMessage", json={"chat_id": chat_id, "text": text}, timeout=10)
print("Paylaşılacak bağlantı:", make_start_link("ref:42"))
offset = 0
while True:
resp = requests.get(f"{API}/getUpdates", params={"offset": offset, "timeout": 30}, timeout=40).json()
for update in resp["result"]:
offset = update["update_id"] + 1
msg = update.get("message")
parsed = parse_command(msg.get("text", "")) if msg else None
if not parsed:
continue
name, args = parsed
chat_id = msg["chat"]["id"]
if name == "start" and args:
try:
send(chat_id, "Hoş geldiniz! Geldiğiniz kaynak: " + read_start_param(args))
except ValueError:
send(chat_id, "Hoş geldiniz! Bilinmeyen start parametresi.")
elif name == "start":
send(chat_id, "Hoş geldiniz! Neler yapabildiğimi görmek için /help gönderin.")
elif name == "help":
send(chat_id, "/start - botu başlat\n/help - bu mesaj\n/settings - ayarlarınız")
elif name == "settings":
send(chat_id, "Henüz ayar yok.")const TOKEN = process.env.BOT_TOKEN;
const API = `https://api.telegram.org/bot${TOKEN}`;
const BOT_USERNAME = (await (await fetch(`${API}/getMe`)).json()).result.username;
const COMMAND_RE = /^\/([A-Za-z0-9_]+)(?:@([A-Za-z0-9_]+))?(?:\s+([\s\S]*))?$/;
function makeStartLink(payload) {
// Node'un base64url çıktısında "=" dolgusu yok: yalnızca A-Z a-z 0-9 _ - kalır (en fazla 64 karakter)
const code = Buffer.from(payload).toString("base64url");
return `https://t.me/${BOT_USERNAME}?start=${code}`;
}
function readStartParam(code) {
return Buffer.from(code, "base64url").toString("utf8");
}
function parseCommand(text) {
const m = COMMAND_RE.exec(text);
if (!m || (m[2] && m[2].toLowerCase() !== BOT_USERNAME.toLowerCase())) {
return null; // komut değil veya başka bir bota yazılmış komut
}
return { name: m[1].toLowerCase(), args: (m[3] ?? "").trim() };
}
async function send(chatId, text) {
await fetch(`${API}/sendMessage`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ chat_id: chatId, text }),
});
}
console.log("Paylaşılacak bağlantı:", makeStartLink("ref:42"));
let offset = 0;
while (true) {
const resp = await (await fetch(`${API}/getUpdates?offset=${offset}&timeout=30`)).json();
for (const update of resp.result) {
offset = update.update_id + 1;
const msg = update.message;
const parsed = msg ? parseCommand(msg.text ?? "") : null;
if (!parsed) continue;
const { name, args } = parsed;
const chatId = msg.chat.id;
if (name === "start" && args) {
await send(chatId, "Hoş geldiniz! Geldiğiniz kaynak: " + readStartParam(args));
} else if (name === "start") {
await send(chatId, "Hoş geldiniz! Neler yapabildiğimi görmek için /help gönderin.");
} else if (name === "help") {
await send(chatId, "/start - botu başlat\n/help - bu mesaj\n/settings - ayarlarınız");
} else if (name === "settings") {
await send(chatId, "Henüz ayar yok.");
}
}
}JavaScript sürümünü bot.mjs adıyla Node.js 18+ ile çalıştırın (top-level await kullanır). Start parametresini güvenilmeyen girdi olarak ele alın: bağlantıyı herkes üretebilir, bu yüzden tek başına erişim sağlayan bir sırrı asla içine koymayın. Webhook kuruluyken getUpdates çalışmaz; üretim için Telegram bot webhook kurulumu rehberine bakın.
Gruplarda komutlar ve gizlilik modu
Gruplardaki botlar varsayılan olarak gizlilik modunda çalışır. Bu durumda açıkça kendilerine yazılan komutları (/command@your_bot), /start gibi genel komutları yalnızca gruba son mesaj atan bot kendileriyse, kendi mesajlarına verilen yanıtları ve servis mesajlarını alırlar. Bir grupta birden çok bot varsa kullanıcılardan komutlara listeden dokunmalarını isteyin; bu, @your_bot kısmını otomatik ekler. Tüm mesajları almak için botu yönetici yapın veya @BotFather'da /setprivacy ile gizlilik modunu kapatın.
Menü butonu
Özel sohbetlerde giriş alanının yanındaki menü butonu varsayılan olarak komut listesini açar. setChatMenuButton ile onu bir Mini App'e yönlendirebilir veya tekrar komutlara döndürebilirsiniz; chat_id verilmezse tüm sohbetlerin varsayılanı değişir:
curl "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/setChatMenuButton" \
-H "Content-Type: application/json" \
-d '{"menu_button":{"type":"commands"}}'
Diğer türler web_app (text ve web_app ile) ve default'tur. Bot API 10.2'den beri bir BotCommand is_ephemeral: true da alabilir: grupta gönderilen böyle bir komut diğer üyelere ve botlara görünmez, onu yalnızca bot alır.
Bot komutları için iyi uygulamalar
- Listeyi kısa tutun. İnsanların gerçekten ihtiyaç duyduğu komutları kaydedin; nadiren kullanılan yönetici araçları yalnızca yöneticilere özel bir kapsama daha uygundur.
- Eylem odaklı açıklamalar yazın. "Hatırlatıcı oluştur", "Hatırlatıcılar"dan daha çok şey anlatır.
- Komutları deploy sırasında ayarlayın.
setMyCommands'ı deploy betiğinizden çağırmak menüyü onu işleyen kodla senkron tutar. - Bilinmeyen komutlara özel sohbetlerde kibarca yanıt verin, ör.
/helpkomutuna yönlendirin. - Seçimler için butonları kullanın. Çok adımlı akışlarda inline klavyeler, argümanlı komutlardan genellikle daha kullanışlıdır.
Sorun giderme
| Belirti | Olası neden | Çözüm |
|---|---|---|
BOT_COMMAND_INVALID ile 400 | command içinde büyük harf, tire, baştaki / veya 32'den fazla karakter | Eğik çizgi olmadan 1–32 küçük harf, rakam ve alt çizgi kullanın |
| Komutlar ayarlandı ama kullanıcı başka bir liste görüyor | Daha dar bir kapsam veya kullanıcının diline ait liste öncelikli | Her kapsamı ve dili getMyCommands ile kontrol edin |
Bot grupta /start komutunu yok sayıyor | Gizlilik modu açık ve son mesajı başka bir bot attı | /start@your_bot gönderin veya gizlilik modunu değiştirin |
| Start parametresi gelmiyor | A-Z a-z 0-9 _ - dışında karakterler (ör. = dolgusu) veya 64'ten fazla karakter | base64url ile kodlayın, dolguyu silin, veriyi kısaltın |
401 Unauthorized | Yanlış veya iptal edilmiş token | Bot token rehberine bakın |
Sık sorulan sorular
Telegram botuma nasıl komut eklerim?
@BotFather'a /setcommands gönderip botunuzu seçin ya da Bot API'nin setMyCommands metodunu BotCommand nesnelerinden oluşan bir listeyle çağırın. Telegram uygulamaları bundan sonra kullanıcı / yazdığında komutları önerir ve menüde gösterir.
Telegram bot komutu hangi karakterleri içerebilir?
setMyCommands'ta komut metni 1–32 karakterdir ve yalnızca küçük İngilizce harfler, rakamlar ve alt çizgi içerebilir. Açıklama 1–256 karakterdir. Her kapsam ve dil için en fazla 100 komut tanımlanabilir.
/start komutuna nasıl parametre geçirilir?
https://t.me/your_bot?start=airplane gibi bir deep link kullanın. Bot /start airplane mesajını alır. Parametre en fazla 64 karakter olabilir ve yalnızca A-Z, a-z, 0-9, _ ve - içerir; başka veriler için base64url kullanın.
Botum gruptaki komutları neden görmüyor?
Gizlilik modu açıkken (varsayılan) gruptaki bot yalnızca açıkça kendisine yazılan /command@your_bot gibi komutları alır; /start gibi genel komutları ise yalnızca gruba son mesaj atan bot oysa alır. @your_bot biçimini kullanın, botu yönetici yapın veya /setprivacy ile gizlilik modunu kapatın.
Grup yöneticilerine farklı komutları nasıl gösteririm?
Tüm gruplar için scope = {"type": "all_chat_administrators"}, tek bir grup için {"type": "chat_administrators", "chat_id": ...} ile setMyCommands çağırın. Yetkileri yine de sunucuda kontrol edin: güncellemeler komutun hangi kapsamdan geldiğini söylemez.
Bottaki tüm komutları nasıl silerim?
Tanımladığınız her kapsam ve her language_code için deleteMyCommands çağırın. Silme sonrası kullanıcılar arama sırasındaki bir sonraki listeyi, örneğin varsayılan komutları görür.
İ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 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 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.