Lệnh bot Telegram: setMyCommands, scope của lệnh và deep link cho /start
Lệnh bot Telegram là các từ khóa dạng /lệnh như /start hay /help mà ứng dụng Telegram tô sáng trong tin nhắn, gợi ý khi người dùng gõ / và liệt kê trong menu của bot. Bạn đặt danh sách lệnh bằng /setcommands trong @BotFather hoặc bằng phương thức setMyCommands — cách này còn hỗ trợ scope (lệnh khác nhau cho nhóm, admin hay một chat cụ thể) và danh sách theo ngôn ngữ. Bot nhận lệnh như một tin nhắn văn bản bình thường, và /start có thể mang theo tham số deep link. Bài này trình bày tất cả, kèm ví dụ curl, Python và JavaScript.
Lệnh bot Telegram hoạt động thế nào
Lệnh đơn giản là tin nhắn bắt đầu bằng /. Đăng ký lệnh không thay đổi những gì bot nhận được; nó chỉ cho ứng dụng Telegram biết cần gợi ý gì. Quy tắc cho danh sách đăng ký bằng setMyCommands (object BotCommand):
command: 1–32 ký tự, chỉ gồm chữ cái tiếng Anh viết thường, chữ số và dấu gạch dưới, không kèm dấu/ở đầu.description: 1–256 ký tự, hiển thị cạnh lệnh trong danh sách gợi ý.- Tối đa 100 lệnh mỗi danh sách.
Telegram khuyến nghị mọi bot hỗ trợ các lệnh chung /start (bắt đầu tương tác, đồng thời nhận tham số deep link) và /help (bot làm được gì và danh sách lệnh), thêm /settings nếu bot có phần cài đặt. Nên dùng lệnh cụ thể như /newlocation thay vì một lệnh chung chung /new cần thêm đối số.
Đặt lệnh bằng @BotFather
Cách không cần code, phù hợp với danh sách cố định:
- Mở @BotFather và gửi
/setcommands. - Chọn bot của bạn.
- Gửi danh sách, mỗi lệnh một dòng theo định dạng
command - mô tả:
start - Khởi động bot
help - Hướng dẫn sử dụng bot
settings - Cài đặt của bạn
Nếu chưa có bot, hãy bắt đầu với bài cách tạo bot Telegram.
Đặt lệnh bằng setMyCommands
setMyCommands làm điều tương tự từ code, nên danh sách lệnh có thể nằm trong repository và được cập nhật mỗi lần deploy. Tham số: commands (bắt buộc, mảng BotCommand), scope (tùy chọn, mặc định là scope default) và language_code (tùy chọn, mã ISO 639-1 hai chữ cái). Phương thức trả về true:
curl "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/setMyCommands" \
-H "Content-Type: application/json" \
-d '{"commands":[{"command":"start","description":"Khởi động bot"},{"command":"help","description":"Hướng dẫn sử dụng bot"}]}'
Muốn thử mà không cần code, mở setMyCommands trong Bot API Tester, dán token, điền danh sách lệnh và bấm Execute. Sau đó gọi getMyCommands để xem danh sách đã lưu.
Scope của lệnh và ngôn ngữ
Scope quyết định ai thấy danh sách lệnh. Có 7 loại BotCommandScope:
type của scope | Ai thấy danh sách | Trường bổ sung |
|---|---|---|
default | Tất cả mọi người, nếu không có danh sách hẹp hơn | — |
all_private_chats | Mọi chat riêng với bot | — |
all_group_chats | Mọi nhóm và supergroup | — |
all_chat_administrators | Admin của mọi nhóm và supergroup | — |
chat | Một chat cụ thể | chat_id |
chat_administrators | Admin của một nhóm hoặc supergroup | chat_id |
chat_member | Một thành viên của một nhóm hoặc supergroup | chat_id, user_id |
chat_id là id dạng số hoặc @username của supergroup; kênh và chat tin nhắn trực tiếp của kênh không được hỗ trợ. Mỗi scope có thể có danh sách riêng theo ngôn ngữ: có language_code thì danh sách dành cho người dùng đặt ứng dụng ở ngôn ngữ đó, không có thì dành cho mọi người trong scope chưa có danh sách theo ngôn ngữ của mình.
Telegram hiển thị danh sách đầu tiên được đặt, kiểm tra từ scope hẹp nhất trở xuống. Trong chat riêng, thứ tự là chat → all_private_chats → default; trong nhóm là chat_member → chat_administrators → chat → all_chat_administrators → all_group_chats → default (các scope admin chỉ áp dụng cho admin). Ở mỗi bước, danh sách có language_code trùng ngôn ngữ người dùng được ưu tiên hơn danh sách không có.
Script dưới đây đặt danh sách mặc định (tiếng Anh), bản tiếng Việt và các lệnh bổ sung cho admin nhóm, rồi đọc lại một danh sách:
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"]
# Danh sách mặc định cho mọi người
call("setMyCommands", commands=[
{"command": "start", "description": "Start the bot"},
{"command": "help", "description": "How to use the bot"},
{"command": "settings", "description": "Your settings"},
])
# Cùng các lệnh đó cho người dùng đặt ứng dụng Telegram bằng tiếng Việt
call("setMyCommands", language_code="vi", commands=[
{"command": "start", "description": "Khởi động bot"},
{"command": "help", "description": "Hướng dẫn sử dụng bot"},
{"command": "settings", "description": "Cài đặt của bạn"},
])
# Lệnh bổ sung cho admin của mọi nhóm
call("setMyCommands", scope={"type": "all_chat_administrators"}, commands=[
{"command": "help", "description": "How to use the bot"},
{"command": "stats", "description": "Group statistics"},
])
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;
}
// Danh sách mặc định cho mọi người
await call("setMyCommands", {
commands: [
{ command: "start", description: "Start the bot" },
{ command: "help", description: "How to use the bot" },
{ command: "settings", description: "Your settings" },
],
});
// Cùng các lệnh đó cho người dùng đặt ứng dụng Telegram bằng tiếng Việt
await call("setMyCommands", {
language_code: "vi",
commands: [
{ command: "start", description: "Khởi động bot" },
{ command: "help", description: "Hướng dẫn sử dụng bot" },
{ command: "settings", description: "Cài đặt của bạn" },
],
});
// Lệnh bổ sung cho admin của mọi nhóm
await call("setMyCommands", {
scope: { type: "all_chat_administrators" },
commands: [
{ command: "help", description: "How to use the bot" },
{ command: "stats", description: "Group statistics" },
],
});
console.log(await call("getMyCommands", { scope: { type: "all_chat_administrators" } }));Scope chỉ quyết định người dùng thấy gì. Update không cho biết lệnh đến từ scope nào, và người dùng có thể gõ bất kỳ lệnh nào, kể cả lệnh bạn chưa từng đăng ký. Luôn kiểm tra ở server rằng lệnh có tồn tại và người dùng được phép chạy nó (ví dụ kiểm tra quyền admin bằng getChatMember).
getMyCommands và deleteMyCommands
getMyCommands trả về mảng BotCommand cho scope và language_code đã cho, hoặc mảng rỗng nếu chưa đặt. deleteMyCommands xóa danh sách của scope và ngôn ngữ đó; người dùng liên quan sẽ thấy danh sách kế tiếp theo thứ tự ưu tiên:
curl "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/deleteMyCommands" \
-H "Content-Type: application/json" \
-d '{"scope":{"type":"all_chat_administrators"}}'
Xử lý lệnh và tham số của /start
Lệnh đến dưới dạng update message bình thường, với văn bản đúng như người dùng gõ. Trong nhóm, lệnh có thể gửi đích danh cho một bot dạng /command@your_bot, nên hãy tách phần @username và bỏ qua lệnh dành cho bot khác. Deep link hoạt động như sau:
https://t.me/your_bot?start=airplanemở chat với bot, và bot nhận/start airplane.https://t.me/your_bot?startgroup=spaceshipyêu cầu người dùng chọn nhóm để thêm bot vào; bot nhận/start@your_bot spaceship.- Tham số dài tối đa 64 ký tự; chỉ cho phép
A-Z,a-z,0-9,_và-. Với dữ liệu nhị phân hoặc dạng khác, Telegram khuyên dùng base64url.
Bot long polling dưới đây phân tích lệnh, xử lý /start có và không có tham số, đồng thời tạo deep link bằng base64url:
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:
# base64url bỏ padding "=": chỉ còn A-Z a-z 0-9 _ - (tối đa 64 ký tự)
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 # không phải lệnh, hoặc lệnh dành cho bot khác
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("Chia sẻ link này:", 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, "Xin chào! Bạn đến từ: " + read_start_param(args))
except ValueError:
send(chat_id, "Xin chào! Tham số start không hợp lệ.")
elif name == "start":
send(chat_id, "Xin chào! Gửi /help để xem tôi làm được gì.")
elif name == "help":
send(chat_id, "/start - khởi động bot\n/help - tin nhắn này\n/settings - cài đặt của bạn")
elif name == "settings":
send(chat_id, "Chưa có cài đặt nào.")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) {
// base64url của Node không có padding "=": chỉ còn A-Z a-z 0-9 _ - (tối đa 64 ký tự)
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; // không phải lệnh, hoặc lệnh dành cho bot khác
}
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("Chia sẻ link này:", 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, "Xin chào! Bạn đến từ: " + readStartParam(args));
} else if (name === "start") {
await send(chatId, "Xin chào! Gửi /help để xem tôi làm được gì.");
} else if (name === "help") {
await send(chatId, "/start - khởi động bot\n/help - tin nhắn này\n/settings - cài đặt của bạn");
} else if (name === "settings") {
await send(chatId, "Chưa có cài đặt nào.");
}
}
}Lưu bản JavaScript thành bot.mjs và chạy bằng Node.js 18+ (code dùng top-level await). Hãy coi tham số start là dữ liệu không đáng tin: ai cũng có thể tự tạo link, nên đừng bao giờ đặt vào đó một bí mật tự nó cấp quyền truy cập. getUpdates không hoạt động khi webhook đang bật; khi chạy production, xem bài cài webhook Telegram bot.
Lệnh trong nhóm và privacy mode
Bot trong nhóm mặc định chạy ở privacy mode. Khi đó bot nhận các lệnh gửi đích danh cho nó (/command@your_bot), lệnh chung như /start chỉ khi nó là bot gửi tin nhắn gần nhất trong nhóm, các tin trả lời tin nhắn của nó và tin nhắn dịch vụ. Khi nhiều bot cùng ở một nhóm, hãy hướng dẫn người dùng chạm vào lệnh trong danh sách gợi ý — ứng dụng sẽ tự thêm phần @your_bot. Để nhận mọi tin nhắn, cho bot làm admin hoặc tắt privacy mode bằng /setprivacy trong @BotFather.
Nút menu
Trong chat riêng, nút menu cạnh ô nhập mặc định mở danh sách lệnh. Bạn có thể đổi nó sang mở Mini App, hoặc trả lại danh sách lệnh, bằng setChatMenuButton; không truyền chat_id thì thay đổi áp dụng mặc định cho mọi chat:
curl "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/setChatMenuButton" \
-H "Content-Type: application/json" \
-d '{"menu_button":{"type":"commands"}}'
Các loại khác là web_app (kèm text và web_app) và default. Từ Bot API 10.2, BotCommand còn có thể có is_ephemeral: true: lệnh như vậy gửi trong nhóm sẽ không hiện với các thành viên và bot khác, chỉ bot đích nhận được.
Kinh nghiệm khi thiết kế lệnh bot
- Giữ danh sách ngắn gọn. Chỉ đăng ký những lệnh người dùng thật sự cần; công cụ quản trị ít dùng nên để trong scope dành riêng cho admin.
- Viết mô tả theo hành động. "Tạo lời nhắc" rõ nghĩa hơn "Lời nhắc".
- Đặt lệnh khi deploy. Gọi
setMyCommandstrong script deploy giúp menu luôn khớp với code xử lý lệnh. - Trả lời lịch sự với lệnh không xác định trong chat riêng, ví dụ gợi ý gửi
/help. - Dùng nút cho các lựa chọn. Với luồng nhiều bước, inline keyboard thường dễ dùng hơn lệnh kèm đối số.
Xử lý sự cố
| Triệu chứng | Nguyên nhân thường gặp | Cách sửa |
|---|---|---|
400 kèm BOT_COMMAND_INVALID | Có chữ hoa, dấu gạch ngang, dấu / ở đầu hoặc quá 32 ký tự trong command | Dùng 1–32 ký tự gồm chữ thường, chữ số và dấu gạch dưới, không có dấu gạch chéo |
| Đã đặt lệnh nhưng người dùng thấy danh sách khác | Một scope hẹp hơn hoặc danh sách theo ngôn ngữ của người dùng được ưu tiên | Kiểm tra từng scope và ngôn ngữ bằng getMyCommands |
Bot bỏ qua /start trong nhóm | Privacy mode và bot khác vừa gửi tin nhắn gần nhất | Gửi /start@your_bot, hoặc đổi privacy mode |
| Tham số start không đến | Có ký tự ngoài A-Z a-z 0-9 _ - (ví dụ padding =) hoặc dài hơn 64 ký tự | Mã hóa base64url, bỏ padding, rút ngắn dữ liệu |
401 Unauthorized | Token sai hoặc đã bị thu hồi | Xem bài cách lấy token bot Telegram |
Câu hỏi thường gặp
Làm sao thêm lệnh cho bot Telegram?
Gửi /setcommands cho @BotFather rồi chọn bot, hoặc gọi phương thức setMyCommands của Bot API với danh sách object BotCommand. Sau đó ứng dụng Telegram sẽ gợi ý lệnh khi người dùng gõ / và hiển thị chúng trong menu.
Lệnh bot Telegram được chứa những ký tự nào?
Trong setMyCommands, tên lệnh dài 1–32 ký tự và chỉ gồm chữ cái tiếng Anh viết thường, chữ số và dấu gạch dưới. Mô tả dài 1–256 ký tự. Mỗi scope và ngôn ngữ có tối đa 100 lệnh.
Làm sao truyền tham số cho /start?
Dùng deep link dạng https://t.me/your_bot?start=airplane. Bot sẽ nhận tin nhắn /start airplane. Tham số dài tối đa 64 ký tự, chỉ gồm A-Z, a-z, 0-9, _ và -; dữ liệu khác thì mã hóa base64url.
Vì sao bot không thấy lệnh trong nhóm?
Khi privacy mode bật (mặc định), bot trong nhóm nhận các lệnh gửi đích danh cho nó như /command@your_bot, còn lệnh chung như /start chỉ nhận nếu nó là bot gửi tin nhắn gần nhất trong nhóm. Hãy dùng dạng @your_bot, cho bot làm admin hoặc tắt privacy mode bằng /setprivacy.
Làm sao hiển thị lệnh riêng cho admin nhóm?
Gọi setMyCommands với scope là {"type": "all_chat_administrators"} cho mọi nhóm, hoặc {"type": "chat_administrators", "chat_id": ...} cho một nhóm. Vẫn phải kiểm tra quyền ở server: update không cho biết lệnh đến từ scope nào.
Làm sao xóa toàn bộ lệnh của bot?
Gọi deleteMyCommands cho từng scope và language_code đã đặt. Sau khi xóa, người dùng sẽ thấy danh sách kế tiếp theo thứ tự ưu tiên, ví dụ danh sách lệnh mặc định.
Bài viết liên quan
Cách tạo bot Telegram từ A đến Z: BotFather, token và tin nhắn đầu tiên
Tạo bot Telegram miễn phí với @BotFather: chọn username, lấy token, kiểm tra bằng getMe, tìm chat id và gửi tin nhắn đầu tiên bằng curl, Python.
Cách deploy bot Telegram: VPS, Docker và hosting serverless
Cách deploy bot Telegram: chọn polling hay webhook, chạy service systemd trên VPS, Docker, Cloudflare Workers với secret_token và checklist lên production.
Telegram Bot API 10.0–10.5: cài đặt bot, widget, rich message, tin nhắn ephemeral, guest mode và hơn thế
Tổng hợp thay đổi Telegram Bot API 10.0–10.5: setMySettings, BotFullInfo, widget HTML, rich message, tin nhắn ephemeral, guest mode, kèm ví dụ JSON.
Lỗi Telegram Bot API: ý nghĩa từng lỗi và cách khắc phục
Giải thích lỗi Telegram Bot API: 400 chat not found, 403 bot was blocked by the user, 409 Conflict, 429 retry_after. Nguyên nhân, cách sửa và code xử lý.
Giới hạn Telegram Bot API: rate limit, lỗi 429, dung lượng file và độ dài tin nhắn
Giới hạn Telegram Bot API: 30 tin/giây, 1 tin/giây mỗi chat, 20 tin/phút trong group, xử lý lỗi 429 retry_after, dung lượng file và độ dài tin nhắn.
Bàn phím bot Telegram: inline keyboard, nút callback và reply keyboard
Thêm nút bấm cho bot Telegram: inline keyboard với callback_data, answerCallbackQuery, sửa tin nhắn sau khi bấm, reply keyboard và ForceReply, có code mẫu.
Tích hợp n8n với Telegram: kết nối bot, kích hoạt workflow và gửi tin nhắn
Kết nối n8n với Telegram: dùng token bot làm Access Token, Telegram Trigger cần webhook HTTPS công khai, gửi tin nhắn theo chat id và cách sửa lỗi hay gặp.
API gửi tin nhắn Telegram: hướng dẫn sendMessage với curl, Python và JavaScript
Dùng API gửi tin nhắn Telegram qua sendMessage: ví dụ curl, Python requests, JavaScript fetch, định dạng HTML, MarkdownV2, nút inline và lỗi 400, 403, 429.
Cách lấy token bot Telegram: tìm lại, kiểm tra bằng getMe và thu hồi khi bị lộ
Cách lấy token bot Telegram từ @BotFather, xem lại token của bot cũ, kiểm tra bằng getMe, sửa lỗi 401 Unauthorized và thu hồi token khi bị lộ.
Webhook Telegram bot: cài setWebhook, bảo mật bằng secret_token và dùng với n8n
Cài webhook Telegram bot từng bước: yêu cầu HTTPS và cổng, setWebhook với secret_token, kiểm tra getWebhookInfo, sửa lỗi 409 Conflict và webhook n8n.
Chat id Telegram lấy ở đâu? Cách lấy chat id cho người dùng, group, kênh và topic
Chat id Telegram lấy ở đâu: cách lấy chat id bot cho chat riêng, group, supergroup, kênh và topic bằng getUpdates, kèm cách sửa lỗi result rỗng, 409.
Bot inline Telegram: cách bật inline mode và trả lời inline query
Hướng dẫn làm bot inline Telegram: bật inline mode qua @BotFather hoặc setMySettings, xử lý update inline_query và trả kết quả bằng answerInlineQuery.
Thanh toán Telegram Stars cho bot: hóa đơn, pre-checkout, hoàn tiền và thuê bao
Nhận thanh toán Telegram Stars trong bot: sendInvoice với XTR, pre_checkout_query, successful_payment, hoàn tiền, gói thuê bao và code Python/JS.
Test server Telegram: cách test bot trong môi trường thử nghiệm của Telegram
Cách dùng test server Telegram: đăng nhập môi trường test, tạo bot test, gọi Bot API qua /test/ và bật chế độ TEST trong công cụ tester của chúng tôi.
Widget Telegram cho website: Login Widget, nhúng bài đăng, bình luận và nút chia sẻ
Đăng nhập bằng Telegram trên website: Telegram Login mới (OIDC), Login Widget cũ kèm code kiểm tra hash, nhúng bài đăng, bình luận và nút chia sẻ.
TelegramWidget JavaScript API: thuộc tính, sự kiện, mã lỗi và giới hạn
Tra cứu TelegramWidget JavaScript API: thuộc tính, request(), sự kiện, mã lỗi, biến CSS, widget_query, answerWidgetQuery và mọi giới hạn của widget.
Ví dụ widget Telegram: HTML hoàn chỉnh và code bot Python
Ví dụ widget Telegram chạy được kèm code đầy đủ: thẻ đơn hàng tĩnh, bộ đếm dùng widget_query, bình chọn trực tiếp dạng widget dùng chung và stub xem thử.
Widget Telegram: HTML tương tác ngay trong tin nhắn của bot
Widget Telegram (Bot API 10.4) là gì: cách sendWidget, chat_data và public_data hoạt động, widget chạy ở đâu và khác Mini App như thế nào.
Cách test Telegram Mini App: từ mock trên trình duyệt đến Telegram thật
Hướng dẫn test Telegram Mini App: chạy mock trên trình duyệt, localhost qua tunnel HTTPS, môi trường test, DevTools từng nền tảng và xác thực initData.