Telegram Bot API

Test server Telegram: cách test bot trong môi trường thử nghiệm của Telegram

· 7 phút đọc

Test server Telegram là môi trường thử nghiệm riêng với tài khoản và bot của riêng nó, nơi bot gọi Bot API tại https://api.telegram.org/bot<token>/test/METHOD_NAME. Hãy dùng nó khi cần link HTTP thường cho Mini App hoặc Web Login, cần một nhóm người dùng test dùng xong bỏ, hoặc muốn thử những tính năng Bot API hiện chỉ bật ở đó. Với việc test bot Telegram hằng ngày, một bot thứ hai ở production thường là đủ. Bài này trình bày cả hai cách, cách đăng nhập môi trường test trên iOS, Desktop và macOS, và cách gọi API test bằng curl, Python, JavaScript và Bot API Tester của chúng tôi.

Cách 1: tạo một bot test riêng ở production

Cách nhanh nhất để test bot Telegram mà không làm phiền người dùng là chạy một bản code thứ hai trên một tài khoản bot khác:

  1. Tạo bot mới bằng lệnh /newbot trong @BotFather (xem cách tạo bot Telegram).
  2. Đưa token của bot này vào cấu hình của bản test, ví dụ một file .env riêng.
  3. Debug thoải mái với bot mới; bot production vẫn chạy bình thường, không bị động tới.

Lưu ý một điểm: file_id gắn với một bot id duy nhất. Bot test không dùng lại được các giá trị file_id mà bot chính đã lưu, nên file media phải được bot test upload lại từ đầu.

Cách 2: môi trường test chuyên dụng của Telegram

Telegram còn có một môi trường test chuyên dụng cho những nhu cầu test nâng cao. Nó tách biệt hoàn toàn với môi trường chính (production): tài khoản, bot, chat và token ở production đều không tồn tại ở đây. Những điểm khác nhau:

ProductionTest server
Tài khoản người dùngTài khoản Telegram bình thường của bạnTài khoản mới tạo trong môi trường test
Bot và tokenTạo bằng @BotFather ở productionTạo bằng @BotFather trong tài khoản test; token riêng
URL Bot API/bot<token>/METHOD_NAME/bot<token>/test/METHOD_NAME
Link Mini App và Web LoginChỉ HTTPSCho phép HTTP không có TLS
Flood limitGiới hạn tiêu chuẩnKhông được nới, đôi khi còn chặt hơn
Widget (Bot API 10.4)Chỉ trong chat riêng với botCả group, inline mode và tin nhắn chuyển tiếp

Tạo tài khoản test trên iOS, Desktop hoặc macOS

Đăng nhập vào môi trường test của Telegram từ ứng dụng chính thức:

Tài khoản test được thêm bên cạnh tài khoản thường, nên bạn có thể chuyển qua lại giữa hai môi trường ngay trong cùng một ứng dụng. Mọi thứ bạn làm ở đó, kể cả chat với bot test, đều chỉ nằm trong môi trường test.

Tạo bot trên test server và lấy token

Trong tài khoản test, mở @BotFather và tạo bot như bình thường: /newbot, tên hiển thị, rồi username kết thúc bằng bot. BotFather sẽ trả về token cho môi trường test. Token này trông giống mọi token khác, nhưng chỉ hoạt động với URL API có /test/. Hãy lưu nó dưới một tên riêng, ví dụ TEST_BOT_TOKEN, để không bao giờ lẫn với token production; các nguyên tắc trong bài hướng dẫn về token bot cũng áp dụng ở đây.

Gọi Bot API trên test server Telegram

Mọi phương thức Bot API đều hoạt động y như cũ; khác biệt duy nhất là phần /test/ sau token. Kiểm tra token bằng getMe:

curl "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/test/getMe"

Trong code, hãy để base URL trong một hằng số để việc chuyển môi trường chỉ cần sửa một dòng. Bot echo tối giản dưới đây kiểm tra token, sau đó nhận update bằng long polling getUpdates và chờ khi gặp 429 đúng theo retry_after:

