Telegram Bot API

Telegram bot klavyeleri: inline klavye, callback butonları ve reply klavye

· 9 dk okuma

Telegram inline klavye, bir bot mesajına bağlı buton kümesidir: sendMessage'ın reply_markup parametresinde bir InlineKeyboardMarkup nesnesi gönderirsiniz; callback butonuna basıldığında botunuz bir callback_query güncellemesi alır ve buna answerCallbackQuery ile yanıt vermesi gerekir. Reply klavye (ReplyKeyboardMarkup) ise kullanıcının harf klavyesini hazır yanıtlarla değiştirir. Bu rehber iki tür Telegram bot butonunu, tüm buton tiplerini, basıştan sonra mesajı düzenlemeyi ve Python ile JavaScript'te eksiksiz, çalışan bir örneği anlatıyor.

Inline klavye mi, reply klavye mi?

Inline klavyeReply klavye
NesneInlineKeyboardMarkupReplyKeyboardMarkup
Nerede görünürBelirli bir mesajın altındaKullanıcının klavyesinin yerinde
Basınca ne olurCallback query, URL açma, Mini App, inline mod, metin kopyalama…Buton metnini mesaj olarak gönderir veya kişi, konum, kullanıcı, sohbet paylaşır
Sonradan düzenlenebilir miEvet, editMessageReplyMarkup ileHayır, yeni klavye gönderin veya kaldırın
KanallarDestekleniyorDesteklenmiyor

İkisi de ReplyKeyboardRemove ve ForceReply ile birlikte aynı reply_markup parametresine gider. Bir mesaj bu dört nesneden yalnızca birini taşır.

Telegram inline klavye gönderme

inline_keyboard satırlardan oluşan bir dizidir; her satır da bir buton dizisidir:

curl -X POST "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/sendMessage" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": 123456789,
    "text": "Bir seçenek seçin:",
    "reply_markup": {
      "inline_keyboard": [
        [{"text": "Beğen", "callback_data": "like"}, {"text": "Yardım", "callback_data": "help"}],
        [{"text": "Bot API dokümanları", "url": "https://core.telegram.org/bots/api"}]
      ]
    }
  }'

Her butonda text'in yanında, tipini belirleyen tam olarak bir alan olmalıdır:

AlanButon ne yapar
callback_dataBota bu metinle bir callback query gönderir, 1–64 bayt
urlHTTP veya tg:// linki açar
web_appMini App başlatır; yalnızca kullanıcı ile bot arasındaki özel sohbetlerde
login_urlHTTPS URL açar ve kullanıcıyı sitenizde yetkilendirir
switch_inline_query, switch_inline_query_current_chat, switch_inline_query_chosen_chatBotun kullanıcı adını ve bir sorguyu başka bir sohbetin, mevcut sohbetin veya seçilen türdeki bir sohbetin giriş alanına yazar
copy_text{"text": "…"} (1–256 karakter) değerini panoya kopyalar
payÖdeme butonu; yalnızca fatura mesajlarında, ilk satırdaki ilk buton olmalı
callback_gameOyun başlatır; ilk satırdaki ilk buton olmalı
disabledHiçbir şey yapmayan bir DisabledButton (Bot API 10.3)

İki isteğe bağlı alan butonun görünümünü değiştirir (Bot API 9.4, reply klavye butonlarında da var): "danger" (kırmızı), "success" (yeşil) veya "primary" (mavi) değerli style ve metnin önüne özel emoji koyan icon_custom_emoji_id. Özel emojiler yalnızca bot bunları kullanabiliyorsa çalışır: Fragment'ta ek kullanıcı adı satın almış olmalı ya da sahibi Telegram Premium kullanıcısı olmalı ve mesaj doğrudan özel sohbete, gruba veya süper gruba gönderilmeli.

callback_data tasarımı

64 baytlık limit karakteri değil baytı sayar; bu yüzden değerleri kısa ve makine tarafından okunabilir tutun, ör. like, page:3 veya del:8812, asıl veriyi veritabanınızda saklayın. API ayrıca aldığınız data'ya sahip bir butonun mesajda hiç olmayabileceği konusunda uyarır; bu yüzden onu güvenilmeyen kullanıcı girdisi gibi ele alın: ayrıştırın, doğrulayın ve kullanıcının bu işlemi yapmaya yetkili olduğunu kontrol edin. Fazla uzun bir değer klavye gönderilirken reddedilir, genellikle Bad Request: BUTTON_DATA_INVALID ile.

