快速上手:從零到跑通,一步不漏

預設走雲端託管:只需一部手機、約 10 分鐘,不需要伺服器、不需要寫程式碼。每一步都標註了在哪個介面點什麼,以及最容易踩的雷。

目錄 準備清單 第 1 步 · 在 BotFather 建立 bot(含兩個關鍵開關) 第 2 步 · 在 Telegram Business 裡綁定 bot 第 3 步 · 建立控制台論壇群 第 4 步 · 二選一:☁️ 雲端託管(推薦) / 💻 自行架設 第 5 步 · 試聊驗證 常見問題排查

🧾 準備清單

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…

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
  1. 在搜尋框輸入你的 bot username(如 my_lingodesk_bot),點選它。
  2. 權限:把「回覆訊息 / Reply to messages」打開——不開的話 bot 只能看不能替你發。
  3. 「哪些聊天」建議選 所有一對一聊天(All 1:1 Chats);不想讓 bot 看到的私人聯絡人,加到排除清單(Excluded Chats)即可。
綁定成功後,你私訊裡收到的每條訊息都會靜默「抄送」給 bot——對方完全無感知,你手機上的聊天體驗也沒有任何變化。

3建立控制台論壇群

這個群是你的工作台:每個客戶一個話題(Topic),雙語卡片都彈在這裡。

  1. 建立群組:Telegram 裡點新增 → 建立群組,成員就選你的 bot(搜 username 能搜到),群名隨意,比如「LingoDesk 控制台」。
  2. 開啟話題:進群 → 點群名進資料頁 → 編輯 → 找到「話題 Topics」→ 打開。群會自動升級為超級群,介面變成左側話題清單。
  3. 把 bot 提為管理員:資料頁 → 管理員 → 新增管理員 → 選你的 bot → 勾選「管理話題 Manage Topics」(其餘預設即可)→ 儲存。
bot 要為每個客戶自動建立話題,沒有管理員的「管理話題」權限就會失敗——表現為「客戶發訊息了,群裡卻什麼都不彈」。
這個群只有你和 bot,不用拉任何真人。想加合夥人一起盯也可以,TA 在話題裡打中文同樣能觸發翻譯發送。

4二選一:☁️ 雲端託管 或 💻 自行架設

到這裡,手機上的準備已全部完成。接下來選一條路——沒有伺服器就選 A,什麼都不用裝。

☁️ 方式 A · 雲端託管(推薦:無需伺服器、無需程式碼)

  1. 把第 1 步拿到的 BOT_TOKEN 發給我們:點此一鍵產生開通郵件(範本已備好,貼上 token 傳送即可)。
  2. 我們在 24 小時內為你開通並郵件回覆確認。內測期免費,翻譯引擎也由我們提供,不用申請任何 API Key。
  3. 收到確認後,在你的控制台群裡發一句 /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。到這裡,整條鏈路就通了 🎉

🔧 常見問題排查

客戶發訊息了,控制台群什麼都不彈

按順序檢查:① 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 重啟後,之前的「傳送/取消」按鈕點了沒反應

待確認的譯文預覽存在記憶體裡,重啟會失效(按鈕會提示)。在話題裡把中文重新打一遍即可。客戶映射和聊天紀錄都在資料庫裡,不會丟。

🎉 跑通了?

現在起,客戶用任何語言私訊你,你只管打中文。遇到問題先看上面的排查清單,沒解決就寫郵件給我們,附上終端機報錯截圖。

✉️ [email protected]