Telegram Bot API

Cách deploy bot Telegram: VPS, Docker và hosting serverless

· 9 phút đọc

Để deploy bot Telegram, bạn chạy code trên một máy luôn bật và kết nối được tới api.telegram.org, rồi chọn cách nhận update: long polling bằng getUpdates — chạy trên mọi server, không cần domain — hoặc webhook, cần URL HTTPS công khai. Một VPS nhỏ với systemd hoặc một container Docker là lựa chọn phổ biến cho bot polling; nền tảng serverless như Cloudflare Workers hợp với bot webhook. Bài này trình bày từng phương án kèm cấu hình copy-paste được, cùng cách ghi log, tự khởi động lại và checklist khi lên production.

Polling hay webhook trên server

Telegram có hai cách nhận update loại trừ nhau, và dù chọn cách nào, update chưa giao cũng chỉ được giữ tối đa 24 giờ. Lựa chọn này quyết định hosting bot Telegram của bạn cần những gì:

Long polling (getUpdates)Webhook (setWebhook)
MạngChỉ cần HTTPS ra ngoài; chạy được sau NATURL HTTPS công khai, cổng 443, 80, 88 hoặc 8443, IPv4
Tiến trìnhVòng lặp chạy liên tụcHTTP handler; có thể chạy serverless
Số instanceĐúng một cho mỗi tokenNhiều instance sau một URL vẫn ổn
Nơi phù hợpVPS, Docker, server tại nhàVPS có reverse proxy, Cloudflare Workers, AWS Lambda, Vercel

Nếu polling đã chạy tốt trên máy bạn, cứ giữ nguyên: chính hướng dẫn webhook của Telegram cũng nói dùng getUpdates không có gì sai. Chỉ chuyển sang webhook khi nền tảng bắt buộc hoặc khi bạn muốn nhiều instance chia tải.

Bot polling sẵn sàng để deploy

Code chạy production cần ba điều: đọc token từ biến môi trường, ghi log ra stdout và không sập khi gặp lỗi mạng. Bot echo dưới đây đáp ứng cả ba, đồng thời gọi deleteWebhook khi khởi động vì getUpdates không hoạt động khi webhook đang bật:

import logging
import os
import time

import requests

logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s")
log = logging.getLogger("bot")

TOKEN = os.environ["BOT_TOKEN"]  # không bao giờ viết cứng token trong code
API = f"https://api.telegram.org/bot{TOKEN}"


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 main():
    call("deleteWebhook")  # polling và webhook loại trừ nhau
    log.info("started as @%s", call("getMe")["username"])
    offset = 0
    while True:
        try:
            updates = call("getUpdates", offset=offset, timeout=30)
        except Exception:
            log.exception("getUpdates failed, retrying in 5 s")
            time.sleep(5)
            continue
        for update in updates:
            offset = update["update_id"] + 1
            msg = update.get("message")
            if msg and "text" in msg:
                try:
                    call("sendMessage", chat_id=msg["chat"]["id"], text="Bạn vừa gửi: " + msg["text"])
                except Exception:
                    log.exception("update %s failed", update["update_id"])


if __name__ == "__main__":
    main()
const TOKEN = process.env.BOT_TOKEN; // không bao giờ viết cứng token trong code
if (!TOKEN) throw new Error("BOT_TOKEN is not set");
const API = `https://api.telegram.org/bot${TOKEN}`;
const log = (...args) => console.log(new Date().toISOString(), ...args);
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

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;
}

await call("deleteWebhook"); // polling và webhook loại trừ nhau
log("started as @" + (await call("getMe")).username);

let offset = 0;
while (true) {
  let updates;
  try {
    updates = await call("getUpdates", { offset, timeout: 30 });
  } catch (err) {
    log("getUpdates failed, retrying in 5 s:", err.message);
    await sleep(5000);
    continue;
  }
  for (const update of updates) {
    offset = update.update_id + 1;
    const msg = update.message;
    if (!msg?.text) continue;
    try {
      await call("sendMessage", { chat_id: msg.chat.id, text: "Bạn vừa gửi: " + msg.text });
    } catch (err) {
      log(`update ${update.update_id} failed:`, err.message);
    }
  }
}

Lưu thành bot.py (thêm requests vào requirements.txt) hoặc bot.mjs (Node.js 18+, không cần dependency). Các framework trong danh sách thư viện lo phần vòng lặp giúp bạn, nhưng các bước deploy bên dưới vẫn y như vậy.

Chạy bot Telegram trên VPS với systemd

