Telegram bot klavyeleri: inline klavye, callback butonları ve reply klavye
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 klavye | Reply klavye | |
|---|---|---|
| Nesne | InlineKeyboardMarkup | ReplyKeyboardMarkup |
| Nerede görünür | Belirli bir mesajın altında | Kullanıcının klavyesinin yerinde |
| Basınca ne olur | Callback 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 mi | Evet, editMessageReplyMarkup ile | Hayır, yeni klavye gönderin veya kaldırın |
| Kanallar | Destekleniyor | Desteklenmiyor |
İ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:
| Alan | Buton ne yapar |
|---|---|
callback_data | Bota bu metinle bir callback query gönderir, 1–64 bayt |
url | HTTP veya tg:// linki açar |
web_app | Mini App başlatır; yalnızca kullanıcı ile bot arasındaki özel sohbetlerde |
login_url | HTTPS URL açar ve kullanıcıyı sitenizde yetkilendirir |
switch_inline_query, switch_inline_query_current_chat, switch_inline_query_chosen_chat | Botun 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_game | Oyun başlatır; ilk satırdaki ilk buton olmalı |
disabled | Hiç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.
| Parametre | Anlamı |
|---|---|
callback_query_id | Zorunlu, callback query'nin id'si |
text | Bildirim metni, 0–200 karakter; verilmezse hiçbir şey gösterilmez |
show_alert | true ise sohbetin üstündeki bildirim yerine bir uyarı penceresi gösterir |
url | Oyun URL'si (callback_game butonları için) veya t.me/your_bot?start=XXXX gibi bir link |
cache_time | Sonucun 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:
- metni değiştirmek için
editMessageText, isteğe bağlı olarak yeni birreply_markupile; - yalnızca klavyeyi değiştirmek için
editMessageReplyMarkup; kaldırmak içinreply_markup'ı göndermeyin.
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"
}
| Alan | Etkisi |
|---|---|
resize_keyboard | Yüksekliği satır sayısına göre ayarlar; varsayılan olarak klavye standart klavye kadar yüksektir |
one_time_keyboard | Basıştan sonra klavyeyi gizler; kullanıcı klavye simgesiyle tekrar açabilir |
is_persistent | Normal klavye gizliyken klavyeyi her zaman gösterir |
input_field_placeholder | Giriş alanındaki yer tutucu metin, 1–64 karakter |
selective | Klavyeyi 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
- Bot API Tester'da sendMessage'ı açın, token'ınızı ve chat id'nizi girin.
- Yukarıdaki JSON klavyelerden birini
reply_markup'a yapıştırın ve çalıştırın. - Telegram'da bir callback butonuna basın, ardından tester'da
getUpdatesçalıştırarakcallback_querygüncellemesini görün ve answerCallbackQuery ile yanıtlayın.
Telegram bot butonlarında sorun giderme
| Belirti | Neden ve çözüm |
|---|---|
| Basıştan sonra yükleniyor göstergesi | answerCallbackQuery çağrılmamış. Her callback query'ye yanıt verin. |
callback_query güncellemesi gelmiyor | allowed_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_INVALID | callback_data boş veya 64 bayttan uzun. |
message is not modified | Dü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ıyor | Bu 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.
İ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 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.