快速上手:从零到跑通,一步不落
照着做即可,全程约 15 分钟。每一步都标注了在哪个界面点什么,以及最容易踩的坑。
🧾 准备清单
- Telegram Premium 会员 —— Telegram Business 功能(消息回灌给 bot)是 Premium 专属,没有 Premium 整套流程无法工作。
- Node.js 20 或更高 —— 终端跑
node -v 确认;没有就去 nodejs.org 装 LTS 版。
- Anthropic API Key —— 翻译引擎。第 4 步教你申请;可选再备一个 OpenAI Key 做兜底。
- LingoDesk 代码目录 —— 内测阶段由我们提供,解压/克隆到本地即可。
- 一台常开的电脑 —— bot 进程要一直跑着才能收发(后面可迁到服务器)。
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获取三个 ID / Key
4a. ANTHROPIC_API_KEY(翻译引擎)
- 打开
console.anthropic.com,注册/登录。
- 左侧 API Keys → Create Key → 复制那串
sk-ant-…(只显示一次,存好)。
- Billing 里充值几美元即可——默认用 Haiku 模型,一条译文成本约 $0.001,几美元够用很久。
4b. 先把代码跑起来第一步:装依赖 + 填 BOT_TOKEN
终端进入 LingoDesk 目录:
cd lingodesk
npm install
cp .env.example .env
用任意编辑器打开 .env,先只填一行:BOT_TOKEN=第 1 步拿到的 token,保存。
4c. FORUM_CHAT_ID 和 OWNER_USER_ID:一条命令拿到
- 在控制台群里随便发一句(比如「测试」)。
- 用你自己的账号私聊 bot(搜它 username),发一句
/start。
- 回到终端:
npm run ids
── 群/会话(supergroup 且 -100 开头的那行 = FORUM_CHAT_ID)──
-1002345678901 supergroup · LingoDesk 控制台
── 用户(你自己那行 = OWNER_USER_ID)──
712345678 Jason @your_username
两个高亮的数字就是要填的值。如果输出是「(空)」,说明那两条消息还没发,发完重跑;如果报 409,说明 bot 正在运行,先停掉再跑。
5填写 .env
把 .env 填完整(其余行保持默认即可):
# 必填四项
BOT_TOKEN=8123456789:AAHfK3xxxxxxxxxxxxxxxxxxxxxxxxx
FORUM_CHAT_ID=-1002345678901
OWNER_USER_ID=712345678
ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxx
# 可选:OpenAI 兜底(Claude 偶发故障时自动切换,建议填)
OPENAI_API_KEY=sk-xxxxxxxx
FORUM_CHAT_ID 带负号,整串照抄(包括 -100 前缀)。OWNER_USER_ID 一定要填:bot 靠它区分「客户发来的」和「你自己手动回的」,不填会把你的手动回复当客户消息处理。
6启动
npm run db:push
🚀 Your database is now in sync with your Prisma schema.
npm run dev
────────────────────────────────────────
🚀 LingoDesk 已启动,bot = @my_lingodesk_bot
收→译→回→译 跨语言沟通中继:
· 客户私聊你真人号 → 自动译中 + 在控制台 Topic 弹双语卡片
· 你在 Topic 内打中文 → 预览确认 → 译客户语,以你名义发出
────────────────────────────────────────
看到这个横幅就说明起来了。第一次跑 db:push 是初始化本地数据库,以后不用再跑。
同一个 bot token 全球只能有一个实例在跑。如果报 409 Conflict,说明还有另一个进程占着(比如上次没关干净),全部停掉再启动。
7试聊验证
找一个别的 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 步);④ 终端里 bot 是否还在跑、有无报错。
我在话题里打中文,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 重启后,之前的「发送/取消」按钮点了没反应
待确认的译文预览存在内存里,重启会失效(按钮会提示)。在话题里把中文重新打一遍即可。客户映射和聊天记录都在数据库里,不会丢。