VPS là một máy Linux bình thường. Hãy để systemd khởi động bot khi máy boot và chạy lại khi bot crash:

  1. Tạo một user không có quyền đăng nhập và copy code vào /opt/mybot; với Python, tạo virtual environment ở đó và cài các thư viện cần thiết.
  2. Ghi token vào /etc/mybot.env dưới dạng dòng BOT_TOKEN=123456789:AAEexampleTokenReplaceWithYours và giới hạn quyền bằng chmod 600.
  3. Tạo file unit /etc/systemd/system/mybot.service:
[Unit]
Description=Telegram bot
After=network-online.target
Wants=network-online.target

[Service]
User=mybot
WorkingDirectory=/opt/mybot
EnvironmentFile=/etc/mybot.env
ExecStart=/opt/mybot/.venv/bin/python -u bot.py
# Node.js: ExecStart=/usr/bin/node bot.mjs
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Bật service và theo dõi log:

sudo systemctl daemon-reload
sudo systemctl enable --now mybot
journalctl -u mybot -f        # xem log trực tiếp
sudo systemctl restart mybot  # sau khi cập nhật code

Muốn dùng webhook trên cùng VPS, hãy chạy bot như một HTTP server trên cổng local và đặt nginx hoặc Caddy phía trước để xử lý TLS trên cổng 443; bài webhook Telegram bot có sẵn handler kiểm tra secret token.

Deploy bot Telegram bằng Docker

Container đóng gói cả runtime lẫn dependency, nên bot chạy giống hệt nhau trên laptop và trên mọi máy có Docker. Dockerfile cho bot Python:

FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY bot.py .
CMD ["python", "-u", "bot.py"]
# Node.js: FROM node:22-slim, COPY bot.mjs ., CMD ["node", "bot.mjs"]

Build và chạy, truyền token lúc chạy chứ không đóng gói vào image:

docker build -t mybot .
docker run -d --name mybot --restart unless-stopped --env-file .env mybot
docker logs -f mybot

--restart unless-stopped tự chạy lại bot sau khi crash và khi máy chủ reboot. Đừng để .env lọt vào Git hay image (thêm vào .dockerignore). Khi deploy lại bot polling, hãy dừng container cũ trước khi chạy container mới: hai container cùng polling bằng một token sẽ khiến getUpdates lỗi 409 Conflict.

Serverless: bot Telegram trên Cloudflare Workers

Nền tảng serverless chỉ chạy code khi có request đến, nên phải dùng chế độ webhook. Trên Cloudflare Workers, địa chỉ mặc định workers.dev đã phục vụ HTTPS trên cổng 443. Worker dưới đây kiểm tra header secret token, trả lời ngay và xử lý tiếp ở nền bằng ctx.waitUntil:

// worker.js: deploy bằng "npx wrangler deploy"
export default {
  async fetch(request, env, ctx) {
    const url = new URL(request.url);
    if (request.method !== "POST" || url.pathname !== "/telegram/webhook") {
      return new Response("Not found", { status: 404 });
    }
    const enc = new TextEncoder();
    const received = enc.encode(request.headers.get("X-Telegram-Bot-Api-Secret-Token") ?? "");
    const expected = enc.encode(env.WEBHOOK_SECRET);
    if (received.byteLength !== expected.byteLength ||
        !crypto.subtle.timingSafeEqual(received, expected)) {
      return new Response("Forbidden", { status: 403 });
    }
    const update = await request.json();
    ctx.waitUntil(handleUpdate(update, env)); // trả 200 ngay, xử lý tiếp ở nền
    return new Response("OK");
  },
};

async function handleUpdate(update, env) {
  const msg = update.message;
  if (!msg?.text) return;
  const res = await fetch(`https://api.telegram.org/bot${env.BOT_TOKEN}/sendMessage`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ chat_id: msg.chat.id, text: "Bạn vừa gửi: " + msg.text }),
  });
  if (!res.ok) console.error("sendMessage failed", res.status, await res.text());
}

Lưu cả hai giá trị dưới dạng Worker secret, deploy, rồi đăng ký URL của Worker với cùng secret đó:

npx wrangler secret put BOT_TOKEN
npx wrangler secret put WEBHOOK_SECRET
npx wrangler deploy

curl -X POST "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/setWebhook" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://mybot.example.workers.dev/telegram/webhook", "secret_token": "replace-with-your-random-secret"}'

Hoặc điền form setWebhook trong Bot API Tester. Cách làm tương tự áp dụng cho AWS Lambda (sau function URL HTTPS hoặc API gateway) và Vercel functions: đọc JSON body, kiểm tra header, trả 2XX thật nhanh. Các nền tảng đều giới hạn thời gian chạy của function và việc chạy nền, nên hãy đẩy tác vụ chậm vào hàng đợi. Telegram gửi lại mọi phản hồi khác 2XX, nên function bị timeout hoặc crash sẽ nhận lại chính update đó.