Her basışa answerCallbackQuery ile yanıt verin

Callback butonuna basmak callback_query alanı olan bir güncelleme üretir: id, from (kullanıcı), data ve bot tarafından gönderilen mesajlar için orijinal mesajı taşıyan message. Basıştan sonra Telegram istemcileri bot answerCallbackQuery çağırana kadar bir ilerleme göstergesi gösterir; bu yüzden id dışında parametre olmasa bile her seferinde çağırın.

ParametreAnlamı
callback_query_idZorunlu, callback query'nin id'si
textBildirim metni, 0–200 karakter; verilmezse hiçbir şey gösterilmez
show_alerttrue ise sohbetin üstündeki bildirim yerine bir uyarı penceresi gösterir
urlOyun URL'si (callback_game butonları için) veya t.me/your_bot?start=XXXX gibi bir link
cache_timeSonucun istemcide önbelleğe alınabileceği saniye, varsayılan 0

Hızlı yanıt verin: eski bir sorgu Bad Request: query is too old and response timeout expired or query ID is invalid ile başarısız olur. Ayrıntılar için answerCallbackQuery referansına bakın.

Basıştan sonra mesajı düzenleme

Mevcut mesajı güncellemek yeni mesaj göndermekten daha hızlı ve temizdir; Telegram bunu ayarlar ve sayfalama için önerir. callback_query.message'dan chat.id ve message_id'yi alın ve şunu çağırın:

Yeni metin ve klavye mevcutlarla aynıysa API Bad Request: message is not modified döndürür; bu yüzden düzenlemeden önce karşılaştırın veya bu hatayı özel olarak yok sayın.

Tam örnek: callback butonlu inline menü

Bu bot /start'a bir menüyle yanıt verir, mesaj başına beğenileri sayar, Yardım için bir uyarı gösterir ve her değişiklikte mesajı düzenler. getUpdates long polling kullandığı için webhook olmadan localhost'ta çalışır. Önce ortam değişkeninde BOT_TOKEN'ı ayarlayın.

import os
import requests

TOKEN = os.environ["BOT_TOKEN"]
API = f"https://api.telegram.org/bot{TOKEN}"
likes = {}  # (chat_id, message_id) -> sayı


def call(method, **params):
    data = requests.post(f"{API}/{method}", json=params, timeout=40).json()
    if not data["ok"]:
        raise RuntimeError(f"{method}: {data['error_code']} {data['description']}")
    return data["result"]


def menu(count):
    return {"inline_keyboard": [
        [{"text": f"Beğen ({count})", "callback_data": "like", "style": "success"},
         {"text": "Sıfırla", "callback_data": "reset", "style": "danger"}],
        [{"text": "Yardım", "callback_data": "help"},
         {"text": "Bot API dokümanları", "url": "https://core.telegram.org/bots/api"}],
    ]}


def on_callback(cq):
    msg, data = cq.get("message"), cq.get("data")
    if not msg or data not in ("like", "reset", "help"):
        call("answerCallbackQuery", callback_query_id=cq["id"], text="Bilinmeyen buton")
        return
    if data == "help":
        call("answerCallbackQuery", callback_query_id=cq["id"], show_alert=True,
             text="Beğen bir ekler, Sıfırla baştan başlatır.")
        return
    key = (msg["chat"]["id"], msg["message_id"])
    old = likes.get(key, 0)
    new = old + 1 if data == "like" else 0
    call("answerCallbackQuery", callback_query_id=cq["id"],
         text="Teşekkürler!" if data == "like" else "Sayaç sıfırlandı")
    if new != old:  # "message is not modified" hatasından kaçının
        likes[key] = new
        call("editMessageText", chat_id=key[0], message_id=key[1],
             text=f"Beğeni: {new}", reply_markup=menu(new))


offset = 0
while True:
    updates = call("getUpdates", offset=offset, timeout=30,
                   allowed_updates=["message", "callback_query"])
    for update in updates:
        offset = update["update_id"] + 1
        if "callback_query" in update:
            on_callback(update["callback_query"])
        elif update.get("message", {}).get("text") == "/start":
            chat_id = update["message"]["chat"]["id"]
            call("sendMessage", chat_id=chat_id, text="Beğeni: 0", reply_markup=menu(0))
