Bắt đầu nhanh: từ số không đến vận hành, không bỏ sót bước nào

Lối mặc định là lưu trữ trên đám mây: chỉ cần một chiếc điện thoại và khoảng 10 phút — không máy chủ, không lập trình. Mỗi bước đều cho bạn biết cần mở màn hình nào và chạm vào đâu, cùng những cạm bẫy mà người ta thực sự gặp phải.

Mục lục Danh sách chuẩn bị Bước 1 · Tạo bot trong BotFather (hai công tắc then chốt) Bước 2 · Liên kết bot trong Telegram Business Bước 3 · Tạo nhóm diễn đàn console của bạn Bước 4 · Chọn một: ☁️ Lưu trữ đám mây (khuyên dùng) / 💻 Tự lưu trữ Bước 5 · Thử trò chuyện Khắc phục sự cố

🧾 Danh sách chuẩn bị

1Tạo bot trong BotFather

Trong Telegram, tìm @BotFather (để ý huy hiệu xác minh màu xanh) và tiến hành đoạn hội thoại sau:

🤖 BotFather
/newbot
BotFatherAlright, a new bot. How are we going to call it? Please choose a name for your bot.
LingoDesk Assistant
BotFatherGood. Now let's choose a username for your bot. It must end in bot.
my_lingodesk_bot
BotFatherDone! Use this token to access the HTTP API:
8123456789:AAHfK3xxxxxxxxxxxxxxxxxxxxxxxxx
Keep your token secure and store it safely…

1a. Bật Secretary Mode (bắt buộc; trước đây là "Business Mode")

⚠️ Vào tháng 5 năm 2026, Telegram đã đổi tên công tắc này thành Secretary Mode; các phiên bản cũ có thể vẫn ghi là Business Mode — cùng một thứ. Hãy làm việc này bên trong khung chat @BotFather (không phải trang hồ sơ bot của bạn, và cũng không phải mục cài đặt Telegram trên điện thoại). Có hai giao diện — cái nào cũng được:

Giao diện ① Lệnh kiểu cũ — chỉ cần gửi tin nhắn:

/mybots→ @my_lingodesk_bot→ Bot Settings→ Secretary Mode→ Turn on

Giao diện ② Bảng quản lý mới — chạm nút Open màu xanh cạnh ô soạn tin của BotFather:

Open (bảng điều khiển)→ chọn bot của bạn→ Settings→ Mode Settings→ gạt bật Secretary Mode
Không tìm thấy? ① Nó có hai tên: Secretary Mode ở phiên bản mới, Business Mode ở phiên bản cũ — hãy tìm một trong hai; ② đảm bảo bạn đang ở trong @BotFather, không phải mục cài đặt bot của chính bạn; ③ công tắc này không liên quan gì đến Telegram Premium — Premium chỉ quan trọng khi liên kết ở phía tài khoản của bạn tại Bước 2; ai cũng có thể gạt công tắc này.
Nếu không bật Secretary Mode, Telegram sẽ hiện một cửa sổ bật lên — "This bot doesn't support Telegram Business yet" — khi bạn thử thêm bot ở Bước 2. Đây là rào cản phổ biến nhất. Cứ gạt công tắc: nó có hiệu lực tức thì, không cần tạo lại bot; chỉ việc thử thêm lại.

1b. Tắt Group Privacy (bắt buộc)

/mybots→ @my_lingodesk_bot→ Bot Settings→ Group Privacy→ Turn off
Group Privacy mặc định bật, và khi còn bật thì bot không thể thấy các câu trả lời bạn gõ trong nhóm console — triệu chứng là "tôi gõ trong chủ đề mà chẳng có gì xảy ra". Hãy tắt nó đi (BotFather phải báo Privacy mode is disabled).

2Liên kết bot trong Telegram Business

Trên ứng dụng Telegram di động (hiện thiết lập này chỉ có trên di động):

⚙️ Cài đặt→ 💼 Telegram Business→ 🤖 Chatbots

