快速上手:從零到跑通,一步不漏
預設走雲端託管:只需一部手機、約 10 分鐘,不需要伺服器、不需要寫程式碼。每一步都標註了在哪個介面點什麼,以及最容易踩的雷。
🧾 準備清單
- Telegram Premium 會員 —— Telegram Business 功能(訊息回灌給 bot)是 Premium 專屬,沒有 Premium 整套流程無法運作。
- 一部手機 —— 雲端託管模式(預設)只需要這個:第 1–3 步在手機上完成,把 token 發給我們就開通。
- 僅自行架設需要:Node.js ≥ 20(或 Docker)、Anthropic API Key、一台常開的電腦/伺服器。程式碼免費開源在 GitHub。
1在 BotFather 建立 bot
在 Telegram 搜尋 @BotFather(認明官方藍 V),對話如下:
🤖 BotFather
/newbot
BotFatherAlright, a new bot. How are we going to call it? Please choose a name for your bot.
LingoDesk 助手
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…
- 「名字」隨意,是顯示名;「username」必須全域唯一且以
bot 結尾,被佔用就換一個。
- 最後回覆裡那串
數字:字母 就是 BOT_TOKEN,先複製存好。它等於 bot 的密碼,別發給任何人。
1a. 開啟 Business Mode(必做)
還是在 BotFather 裡:
/mybots→
@my_lingodesk_bot→
Bot Settings→
Business Mode→
Turn on
不開 Business Mode,第 2 步在 Telegram Business 的機器人清單裡根本搜不到你的 bot。這是最常見的卡點。
1b. 關閉 Group Privacy(必做)
/mybots→
@my_lingodesk_bot→
Bot Settings→
Group Privacy→
Turn off
Privacy 預設開啟,開啟狀態下 bot 看不到你在控制台群裡打的中文——表現為「我在話題裡發訊息,bot 毫無反應」。務必關掉(BotFather 會顯示 Privacy mode is disabled 才算成功)。
2在 Telegram Business 裡綁定 bot
用手機版 Telegram(此設定目前只在手機端有):
⚙️ 設定→
💼 Telegram Business→
🤖 聊天機器人 Chatbots
- 在搜尋框輸入你的 bot username(如
my_lingodesk_bot),點選它。
- 權限:把「回覆訊息 / Reply to messages」打開——不開的話 bot 只能看不能替你發。
- 「哪些聊天」建議選 所有一對一聊天(All 1:1 Chats);不想讓 bot 看到的私人聯絡人,加到排除清單(Excluded Chats)即可。
綁定成功後,你私訊裡收到的每條訊息都會靜默「抄送」給 bot——對方完全無感知,你手機上的聊天體驗也沒有任何變化。
3建立控制台論壇群
這個群是你的工作台:每個客戶一個話題(Topic),雙語卡片都彈在這裡。
- 建立群組:Telegram 裡點新增 → 建立群組,成員就選你的 bot(搜 username 能搜到),群名隨意,比如「LingoDesk 控制台」。
- 開啟話題:進群 → 點群名進資料頁 → 編輯 → 找到「話題 Topics」→ 打開。群會自動升級為超級群,介面變成左側話題清單。
- 把 bot 提為管理員:資料頁 → 管理員 → 新增管理員 → 選你的 bot → 勾選「管理話題 Manage Topics」(其餘預設即可)→ 儲存。
bot 要為每個客戶自動建立話題,沒有管理員的「管理話題」權限就會失敗——表現為「客戶發訊息了,群裡卻什麼都不彈」。
這個群只有你和 bot,不用拉任何真人。想加合夥人一起盯也可以,TA 在話題裡打中文同樣能觸發翻譯發送。
4二選一:☁️ 雲端託管 或 💻 自行架設
到這裡,手機上的準備已全部完成。接下來選一條路——沒有伺服器就選 A,什麼都不用裝。
☁️ 方式 A · 雲端託管(推薦:無需伺服器、無需程式碼)
- 把第 1 步拿到的 BOT_TOKEN 發給我們:點此一鍵產生開通郵件(範本已備好,貼上 token 傳送即可)。
- 我們在 24 小時內為你開通並郵件回覆確認。內測期免費,翻譯引擎也由我們提供,不用申請任何 API Key。
- 收到確認後,在你的控制台群裡發一句
/bind —— bot 回覆「✅ 已綁定」,全部完成,直接跳到第 5 步試聊。
擔心 token 交出去不安全?token 只被用於收發你在 Business 裡授權的會話;你隨時可以在 BotFather 裡(/mybots → API Token → Revoke)重設它,舊 token 立即失效,主動權始終在你手裡。
💻 方式 B · 自行架設(自己的電腦/伺服器,資料完全自持)
先去 console.anthropic.com → API Keys → Create Key 拿一個 sk-ant-…(翻譯引擎;Billing 儲值幾美元,一條譯文約 $0.001,夠用很久)。然後:
git clone https://github.com/sanxiaozi/lingodesk.git
cd lingodesk
npm install
cp .env.example .env # 打開 .env,只需填 BOT_TOKEN 和 ANTHROPIC_API_KEY 兩行
npm run db:push # 初始化資料庫(僅首次)
npm run dev
🚀 LingoDesk 已启动,bot = @my_lingodesk_bot
看到啟動橫幅後,在控制台群裡發一句 /bind 完成綁定(群 ID、你的使用者 ID 全部自動辨識,不用再查任何數字)。伺服器上推薦 Docker:docker compose up -d,詳見 GitHub README。
同一個 bot token 全球只能有一個實例在跑(報 409 Conflict = 有舊程序沒停)。已開通雲端託管的話,就不要再自己啟動本機實例。
5試聊驗證
找一個別的 Telegram 帳號(分身帳號或朋友),用外語私訊你的真人帳號(不是私訊 bot!),比如發一句西語「Hola, ¿cuánto cuesta?」。控制台群裡應該幾秒內彈出一個以對方命名的新話題:
📋 LingoDesk 控制台 · 話題:@amigo_es
my_lingodesk_bot🆕新客戶 @amigo_es(es)
原文:Hola, ¿cuánto cuesta?
🇨🇳 你好,多少錢?
─────
↳ 本話題內打中文,自動譯 es 以你名義發出
套餐 A 是 100 美元,包含全部功能。
my_lingodesk_bot📤 譯文預覽(→es),確認後才發給客戶:
El paquete A cuesta 100 dólares e incluye todas las funciones.
(你的中文:套餐 A 是 100 美元…)
[ ✅ 傳送給客戶 ] [ ✏️ 取消 ]
點「✅ 傳送給客戶」,對方會看到你的真人帳號用流利西語回覆了 TA。到這裡,整條鏈路就通了 🎉
- 對方發圖片/檔案/語音 → 自動轉進話題並存檔。
- 語種辨識錯了?在話題裡發
/lang es 手動糾正,發 /help 看全部指令。
- 你在手機上直接手動回覆客戶也沒問題,bot 會把它記錄進話題存檔。
🔧 常見問題排查
客戶發訊息了,控制台群什麼都不彈
按順序檢查:① BotFather 裡 Business Mode 是否 Turn on(第 1a 步);② Telegram Business → Chatbots 是否綁定了 bot、該聊天是否在涵蓋範圍內(第 2 步);③ bot 是否是群管理員且有「管理話題」權限(第 3 步);④ 控制台群是否已綁定 —— 在群裡發一句 /bind;⑤ 自行架設使用者:終端機裡 bot 是否還在跑、有無報錯。
在群裡發 /bind,bot 沒反應
① Group Privacy 沒關(第 1b 步),關掉後把 bot 踢出群重新拉進來;② 群還沒開啟「話題(Topics)」;③ 雲端託管使用者:確認已收到我們的開通郵件(開通前 bot 還沒執行);④ 自行架設使用者:確認終端機裡 bot 正在執行。
雲端託管要交出 BOT_TOKEN,安全嗎?
token 只被用來收發你在 Telegram Business 裡授權範圍內的會話,你也可以把私人聯絡人加入排除清單(第 2 步)。主動權在你:任何時候去 BotFather → /mybots → API Token → Revoke 重設,舊 token 立即失效,服務即刻中斷。停用前發郵件告知一聲即可。
我在話題裡打中文,bot 沒反應
九成是 Group Privacy 沒關(第 1b 步)。去 BotFather → Bot Settings → Group Privacy → Turn off,然後把 bot 踢出群再重新拉進來(權限變更需要重進群才生效),重新設為管理員。
啟動報 409 Conflict
同一 token 有兩個實例在跑。找到並停掉舊程序(Ctrl+C 或 pkill -f "tsx.*main.ts"),等十秒再啟動。
點「傳送給客戶」報錯:客戶太久沒往來
Telegram 限制:太久沒互動的對話,bot 不能替你主動發起(報 BUSINESS_PEER_USAGE_MISSING)。讓對方先隨便發一句啟用,或這一次你在手機上手動回。
傳送報錯:Business 連線失效
去 設定 → Telegram Business → Chatbots 裡把 bot 移除再重新加入,或讓客戶發條新訊息——bot 會自動捕獲新的連線並恢復。
翻譯語種不對 / 想換目標語言
語種在客戶第一條訊息時鎖定(避免短訊息誤判來回跳)。在該客戶的話題裡發 /lang 語種碼 即可糾正,如 /lang pt(葡語)、/lang ar(阿語)。
bot 重啟後,之前的「傳送/取消」按鈕點了沒反應
待確認的譯文預覽存在記憶體裡,重啟會失效(按鈕會提示)。在話題裡把中文重新打一遍即可。客戶映射和聊天紀錄都在資料庫裡,不會丟。