const TOKEN = process.env.BOT_TOKEN;
const API = `https://api.telegram.org/bot${TOKEN}`;
const likes = new Map(); // "chatId:messageId" -> sayı

async function call(method, params = {}) {
  const res = await fetch(`${API}/${method}`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(params),
    signal: AbortSignal.timeout(40_000),
  });
  const data = await res.json();
  if (!data.ok) throw new Error(`${method}: ${data.error_code} ${data.description}`);
  return data.result;
}

function menu(count) {
  return { inline_keyboard: [
    [{ text: `Beğen (${count})`, callback_data: "like", style: "success" },
     { text: "Sıfırla", callback_data: "reset", style: "danger" }],
    [{ text: "Yardım", callback_data: "help" },
     { text: "Bot API dokümanları", url: "https://core.telegram.org/bots/api" }],
  ] };
}

async function onCallback(cq) {
  const msg = cq.message;
  const data = cq.data;
  if (!msg || !["like", "reset", "help"].includes(data)) {
    await call("answerCallbackQuery", { callback_query_id: cq.id, text: "Bilinmeyen buton" });
    return;
  }
  if (data === "help") {
    await call("answerCallbackQuery", { callback_query_id: cq.id, show_alert: true,
      text: "Beğen bir ekler, Sıfırla baştan başlatır." });
    return;
  }
  const key = `${msg.chat.id}:${msg.message_id}`;
  const old = likes.get(key) ?? 0;
  const next = data === "like" ? old + 1 : 0;
  await call("answerCallbackQuery", { callback_query_id: cq.id,
    text: data === "like" ? "Teşekkürler!" : "Sayaç sıfırlandı" });
  if (next !== old) { // "message is not modified" hatasından kaçının
    likes.set(key, next);
    await call("editMessageText", { chat_id: msg.chat.id, message_id: msg.message_id,
      text: `Beğeni: ${next}`, reply_markup: menu(next) });
  }
}

let offset = 0;
while (true) {
  const updates = await call("getUpdates", { offset, timeout: 30,
    allowed_updates: ["message", "callback_query"] });
  for (const update of updates) {
    offset = update.update_id + 1;
    if (update.callback_query) {
      await onCallback(update.callback_query);
    } else if (update.message?.text === "/start") {
      await call("sendMessage", { chat_id: update.message.chat.id, text: "Beğeni: 0",
        reply_markup: menu(0) });
    }
  }
}

JavaScript sürümünü bot.mjs olarak kaydedin (top-level await kullanır) ve Node.js 18+ ile çalıştırın. Sayaç bellekte tutulur; gerçek bir bot bunu veritabanında saklar. Varsayılan buton renklerini istiyorsanız style alanlarını kaldırın.

Telegram'da reply klavye

Reply klavye hazır yanıtlar sunar. Yalnızca bir metin olarak da yazılabilen düz metin butonu, metnini kullanıcı yazmış gibi sohbete gönderir; botunuz bunu diğer mesajlar gibi işler:

{
  "keyboard": [
    ["Katalog", "Sepet"],
    [{"text": "Telefonumu paylaş", "request_contact": true},
     {"text": "Konum gönder", "request_location": true}]
  ],
  "resize_keyboard": true,
  "one_time_keyboard": true,
  "input_field_placeholder": "Bir bölüm seçin"
}
AlanEtkisi
resize_keyboardYüksekliği satır sayısına göre ayarlar; varsayılan olarak klavye standart klavye kadar yüksektir
one_time_keyboardBasıştan sonra klavyeyi gizler; kullanıcı klavye simgesiyle tekrar açabilir
is_persistentNormal klavye gizliyken klavyeyi her zaman gösterir
input_field_placeholderGiriş alanındaki yer tutucu metin, 1–64 karakter
selectiveKlavyeyi yalnızca @ ile anılan kullanıcılara veya yanıtlanan mesajın göndericisine gösterir

Özel butonlar yalnızca özel sohbetlerde çalışır: request_contact kullanıcının telefon numarasını kişi olarak, request_location anlık konumunu gönderir, request_poll kullanıcıdan anket oluşturmasını ister, web_app bir Mini App başlatır. request_users (KeyboardButtonRequestUsers) ve request_chat (KeyboardButtonRequestChat) bir seçici açar ve sonucu users_shared ve chat_shared servis mesajlarında döndürür; ikisi de mesaj içinde benzersiz, işaretli 32 bitlik bir sayı olan request_id ister:

{"keyboard": [[
  {"text": "Kullanıcı seç", "request_users": {"request_id": 1, "user_is_bot": false, "max_quantity": 3}},
  {"text": "Grubumu seç", "request_chat": {"request_id": 2, "chat_is_channel": false, "chat_is_created": true}}
]], "resize_keyboard": true}

ReplyKeyboardRemove ve ForceReply

Reply klavye, bot başka bir klavye gönderene kadar görünür kalır. Kaldırmak için {"remove_keyboard": true} içeren bir mesaj gönderin. ForceReply, yani {"force_reply": true, "input_field_placeholder": "Şehriniz"}, kullanıcı Yanıtla'ya dokunmuş gibi botun mesajına yanıt arayüzünü açar. Gruplarda adım adım veri almak için kullanışlıdır, çünkü privacy mode açıkken bile yanıt bota ulaşır. Reply klavyeler gibi bu iki nesne de kanallarda çalışmaz.

Bot API Tester'da deneyin

  1. Bot API Tester'da sendMessage'ı açın, token'ınızı ve chat id'nizi girin.
  2. Yukarıdaki JSON klavyelerden birini reply_markup'a yapıştırın ve çalıştırın.
  3. Telegram'da bir callback butonuna basın, ardından tester'da getUpdates çalıştırarak callback_query güncellemesini görün ve answerCallbackQuery ile yanıtlayın.

Telegram bot butonlarında sorun giderme

BelirtiNeden ve çözüm
Basıştan sonra yükleniyor göstergesianswerCallbackQuery çağrılmamış. Her callback query'ye yanıt verin.
callback_query güncellemesi gelmiyorallowed_updates içinde callback_query yok ya da güncellemeleri başka bir süreç tüketiyor (webhook veya ikinci bir polling örneği).
BUTTON_DATA_INVALIDcallback_data boş veya 64 bayttan uzun.
message is not modifiedDüzenleme metni veya klavyeyi değiştirmiyor.
query is too old…Yanıt çok geç geldi, ör. yeniden başlatmadan sonra eski güncellemeler işlendi.
Kişi veya konum butonu grupta hiçbir şey yapmıyorBu butonlar yalnızca özel sohbetlerde kullanılabilir.

Hata mesajlarının tam listesi için Telegram Bot API hataları rehberine bakın. Biçimlendirme ve diğer sendMessage seçenekleri Bot API ile mesaj gönderme rehberinde anlatılıyor; inline moda geçiş butonları ise inline mod ile birlikte kullanılır.

Sık sorulan sorular

Telegram'da inline klavye ile reply klavye arasındaki fark nedir?

Inline klavye (InlineKeyboardMarkup) belirli bir mesaja bağlıdır; butonlarına basmak sohbete hiçbir şey göndermez. Reply klavye (ReplyKeyboardMarkup) kullanıcının harf klavyesinin yerini alır; basit bir metin butonu, metnini normal bir mesaj olarak gönderir.

callback_data en fazla ne kadar uzun olabilir?

1–64 bayt. Karakter değil bayt: Latin dışı harfler ve ğ, ş, ı gibi Türkçe karakterler UTF-8'de 2 veya daha fazla bayt tutar. item:42 gibi kısa anahtarlar saklayın, asıl veriyi sunucunuzda tutun.

Butona bastıktan sonra neden yükleniyor göstergesi kaybolmuyor?

Bot answerCallbackQuery çağırmadı. Telegram istemcileri siz yanıt verene kadar bir ilerleme göstergesi gösterir; bu yüzden text olmasa bile her callback query için çağırın.

Kullanıcı bir butona bastıktan sonra butonları nasıl değiştiririm?

Yalnızca klavyeyi değiştirmek için callback_query.message'daki chat_id ve message_id ile editMessageReplyMarkup çağırın; metni ve klavyeyi birlikte değiştirmek için editMessageText kullanın.

Reply klavye nasıl kaldırılır?

reply_markup değeri {"remove_keyboard": true} (ReplyKeyboardRemove) olan bir mesaj gönderin. Klavyeyi erişilebilir bırakıp yalnızca bir basıştan sonra gizlemek istiyorsanız bunun yerine one_time_keyboard kullanın.

Kanaldaki mesajlara buton eklenebilir mi?

Inline klavye, evet. Reply klavye, ReplyKeyboardRemove ve ForceReply kanallarda desteklenmez.

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.

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.