import os
import time
import requests

TOKEN = os.environ["TEST_BOT_TOKEN"]
API = f"https://api.telegram.org/bot{TOKEN}/test"  # bỏ "/test" khi chạy production


def call(method, **params):
    while True:
        data = requests.post(f"{API}/{method}", json=params, timeout=40).json()
        if data["ok"]:
            return data["result"]
        if data.get("error_code") == 429:  # flood limit: chờ đúng thời gian được báo
            time.sleep(data["parameters"]["retry_after"])
            continue
        raise RuntimeError(f"{method}: {data['error_code']} {data['description']}")


me = call("getMe")
print("Đang chạy trên test server với tên @" + me["username"])

offset = 0
while True:
    for update in call("getUpdates", offset=offset, timeout=30):
        offset = update["update_id"] + 1
        msg = update.get("message")
        if msg and "text" in msg:
            call("sendMessage", chat_id=msg["chat"]["id"], text="Test echo: " + msg["text"])
const TOKEN = process.env.TEST_BOT_TOKEN;
const API = `https://api.telegram.org/bot${TOKEN}/test`; // bỏ "/test" khi chạy production

async function call(method, params = {}) {
  while (true) {
    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) return data.result;
    if (data.error_code === 429) { // flood limit: chờ đúng thời gian được báo
      await new Promise((resolve) => setTimeout(resolve, data.parameters.retry_after * 1000));
      continue;
    }
    throw new Error(`${method}: ${data.error_code} ${data.description}`);
  }
}

const me = await call("getMe");
console.log("Đang chạy trên test server với tên @" + me.username);

let offset = 0;
while (true) {
  for (const update of await call("getUpdates", { offset, timeout: 30 })) {
    offset = update.update_id + 1;
    const msg = update.message;
    if (msg?.text) {
      await call("sendMessage", { chat_id: msg.chat.id, text: "Test echo: " + msg.text });
    }
  }
}

Gửi /start cho bot từ tài khoản test và bot sẽ trả lời. Bản JavaScript dùng await ở cấp cao nhất, nên hãy lưu thành bot.mjs và chạy bằng Node.js 18 trở lên.

Webhook cũng hoạt động tương tự: gọi setWebhook qua URL test, các quy tắc quen thuộc về url, cổng và secret_token vẫn giữ nguyên. Kiểm tra kết quả bằng getWebhookInfo, cũng qua /test/:

curl "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/test/setWebhook" \
  -d "url=https://example.com/telegram/webhook"
curl "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/test/getWebhookInfo"

Các thư viện bot thường ghép URL request từ một địa chỉ gốc. Nếu thư viện bạn dùng cho phép thay base URL của Bot API, hãy đặt sao cho request đi tới …/bot<token>/test/METHOD_NAME; tên tùy chọn mỗi thư viện một khác, nên hãy tra trong tài liệu của thư viện đó.

Thử test server ngay trong Bot API Tester

Bot API Tester của chúng tôi gửi được request tới môi trường test mà không cần viết dòng code nào:

  1. Mở getMe trong Bot API Tester.
  2. Bật công tắc TEST cạnh ô nhập token, hoặc mở trang tester với ?env=test trên thanh địa chỉ.
  3. Dán token của bot test rồi bấm Execute. Lúc này request sẽ đi tới https://api.telegram.org/bot<token>/test/METHOD.

Khi công tắc đang bật, mọi phương thức đều dùng URL test, kể cả long polling getUpdates, nên bạn có thể xem update từ tài khoản test xuất hiện trong lịch sử update. Tester ghi nhớ trạng thái công tắc trong trình duyệt; hãy tắt nó trước khi dán token production. Như mọi khi, token chỉ nằm trong localStorage của trình duyệt và request đi thẳng tới api.telegram.org.

Mini App và Web Login qua HTTP thường