Ở phiên bản mới hơn, mục này có tên "Chat Automation" — nhãn khác, cùng một lối vào.

  1. Gõ username của bot (ví dụ my_lingodesk_bot) vào ô tìm kiếm rồi chọn nó.
  2. Quyền: bật "Reply to messages" — nếu không, bot có thể đọc nhưng không bao giờ gửi thay bạn được.
  3. Với mục "những cuộc trò chuyện nào", hãy chọn All 1:1 Chats; thêm bất kỳ liên hệ riêng tư nào bạn muốn giữ ngoài luồng chuyển tiếp vào danh sách Excluded Chats.
Sau khi liên kết, mọi tin nhắn riêng tư bạn nhận được đều âm thầm được "cc" cho bot — phía bên kia chẳng nhận ra gì, và trải nghiệm chat của chính bạn cũng không thay đổi chút nào.

3Tạo nhóm diễn đàn console của bạn

Nhóm này là bàn làm việc của bạn: mỗi liên hệ một chủ đề, với các thẻ tin nhắn song ngữ hiện lên bên trong.

  1. Tạo một nhóm: New → New Group, thêm bot của bạn làm thành viên duy nhất (tìm theo username). Đặt tên tùy ý, ví dụ "LingoDesk Console".
  2. Bật Topics: mở nhóm → chạm vào tên để vào hồ sơ → Edit → gạt bật Topics. Nhóm sẽ nâng cấp thành supergroup và có danh sách chủ đề.
  3. Thăng bot lên quản trị viên: hồ sơ → Administrators → Add Admin → chọn bot của bạn → tích "Manage Topics" (giữ nguyên phần còn lại) → lưu.
Bot tự động tạo một chủ đề cho mỗi liên hệ. Nếu thiếu quyền admin + "Manage Topics" thì việc đó thất bại — triệu chứng là "khách hàng nhắn cho tôi nhưng chẳng thấy gì hiện trong nhóm".
Nhóm chỉ cần bạn và bot — không cần người nào khác. Nếu bạn thêm một cộng sự, các câu trả lời của họ trong một chủ đề cũng sẽ kích hoạt dịch và gửi đi y như của bạn.

4Chọn một: ☁️ Lưu trữ đám mây hoặc 💻 Tự lưu trữ

Mọi thứ ở phía điện thoại đã xong. Giờ hãy chọn lối đi của bạn — không có máy chủ? Chọn A: chẳng phải cài gì cả.

☁️ Phương án A · Lưu trữ đám mây (khuyên dùng: không máy chủ, không lập trình, tức thì)

  1. Nhắn cho bot kích hoạt chính thức @LingoDeskbot, gửi /start, rồi dán thẳng BOT_TOKEN từ Bước 1 vào khung chat.
  2. Kích hoạt tự động tức thì: khi token được xác thực, bot trả lời "🎉 Activated" (và xóa tin nhắn chứa token của bạn). Gói Miễn phí gồm 300 câu trả lời được dịch/tháng; nâng lên Pro (500 ⭐/tháng) bất cứ lúc nào để dùng không giới hạn. Bộ máy dịch do chúng tôi lo — không phải đăng ký API Key nào cả.
  3. Làm theo câu trả lời của bot để hoàn tất liên kết, rồi gửi /bind trong nhóm console của bạn — bot trả lời "✅ bound" là xong. Nhảy tới Bước 5 để thử. Nhắn /status cho bot bất cứ lúc nào, hoặc /native en để đặt ngôn ngữ của chính bạn.
Lo lắng khi giao token? Nó được lưu trữ dạng mã hóa và chỉ dùng để chuyển tiếp những cuộc trò chuyện bạn đã cho phép trong Telegram Business — và bạn luôn nắm quyền: thu hồi nó bất cứ lúc nào trong BotFather (/mybots → API Token → Revoke) và token cũ chết ngay lập tức.

💻 Phương án B · Tự lưu trữ (máy của riêng bạn, dữ liệu của riêng bạn)

Trước tiên lấy một khóa dịch tại console.anthropic.com → API Keys → Create Key (sk-ant-…; vài đô la tín dụng dùng được rất lâu với mức khoảng $0.001 mỗi tin nhắn). Rồi:

git clone https://github.com/sanxiaozi/lingodesk.git cd lingodesk npm install cp .env.example .env # open .env — only BOT_TOKEN and ANTHROPIC_API_KEY are required npm run db:push # initialize the database (first run only) npm run dev 🚀 LingoDesk is up, bot = @my_lingodesk_bot

Khi bạn thấy dòng banner, gửi /bind trong nhóm console để liên kết (ID nhóm và ID người dùng của bạn được tự động nhận diện — không phải tra con số nào). Trên máy chủ, Docker chỉ một lệnh: docker compose up -d — xem GitHub README.

Một token bot = một phiên bản đang chạy, trên toàn cầu (409 Conflict = một tiến trình cũ vẫn đang giữ nó). Nếu chúng tôi lưu trữ giúp bạn, đừng chạy thêm một phiên bản cục bộ.

5Thử trò chuyện

Từ một tài khoản Telegram khác (tài khoản thứ hai hoặc của một người bạn), gửi một tin nhắn riêng bằng ngoại ngữ đến tài khoản cá nhân của bạn (không phải cho bot!) — chẳng hạn "Hola, ¿cuánto cuesta?" bằng tiếng Tây Ban Nha. Trong vài giây, một chủ đề mới mang tên người gửi sẽ xuất hiện trong nhóm console của bạn:

📋 LingoDesk Console · chủ đề: @amigo_es
my_lingodesk_bot🆕 Liên hệ mới @amigo_es (es)
Bản gốc: Hola, ¿cuánto cuesta?
🌐 Chào bạn, giá bao nhiêu vậy?
─────
↳ Gõ vào đây bằng ngôn ngữ của bạn — nó được gửi đi bằng es, dưới danh nghĩa chính bạn
Gói A giá $100 và bao gồm mọi tính năng.
my_lingodesk_bot📤 Xem trước bản dịch (→es), chỉ gửi sau khi bạn xác nhận:

El paquete A cuesta 100 dólares e incluye todas las funciones.

(Tin nhắn của bạn: Package A is $100…)

[ ✅ Gửi cho khách hàng ] [ ✏️ Hủy ]

Chạm "✅ Gửi cho khách hàng" — phía bên kia thấy tài khoản cá nhân của bạn trả lời bằng tiếng Tây Ban Nha lưu loát. Cả vòng lặp giờ đã chạy 🎉

🔧 Khắc phục sự cố

Khách hàng nhắn cho tôi nhưng chẳng thấy gì hiện trong nhóm console

Kiểm tra theo thứ tự: ① BotFather → Business Mode đã bật (Bước 1a); ② Telegram Business → Chatbots đã liên kết bot của bạn và cuộc trò chuyện đó nằm trong phạm vi (Bước 2); ③ bot là quản trị viên nhóm với quyền "Manage Topics" (Bước 3); ④ nhóm console đã được liên kết — gửi /bind trong đó; ⑤ với người tự lưu trữ: tiến trình bot vẫn đang chạy không lỗi.

Cửa sổ bật lên khi thêm bot: "This bot doesn't support Telegram Business yet"

Business Mode chưa được bật trong BotFather (Bước 1a). Vào @BotFather → /mybots → chọn bot của bạn → Bot Settings → Business Mode → Turn on. Nó có hiệu lực tức thì — không cần tạo lại bot hay gửi lại token; chỉ việc quay lại Telegram Business → Chatbots và thêm lại. Người dùng lưu trữ đám mây có thể nhắn @LingoDeskbot /status để kiểm tra lại mục này.

Tôi gửi /bind trong nhóm mà chẳng có gì xảy ra

① Group Privacy vẫn còn bật (Bước 1b) — hãy tắt nó, rồi xóa và thêm lại bot; ② Topics chưa được bật trên nhóm; ③ người dùng lưu trữ đám mây: đảm bảo @LingoDeskbot đã trả lời "Activated" (nhắn /status để kiểm tra); ④ người tự lưu trữ: đảm bảo tiến trình đang chạy.

Giao BOT_TOKEN của tôi cho dịch vụ lưu trữ đám mây có an toàn không?

