کیبورد ربات تلگرام: دکمه شیشهای (inline keyboard)، دکمههای callback و reply keyboard
دکمه شیشهای ربات تلگرام (inline keyboard) مجموعهای از دکمههاست که به پیام ربات میچسبد: یک آبجکت InlineKeyboardMarkup را در پارامتر reply_markup متد sendMessage میفرستید و زدن دکمه callback یک آپدیت callback_query به ربات میفرستد که باید با answerCallbackQuery به آن جواب بدهید. در مقابل، reply keyboard (ReplyKeyboardMarkup) جای کیبورد حروف کاربر را با پاسخهای آماده میگیرد. این راهنما هر دو نوع کیبورد ربات تلگرام، همه انواع دکمه، ویرایش پیام بعد از کلیک و یک مثال کامل و قابل اجرا با Python و JavaScript را پوشش میدهد.
دکمه شیشهای یا reply keyboard؟
| دکمه شیشهای (inline keyboard) | Reply keyboard | |
|---|---|---|
| آبجکت | InlineKeyboardMarkup | ReplyKeyboardMarkup |
| محل نمایش | زیر یک پیام مشخص | به جای کیبورد کاربر |
| کار دکمه | callback query، باز کردن URL، Mini App، حالت inline، کپی متن… | ارسال متن دکمه به صورت پیام، یا اشتراک مخاطب، موقعیت، کاربران، چت |
| ویرایش بعدی | بله، با editMessageReplyMarkup | نه؛ کیبورد جدید بفرستید یا حذفش کنید |
| کانالها | پشتیبانی میشود | پشتیبانی نمیشود |
هر دو در همان پارامتر reply_markup قرار میگیرند، همراه با ReplyKeyboardRemove و ForceReply. هر پیام فقط یکی از این چهار آبجکت را دارد.
ارسال دکمه شیشهای در تلگرام
inline_keyboard آرایهای از ردیفهاست و هر ردیف آرایهای از دکمهها:
curl -X POST "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/sendMessage" \
-H "Content-Type: application/json" \
-d '{
"chat_id": 123456789,
"text": "یک گزینه را انتخاب کنید:",
"reply_markup": {
"inline_keyboard": [
[{"text": "لایک", "callback_data": "like"}, {"text": "راهنما", "callback_data": "help"}],
[{"text": "مستندات Bot API", "url": "https://core.telegram.org/bots/api"}]
]
}
}'
هر دکمه علاوه بر text باید دقیقاً یک فیلد داشته باشد که نوعش را مشخص کند:
| فیلد | کار دکمه |
|---|---|
callback_data | یک callback query با این رشته به ربات میفرستد، 1 تا 64 بایت |
url | لینک HTTP یا tg:// را باز میکند |
web_app | یک Mini App را اجرا میکند؛ فقط در چت خصوصی کاربر با ربات |
login_url | یک آدرس HTTPS را باز میکند و کاربر را در سایت شما احراز هویت میکند |
switch_inline_query، switch_inline_query_current_chat، switch_inline_query_chosen_chat | username ربات و یک کوئری را در فیلد ورودی چت دیگر، چت فعلی یا چتی از نوع انتخابی قرار میدهد |
copy_text | {"text": "…"} (1 تا 256 کاراکتر) را در کلیپبورد کپی میکند |
pay | دکمه پرداخت؛ فقط در پیامهای invoice و باید اولین دکمه ردیف اول باشد |
callback_game | یک بازی را اجرا میکند؛ باید اولین دکمه ردیف اول باشد |
disabled | یک DisabledButton که هیچ کاری نمیکند (Bot API 10.3) |
دو فیلد اختیاری ظاهر دکمه را تغییر میدهند (Bot API 9.4، روی دکمههای reply keyboard هم در دسترس): style با مقدار "danger" (قرمز)، "success" (سبز) یا "primary" (آبی)، و icon_custom_emoji_id برای یک custom emoji قبل از متن. custom emoji فقط وقتی کار میکند که ربات اجازه استفاده از آن را داشته باشد: username اضافه در Fragment خریده باشد، یا صاحبش Telegram Premium داشته باشد و پیام مستقیماً به چت خصوصی، گروه یا سوپرگروه فرستاده شود.
طراحی callback_data
محدودیت 64 بایتی بایتها را میشمارد، نه کاراکترها را؛ پس مقادیر را کوتاه و ماشینخوان نگه دارید، مثلاً like، page:3 یا del:8812، و داده اصلی را در دیتابیس نگه دارید. مستندات API هشدار میدهد ممکن است پیام اصلاً دکمهای با data دریافتی نداشته باشد؛ پس آن را ورودی غیرقابلاعتماد کاربر بدانید: پارس کنید، اعتبارسنجی کنید و بررسی کنید که کاربر اجازه انجام آن کار را دارد. مقدار خیلی طولانی هنگام ارسال کیبورد رد میشود، معمولاً با Bad Request: BUTTON_DATA_INVALID.
پاسخ به هر کلیک با answerCallbackQuery
زدن دکمه callback یک آپدیت با فیلد callback_query میسازد: id، from (کاربر)، data و برای پیامهایی که ربات فرستاده، message با پیام اصلی. بعد از کلیک، کلاینتهای تلگرام تا وقتی ربات answerCallbackQuery را صدا نزند علامت پیشرفت نشان میدهند؛ پس آن را هر بار صدا بزنید، حتی فقط با id.
| پارامتر | معنی |
|---|---|
callback_query_id | اجباری، id همان callback query |
text | متن اعلان، 0 تا 200 کاراکتر؛ اگر نفرستید چیزی نمایش داده نمیشود |
show_alert | با true به جای اعلان بالای چت، یک پنجره هشدار (alert) نشان داده میشود |
url | آدرس بازی (برای دکمههای callback_game) یا لینکی مثل t.me/your_bot?start=XXXX |
cache_time | چند ثانیه نتیجه در کلاینت کش شود، پیشفرض 0 |
سریع جواب بدهید: کوئری قدیمی با Bad Request: query is too old and response timeout expired or query ID is invalid رد میشود. جزئیات را در مرجع متد answerCallbackQuery ببینید.
ویرایش پیام بعد از کلیک
بهروز کردن همان پیام سریعتر و تمیزتر از ارسال پیام جدید است و تلگرام آن را برای تنظیمات و صفحهبندی توصیه میکند. chat.id و message_id را از callback_query.message بردارید و صدا بزنید:
editMessageTextبرای تغییر متن، در صورت نیاز همراه باreply_markupجدید؛editMessageReplyMarkupبرای تعویض فقط کیبورد؛ اگرreply_markupرا نفرستید، کیبورد حذف میشود.
اگر متن و کیبورد جدید با فعلی یکسان باشند، API خطای Bad Request: message is not modified برمیگرداند؛ پس قبل از ویرایش مقایسه کنید یا همین خطای مشخص را نادیده بگیرید.
مثال کامل: منوی شیشهای با دکمههای callback
این ربات به /start با یک منو جواب میدهد، لایکها را برای هر پیام میشمارد، برای «راهنما» یک alert نشان میدهد و با هر تغییر پیام را ویرایش میکند. از long polling با getUpdates استفاده میکند، پس روی localhost و بدون وب هوک اجرا میشود. اول متغیر محیطی BOT_TOKEN را تنظیم کنید.
import os
import requests
TOKEN = os.environ["BOT_TOKEN"]
API = f"https://api.telegram.org/bot{TOKEN}"
likes = {} # (chat_id, message_id) -> تعداد
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"لایک ({count})", "callback_data": "like", "style": "success"},
{"text": "صفر کردن", "callback_data": "reset", "style": "danger"}],
[{"text": "راهنما", "callback_data": "help"},
{"text": "مستندات Bot API", "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="دکمه ناشناخته")
return
if data == "help":
call("answerCallbackQuery", callback_query_id=cq["id"], show_alert=True,
text="لایک یکی اضافه میکند، صفر کردن از اول شروع میکند.")
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="ممنون!" if data == "like" else "شمارنده صفر شد")
if new != old: # جلوگیری از خطای "message is not modified"
likes[key] = new
call("editMessageText", chat_id=key[0], message_id=key[1],
text=f"لایکها: {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="لایکها: 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" -> تعداد
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: `لایک (${count})`, callback_data: "like", style: "success" },
{ text: "صفر کردن", callback_data: "reset", style: "danger" }],
[{ text: "راهنما", callback_data: "help" },
{ text: "مستندات Bot API", 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: "دکمه ناشناخته" });
return;
}
if (data === "help") {
await call("answerCallbackQuery", { callback_query_id: cq.id, show_alert: true,
text: "لایک یکی اضافه میکند، صفر کردن از اول شروع میکند." });
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" ? "ممنون!" : "شمارنده صفر شد" });
if (next !== old) { // جلوگیری از خطای "message is not modified"
likes.set(key, next);
await call("editMessageText", { chat_id: msg.chat.id, message_id: msg.message_id,
text: `لایکها: ${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: "لایکها: 0",
reply_markup: menu(0) });
}
}
}نسخه JavaScript را با نام bot.mjs ذخیره کنید (از await در سطح بالا استفاده میکند) و با Node.js 18+ اجرا کنید. شمارنده در حافظه است؛ ربات واقعی آن را در دیتابیس ذخیره میکند. اگر رنگ پیشفرض دکمهها را میخواهید، فیلدهای style را حذف کنید.
Reply keyboard در تلگرام
Reply keyboard پاسخهای آماده پیشنهاد میدهد. یک دکمه متنی ساده، که میشود آن را فقط به صورت یک رشته هم نوشت، متن خودش را طوری به چت میفرستد که انگار کاربر تایپش کرده؛ پس ربات مثل هر پیام دیگری آن را پردازش میکند:
{
"keyboard": [
["فروشگاه", "سبد خرید"],
[{"text": "ارسال شماره من", "request_contact": true},
{"text": "ارسال موقعیت", "request_location": true}]
],
"resize_keyboard": true,
"one_time_keyboard": true,
"input_field_placeholder": "یک بخش را انتخاب کنید"
}
| فیلد | اثر |
|---|---|
resize_keyboard | ارتفاع را با تعداد ردیفها تنظیم میکند؛ به طور پیشفرض کیبورد همقد کیبورد استاندارد است |
one_time_keyboard | کیبورد را بعد از یک کلیک پنهان میکند؛ کاربر میتواند با آیکون کیبورد دوباره بازش کند |
is_persistent | وقتی کیبورد معمولی پنهان است، همیشه این کیبورد را نشان میدهد |
input_field_placeholder | متن placeholder در فیلد ورودی، 1 تا 64 کاراکتر |
selective | کیبورد را فقط به کاربران @منشنشده یا فرستنده پیامی که به آن ریپلای شده نشان میدهد |
دکمههای ویژه فقط در چت خصوصی کار میکنند: request_contact شماره تلفن کاربر را به صورت مخاطب میفرستد، request_location موقعیت فعلی او را، request_poll از او میخواهد نظرسنجی بسازد و web_app یک Mini App را اجرا میکند. request_users (KeyboardButtonRequestUsers) و request_chat (KeyboardButtonRequestChat) یک انتخابگر باز میکنند و نتیجه را در پیامهای سرویسی users_shared و chat_shared برمیگردانند؛ هر دو به یک request_id نیاز دارند، یک عدد علامتدار 32 بیتی که در آن پیام یکتا باشد:
{"keyboard": [[
{"text": "انتخاب کاربر", "request_users": {"request_id": 1, "user_is_bot": false, "max_quantity": 3}},
{"text": "انتخاب گروه من", "request_chat": {"request_id": 2, "chat_is_channel": false, "chat_is_created": true}}
]], "resize_keyboard": true}
ReplyKeyboardRemove و ForceReply
Reply keyboard تا وقتی ربات کیبورد دیگری نفرستد نمایش داده میشود. برای حذفش پیامی با {"remove_keyboard": true} بفرستید. ForceReply، یعنی {"force_reply": true, "input_field_placeholder": "شهر شما"}، رابط ریپلای به پیام ربات را باز میکند؛ انگار کاربر Reply را زده باشد. برای گرفتن ورودی مرحلهبهمرحله در گروهها مفید است، چون پاسخ حتی با privacy mode روشن هم به ربات میرسد. مثل reply keyboard، هیچکدام از این دو آبجکت در کانال کار نمیکنند.
امتحان در Bot API Tester
- متد sendMessage را در Bot API Tester باز کنید و توکن و chat id خود را وارد کنید.
- یکی از کیبوردهای JSON بالا را در
reply_markupبچسبانید و اجرا کنید. - در تلگرام یک دکمه callback را بزنید، بعد در تستر
getUpdatesرا اجرا کنید تا آپدیتcallback_queryرا ببینید و با answerCallbackQuery جوابش را بدهید.
رفع مشکلات دکمههای ربات تلگرام
| نشانه | علت و راه حل |
|---|---|
| علامت بارگذاری بعد از کلیک | answerCallbackQuery صدا زده نشده. به هر callback query جواب بدهید. |
آپدیت callback_query نمیرسد | allowed_updates شامل callback_query نیست، یا پروسه دیگری آپدیتها را مصرف میکند (وب هوک یا نمونه دوم polling). |
BUTTON_DATA_INVALID | callback_data خالی است یا بیشتر از 64 بایت. |
message is not modified | ویرایش، متن یا کیبورد را تغییر نمیدهد. |
query is too old… | جواب خیلی دیر رسیده؛ مثلاً بعد از ریاستارت، آپدیتهای قدیمی پردازش شدهاند. |
| دکمه مخاطب یا موقعیت در گروه کار نمیکند | این دکمهها فقط در چت خصوصی در دسترساند. |
لیست کامل پیامهای خطا را در خطاهای Telegram Bot API ببینید. قالببندی و بقیه گزینههای sendMessage در آموزش ارسال پیام با ربات تلگرام آمده است و دکمههای switch-to-inline با حالت inline کامل میشوند.
پرسشهای متداول
فرق دکمه شیشهای (inline keyboard) با reply keyboard در تلگرام چیست؟
دکمه شیشهای (InlineKeyboardMarkup) به یک پیام مشخص چسبیده است و زدن آن چیزی در چت نمیفرستد. Reply keyboard (ReplyKeyboardMarkup) جای کیبورد حروف کاربر را میگیرد و یک دکمه متنی ساده، متن خودش را به صورت پیام معمولی میفرستد.
callback_data حداکثر چقدر میتواند باشد؟
1 تا 64 بایت. بایت، نه کاراکتر: حروف غیر لاتین (از جمله فارسی) در UTF-8 دو بایت یا بیشتر جا میگیرند. کلیدهای کوتاهی مثل item:42 ذخیره کنید و داده اصلی را روی سرور نگه دارید.
چرا بعد از زدن دکمه، علامت بارگذاری روی آن میماند؟
ربات answerCallbackQuery را صدا نزده است. کلاینتهای تلگرام تا وقتی جواب ندهید نوار پیشرفت نشان میدهند؛ پس برای هر callback query این متد را صدا بزنید، حتی بدون text.
چطور دکمهها را بعد از کلیک کاربر تغییر دهم؟
editMessageReplyMarkup را با chat_id و message_id از callback_query.message صدا بزنید تا فقط کیبورد عوض شود، یا editMessageText را تا متن و کیبورد با هم تغییر کنند.
چطور reply keyboard را حذف کنم؟
پیامی بفرستید که reply_markup آن {"remove_keyboard": true} (ReplyKeyboardRemove) باشد. اگر فقط میخواهید بعد از یک بار زدن پنهان شود ولی در دسترس بماند، از one_time_keyboard استفاده کنید.
آیا میشود به پیامهای کانال دکمه اضافه کرد؟
دکمه شیشهای بله. Reply keyboard، ReplyKeyboardRemove و ForceReply در کانال پشتیبانی نمیشوند.
آموزشهای مرتبط
ساخت ربات تلگرام: آموزش قدمبهقدم از BotFather تا اولین پیام با Python
ساخت ربات تلگرام قدمبهقدم: ساخت ربات در BotFather، گرفتن توکن، تست با getMe، پیدا کردن chat id و ارسال اولین پیام با curl و Python.
دیپلوی ربات تلگرام: راهاندازی روی VPS، داکر و هاست Serverless
آموزش دیپلوی و هاست ربات تلگرام: polling یا وب هوک، سرویس systemd روی VPS، داکر، Cloudflare Workers با secret_token و چکلیست راهاندازی.
Telegram Bot API 10.0 تا 10.5: تنظیمات ربات، ویجتها، پیامهای rich و ephemeral، حالت مهمان و بیشتر
تغییرات Telegram Bot API 10.0 تا 10.5: متد setMySettings و BotFullInfo، ویجتهای HTML، پیامهای rich و ephemeral و حالت مهمان، همراه با مثال JSON.
خطاهای Telegram Bot API: معنی هر خطا و روش رفع آن
خطاهای ربات تلگرام به زبان ساده: 400 chat not found، 403 bot was blocked by the user، 409 Conflict و 429 retry_after؛ علت، راه حل و کد مدیریت خطا.
محدودیتهای Telegram Bot API: نرخ ارسال، خطای 429، حجم فایل و طول پیام
محدودیتهای Telegram Bot API به زبان ساده: 30 پیام در ثانیه، 1 پیام در ثانیه در هر چت، 20 در دقیقه در گروه، مدیریت خطای 429 و محدودیت حجم فایل.
دستورات ربات تلگرام: setMyCommands، اسکوپ دستورات و دیپلینک /start
تنظیم دستورات ربات تلگرام: /setcommands در @BotFather، متد setMyCommands با اسکوپ و زبان، پارامتر دیپلینک /start و دستور /cmd@bot در گروهها.
اتصال n8n به تلگرام: وصل کردن ربات، اجرای ورکفلو و ارسال پیام
اتصال n8n به تلگرام: توکن ربات به عنوان Access Token، وب هوک Telegram Trigger روی HTTPS عمومی، ارسال پیام با چت آیدی و رفع خطاهای رایج.
ارسال پیام با ربات تلگرام از طریق API تلگرام (sendMessage)
آموزش ارسال پیام با ربات تلگرام از طریق API تلگرام: متد sendMessage با curl، Python و JavaScript، قالببندی HTML و MarkdownV2، دکمه شیشهای و رفع خطاها.
توکن ربات تلگرام: چیست، چطور بگیریم، بررسی و باطل کنیم
توکن ربات تلگرام چیست و از کجا بگیریم؟ گرفتن توکن از BotFather، پیدا کردن توکن ربات قبلی، تست با getMe، باطل کردن توکن لو رفته و نگهداری امن آن.
وب هوک ربات تلگرام: راهاندازی setWebhook، بررسی و رفع خطا
آموزش ست وب هوک تلگرام با setWebhook: پیشنیازهای HTTPS و پورتها، secret_token، بررسی با getWebhookInfo، حذف وب هوک و رفع خطاهای رایج مثل 409.
چت آیدی تلگرام: چیست، کجاست و چطور chat id کاربر، گروه و کانال را پیدا کنیم
چت آیدی تلگرام کجاست؟ پیدا کردن chat_id کاربر، گروه، سوپرگروه، کانال و تاپیک با getUpdates، معنی آیدیهای منفی و رفع مشکل نتیجه خالی و خطای 409.
ربات اینلاین تلگرام: فعال کردن حالت inline و پاسخ به کوئریها
ساخت ربات اینلاین تلگرام: فعال کردن حالت inline با @BotFather یا setMySettings، دریافت آپدیت inline_query و پاسخ با answerInlineQuery.
پرداخت با Telegram Stars در ربات: فاکتور، پیشپرداخت، بازپرداخت و اشتراک
دریافت پرداخت با استارز تلگرام در ربات: sendInvoice با ارز XTR، پاسخ به pre_checkout_query، successful_payment، بازپرداخت و اشتراک با کد پایتون و JS.
سرور تست تلگرام: چطور ربات را در محیط تست تلگرام تست کنیم
سرور تست تلگرام برای رباتها: ورود به محیط تست، ساخت ربات تست در BotFather، فراخوانی Bot API با مسیر /test/ و سوییچ TEST در تستر ما.
ویجت تلگرام برای سایت: ورود با تلگرام، جاسازی پست، کامنتها و دکمه اشتراکگذاری
ورود با تلگرام در سایت با Telegram Login (OIDC) و ویجت قدیمی همراه کد بررسی hash، جاسازی پست کانال، ویجت کامنت و دکمه اشتراکگذاری تلگرام.
مرجع API جاوااسکریپت TelegramWidget: رویدادها، کدهای خطا و محدودیتها
مرجع API جاوااسکریپت ویجت تلگرام: ویژگیها، request()، رویدادها، کدهای خطا، متغیرهای CSS، widget_query و answerWidgetQuery و همه محدودیتها.
مثال ویجت تلگرام: کد کامل HTML و ربات پایتون
مثالهای کامل ویجت تلگرام با کد: کارت سفارش ثابت، شمارنده با widget_query، نظرسنجی زنده با ویجت اشتراکی و پیشنمایش در مرورگر با ربات پایتون.
ویجت تلگرام چیست؟ HTML تعاملی داخل پیامهای ربات
ویجت تلگرام در Bot API 10.4 چیست؟ ارسال با sendWidget، وضعیت chat_data و public_data، محدودیتها، جاهایی که فعلاً کار میکند و تفاوت با مینی اپ.
تست مینی اپ تلگرام: از mock در مرورگر تا اجرای واقعی در تلگرام
تست مینی اپ تلگرام قدم به قدم: حالت mock در مرورگر، اجرای localhost با تونل HTTPS، محیط تست، DevTools در هر پلتفرم و اعتبارسنجی initData در سرور.