Telegram Bot API

Lệnh bot Telegram: setMyCommands, scope của lệnh và deep link cho /start

· 8 phút đọc

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):

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:

  1. Mở @BotFather và gửi /setcommands.
  2. Chọn bot của bạn.
  3. 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 scopeAi thấy danh sáchTrường bổ sung
defaultTất cả mọi người, nếu không có danh sách hẹp hơn—
all_private_chatsMọi chat riêng với bot—
all_group_chatsMọi nhóm và supergroup—
all_chat_administratorsAdmin của mọi nhóm và supergroup—
chatMột chat cụ thểchat_id
chat_administratorsAdmin của một nhóm hoặc supergroupchat_id
chat_memberMột thành viên của một nhóm hoặc supergroupchat_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:

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.

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

Xử lý sự cố

Triệu chứngNguyên nhân thường gặpCách sửa
400 kèm BOT_COMMAND_INVALIDCó chữ hoa, dấu gạch ngang, dấu / ở đầu hoặc quá 32 ký tự trong commandDù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ácMột scope hẹp hơn hoặc danh sách theo ngôn ngữ của người dùng được ưu tiênKiểm tra từng scope và ngôn ngữ bằng getMyCommands
Bot bỏ qua /start trong nhómPrivacy mode và bot khác vừa gửi tin nhắn gần nhấtGửi /start@your_bot, hoặc đổi privacy mode
Tham số start không đếnCó 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 UnauthorizedToken sai hoặc đã bị thu hồiXem 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.

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.