Đây là lý do chính khiến dev Mini App dùng môi trường test: ở đó, url trong WebAppInfo (Mini App) và LoginUrl (nút Web Login) có thể là link HTTP không có TLS. Nhờ vậy bạn có thể trỏ menu button hoặc nút web_app của bot test tới dev server trong mạng nội bộ mà không phải cài chứng chỉ hay dựng tunnel. Ở production, link bắt buộc phải là HTTPS. Muốn thử JavaScript API của Mini App ngay trong trình duyệt thường, hãy dùng Mini App Tester của chúng tôi.

Widget Bot API 10.4 trên test server

Widget HTML trong tin nhắn, có từ Bot API 10.4, hiện ở production chỉ chạy trong chat riêng với bot. Widget trong group, trong inline mode và trong tin nhắn chuyển tiếp tạm thời chỉ hoạt động trên test server, nên đó là nơi để thử các kịch bản này. Xem bài widget Telegram để hiểu widget hoạt động ra sao.

Giới hạn và kinh nghiệm thực tế

Xử lý lỗi thường gặp

Hiện tượngNguyên nhân thường gặpCách khắc phục
401 UnauthorizedGửi token production tới /test/, hoặc gửi token test mà thiếu /test/Hai môi trường tách biệt: dùng token khớp với URL (hoặc với công tắc TEST trong tester)
400 Bad Request: chat not foundChat id lấy từ production; người dùng và chat đó không tồn tại trên test serverNhắn cho bot test từ tài khoản test và lấy chat id từ getUpdates
Không tìm thấy bot khi tìm kiếmĐang tìm từ tài khoản productionTìm từ tài khoản test, nơi bot được tạo
429 Too Many RequestsFlood limit, vốn không được nới trên test serverChờ retry_after giây và giảm tốc độ gửi
Mini App qua HTTP không mở đượcBot hoặc tài khoản đang ở productionDùng bot tạo trong môi trường test và mở từ tài khoản test

Câu hỏi thường gặp

Test server Telegram là gì?

Là môi trường thử nghiệm riêng, tách biệt hoàn toàn với Telegram production. Ở đó có tài khoản người dùng và bot riêng, và bot gọi Bot API tại https://api.telegram.org/bot<token>/test/METHOD_NAME.

Đăng nhập vào môi trường test của Telegram như thế nào?

Trên iOS, chạm biểu tượng Settings 10 lần → Accounts → Login to another account → Test. Trên Telegram Desktop, mở ☰ Settings, giữ Shift + Alt và nhấp chuột phải vào Add Account → Test Server. Trên macOS, nhấp biểu tượng Settings 10 lần để mở Debug Menu, rồi ⌘ + click vào Add Account.

Có dùng token bot production trên test server được không?

Không. Hai môi trường tách biệt, nên bot tạo ở production không tồn tại trên test server và ngược lại. Hãy tạo bot mới với @BotFather ngay trong tài khoản test; dùng token sai môi trường thường sẽ nhận lỗi 401 Unauthorized.

Giới hạn request trên test server Telegram có cao hơn không?

Không. Flood limit trong môi trường test không được nới và đôi khi còn chặt hơn, vì vậy hãy xử lý 429 Too Many Requests theo retry_after và đừng hardcode các con số giới hạn.

Mini App có dùng HTTP thường trong môi trường test được không?

Được. Trong môi trường test, url của WebAppInfo (Mini App) và LoginUrl (Web Login) có thể là link HTTP không có TLS. Ở production bắt buộc phải dùng HTTPS.

Muốn test bot Telegram có nhất thiết phải dùng test server không?

Không. Phần lớn trường hợp chỉ cần một bot thứ hai tạo bằng @BotFather ở production: bot này có token riêng và không ảnh hưởng tới người dùng thật. Hãy dùng test server khi cần link HTTP, tài khoản test riêng hoặc tính năng hiện chỉ có ở đó.

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.

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.

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.