Cách host bot Telegram miễn phí hoặc chi phí thấp

Yêu cầu webhook trên mọi nền tảng

Sau mỗi lần deploy, mở getWebhookInfo trong Bot API Tester: pending_update_count tăng dần hoặc có last_error_message mới nghĩa là Telegram không giao được update.

Biến môi trường, log và tự khởi động lại

Checklist khi deploy

  1. Token lấy từ biến môi trường hoặc secret; gọi getMe trên server thành công.
  2. Mỗi token chỉ có đúng một instance polling, hoặc một webhook có secret_token — không bao giờ cả hai.
  3. Tiến trình tự khởi động lại sau khi crash và reboot.
  4. Log được thu thập và không chứa token.
  5. Lỗi ở một update chỉ được ghi log, không làm sập bot; webhook handler trả 2XX thật nhanh.
  6. Với webhook, getWebhookInfo hiển thị đúng URL và không có lỗi gần đây.
  7. Thử nghiệm bằng một bot test riêng hoặc server test của Telegram, không dùng token production.

Xử lý sự cố khi deploy

Triệu chứngNguyên nhân và cách sửa
409 Conflict: terminated by other getUpdates requestHai instance cùng polling bằng một token (container cũ, laptop của bạn). Dừng hết, chỉ giữ một.
409 Conflict nhắc đến webhook đang bậtWebhook vẫn còn. Gọi deleteWebhook trước khi polling.
401 UnauthorizedBiến token rỗng, gõ sai hoặc token đã bị thu hồi. Kiểm tra bằng getMe.
Chạy local được, lên server thì im lặngKết nối HTTPS ra api.telegram.org bị chặn, hoặc file biến môi trường chưa được nạp. Xem log.
Bot webhook không nhận được gìXem last_error_message trong getWebhookInfo: lỗi TLS, sai cổng, 403 do sai secret hoặc handler bị crash.

Mới làm quen với bot? Hãy bắt đầu từ bài cách tạo bot Telegram, rồi quay lại đây để deploy.

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

Có thể host bot Telegram ở đâu?

Ở bất kỳ đâu gửi được request HTTPS ra ngoài: VPS, máy chạy Docker, server tại nhà hoặc nền tảng serverless. Bot dùng getUpdates không cần địa chỉ công khai; bot dùng webhook cần URL HTTPS công khai trên cổng 443, 80, 88 hoặc 8443.

Bot đã deploy nên dùng polling hay webhook?

Cả hai đều dùng được cho production. Long polling bằng getUpdates đơn giản nhất trên VPS hoặc Docker vì không cần domain hay chứng chỉ. Webhook là bắt buộc trên nền tảng serverless, nơi code chỉ chạy khi có request đến.

Vì sao gặp 409 Conflict sau khi deploy bot?

Hoặc webhook vẫn còn trong khi bot gọi getUpdates (hãy gọi deleteWebhook), hoặc có hai bản bot cùng polling, ví dụ container cũ và mới trong lúc deploy, hay laptop của bạn và server. Mỗi token chỉ chạy đúng một instance polling.

Làm sao giữ bot Telegram chạy 24/7?

Chạy bot dưới một trình giám sát tiến trình có tự khởi động lại sau khi crash và reboot: service systemd với Restart=always trên VPS, hoặc container Docker với --restart unless-stopped. Ghi log ra stdout và theo dõi bằng journalctl hoặc docker logs.

Có chạy được bot Telegram trên Cloudflare Workers không?

Được, ở chế độ webhook. Worker nhận mỗi update dưới dạng request POST, kiểm tra header X-Telegram-Bot-Api-Secret-Token và gọi Bot API bằng fetch. Đăng ký địa chỉ HTTPS workers.dev của nó bằng setWebhook. Vòng lặp long polling không phù hợp với mô hình này.

Nên lưu token bot ở đâu trên server?

Trong biến môi trường nạp từ một file chỉ user chạy bot đọc được, hoặc trong kho secret của nền tảng (ví dụ Worker secret). Không bao giờ commit token lên Git hay đóng gói vào Docker image. Nếu bị lộ, hãy thu hồi token trong @BotFather.

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.

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.

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

Cài lệnh cho bot Telegram: /setcommands trong @BotFather, setMyCommands theo scope và ngôn ngữ, tham số deep link của /start và lệnh /cmd@bot trong nhóm.

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.