Token được lưu trữ dạng mã hóa và chỉ dùng để chuyển tiếp các cuộc trò chuyện trong phạm vi bạn đã cho phép trong Telegram Business — và bạn có thể loại trừ các liên hệ riêng tư (Bước 2). Bạn luôn nắm quyền: thu hồi nó bất cứ lúc nào qua BotFather → /mybots → API Token → Revoke; token cũ chết ngay lập tức và dịch vụ dừng lại. Muốn tiếp tục, chỉ cần gửi token mới cho @LingoDeskbot.

Tôi gõ trong một chủ đề mà bot chẳng làm gì

Chín trên mười trường hợp là do Group Privacy vẫn còn bật (Bước 1b). BotFather → Bot Settings → Group Privacy → Turn off, rồi xóa bot khỏi nhóm và thêm lại (thay đổi chỉ áp dụng sau khi bot tham gia lại), và thăng nó lên admin một lần nữa.

Khởi động thất bại với 409 Conflict

Có hai phiên bản đang chạy trên cùng một token. Tìm và dừng tiến trình cũ (Ctrl+C hoặc pkill -f "tsx.*main.ts"), chờ mười giây, rồi khởi động lại.

"Gửi cho khách hàng" thất bại với một lỗi chung chung

Kiểm tra theo thứ tự khả năng: ① quyền "Reply to messages" đang tắt (phổ biến nhất) — Settings → Telegram Business → Chat Automation (Chatbots) → chọn bot của bạn → bật "Reply to messages"; không có nó bot có thể đọc nhưng không bao giờ gửi; ② cuộc trò chuyện của khách hàng không nằm trong phạm vi chat mà bot truy cập được (cùng trang đó); ③ liên hệ đã hơn 24 giờ không nhắn cho bạn — Telegram chặn việc bot chủ động gửi; hãy nhờ họ gửi bất cứ gì trước. Người dùng lưu trữ đám mây: nhắn @LingoDeskbot /status — dòng "reply permission" cho bạn câu trả lời trực tiếp.

"Gửi cho khách hàng" thất bại: liên hệ đã im lặng quá lâu

Một hạn chế của Telegram: nếu một cuộc trò chuyện đã ngừng hoạt động quá lâu, bot không thể chủ động thay bạn (BUSINESS_PEER_USAGE_MISSING). Hãy nhờ họ gửi bất cứ gì để kích hoạt lại, hoặc lần này trả lời thủ công từ điện thoại.

Gửi thất bại: business connection invalid

Vào Settings → Telegram Business → Chatbots, xóa và thêm lại bot — hoặc đơn giản chờ tin nhắn tiếp theo của khách hàng, nó cho phép bot tự động bắt được một kết nối mới.

Nhận diện sai ngôn ngữ / muốn một ngôn ngữ đích khác

Ngôn ngữ được khóa cố định ở tin nhắn đầu tiên của liên hệ (để tránh nhảy qua nhảy lại với các đoạn văn ngắn). Gửi /lang code trong chủ đề của liên hệ đó để chỉnh lại, ví dụ /lang pt (tiếng Bồ Đào Nha) hoặc /lang ar (tiếng Ả Rập).

Sau khi khởi động lại, các nút "Gửi / Hủy" cũ ngừng hoạt động

Các bản xem trước đang chờ nằm trong bộ nhớ và hết hạn khi khởi động lại (nút sẽ báo cho bạn biết). Chỉ cần gõ lại câu trả lời của bạn trong chủ đề. Liên hệ và lịch sử trò chuyện nằm trong cơ sở dữ liệu — không mất gì cả.

🎉 Mọi thứ đã chạy chưa?

Từ giờ, khách hàng cứ viết bằng bất kỳ ngôn ngữ nào họ thích — bạn chỉ việc gõ bằng ngôn ngữ của mình. Nếu có gì trục trặc, trước tiên hãy rà qua danh sách khắc phục sự cố ở trên; vẫn kẹt, hãy email cho chúng tôi kèm ảnh chụp lỗi trên terminal.

✉️ [email protected]