Telegram Bot API

Telegram bot komutları: setMyCommands, komut kapsamları ve /start deep link

· 8 dk okuma

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:

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:

  1. @BotFather'ı açın ve /setcommands gönderin.
  2. Botunuzu seçin.
  3. Listeyi her satıra bir komut gelecek şekilde komut - açıklama biç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 typeListeyi kim görürEk alanlar
defaultDaha dar bir liste yoksa herkes—
all_private_chatsBotla yapılan tüm özel sohbetler—
all_group_chatsTüm gruplar ve süper gruplar—
all_chat_administratorsTüm grup ve süper grupların yöneticileri—
chatBelirli bir sohbetchat_id
chat_administratorsTek bir grup veya süper grubun yöneticilerichat_id
chat_memberTek bir grup veya süper gruptaki tek bir üyechat_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:

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.

Ö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

Sorun giderme

BelirtiOlası nedenÇözüm
BOT_COMMAND_INVALID ile 400command içinde büyük harf, tire, baştaki / veya 32'den fazla karakterEğ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üyorDaha dar bir kapsam veya kullanıcının diline ait liste öncelikliHer kapsamı ve dili getMyCommands ile kontrol edin
Bot grupta /start komutunu yok sayıyorGizlilik modu açık ve son mesajı başka bir bot attı/start@your_bot gönderin veya gizlilik modunu değiştirin
Start parametresi gelmiyorA-Z a-z 0-9 _ - dışında karakterler (ör. = dolgusu) veya 64'ten fazla karakterbase64url ile kodlayın, dolguyu silin, veriyi kısaltın
401 UnauthorizedYanlış veya iptal edilmiş tokenBot 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.

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.