Quick start: from zero to running, no steps skipped
The default path is cloud-hosted: just a phone and ~10 minutes — no server, no code. Every step tells you which screen to open and what to tap, plus the pitfalls people actually hit.
Check first: this guide needs Telegram Premium. The invisible relay configured on this page runs on Telegram Business — a Premium-only feature. No Premium? Skip this guide entirely: message @LingoDeskbot and send /free — group live interpreting, inline translation and the bot-front console all work for free.
🧾 Checklist
- Telegram Premium — the Telegram Business features LingoDesk relies on (message relay to a bot) are Premium-only. Without Premium none of this works.
- A phone — that's all the cloud-hosted mode (the default) needs: do Steps 1–3 on your phone, send us the token, done.
- Self-hosting only: Node.js ≥ 20 (or Docker), an Anthropic API key, and an always-on computer/server. The code is free and open source on GitHub.
1Create your bot in BotFather
In Telegram, search for @BotFather (look for the blue verification badge) and have this conversation:
🤖 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…
- The "name" is just a display name; the "username" must be globally unique and end in
bot — if taken, try another.
- That
digits:letters string in the last reply is your BOT_TOKEN. Copy it somewhere safe. It is effectively the bot's password — never share it.
1a. Turn on Secretary Mode (required; formerly "Business Mode")
⚠️ In May 2026 Telegram renamed this switch to Secretary Mode; older clients may still label it Business Mode — same thing. Do this inside the @BotFather chat (not your bot's profile page, and not your phone's Telegram settings). Two interfaces — either works:
Interface ① Classic commands — just send messages:
/mybots→
@my_lingodesk_bot→
Bot Settings→
Secretary Mode→
Turn on
Interface ② New management panel — tap the blue Open button next to BotFather's message box:
Open (panel)→
pick your bot→
Settings→
Mode Settings→
toggle Secretary Mode on
Can't find it? ① It has two names: Secretary Mode in new clients, Business Mode in older ones — look for either; ② make sure you're inside @BotFather, not your own bot's settings; ③ the toggle has nothing to do with Telegram Premium — Premium only matters for linking on your account side in Step 2; anyone can flip this switch.
Without Secretary Mode, Telegram shows a popup — "This bot doesn't support Telegram Business yet" — when you try to add it in Step 2. It's the single most common blocker. Flip the switch: it takes effect instantly, no need to recreate the bot; just retry adding it.
1b. Turn off Group Privacy (required)
/mybots→
@my_lingodesk_bot→
Bot Settings→
Group Privacy→
Turn off
Privacy is on by default, and while it's on the bot cannot see the replies you type in your console group — the symptom is "I type in the topic and nothing happens". Turn it off (BotFather must say Privacy mode is disabled).
2Link the bot in Telegram Business
On the mobile Telegram app (this setting currently exists only on mobile):
⚙️ Settings→
💼 Telegram Business→
🤖 Chatbots
In newer clients this item is called "Chat Automation" — different label, same entry.
- Type your bot's username (e.g.
my_lingodesk_bot) in the search box and select it.
- Permissions: enable "Reply to messages" — without it the bot can read but can never send on your behalf.
- For "which chats", choose All 1:1 Chats; add any private contacts you want to keep out of the relay to the Excluded Chats list.
Once linked, every private message you receive is silently "cc'd" to the bot — the other side notices nothing, and your own chat experience doesn't change at all.
3Create your console forum group
This group is your workbench: one topic per contact, with bilingual message cards popping up inside.
- Create a group: New → New Group, add your bot as the only member (search its username). Name it anything, e.g. "LingoDesk Console".
- Enable Topics: open the group → tap the name for its profile → Edit → toggle Topics on. The group upgrades to a supergroup and gets a topic list.
- Promote the bot to admin: profile → Administrators → Add Admin → your bot → check "Manage Topics" (leave the rest default) → save.
The bot creates a topic automatically for each contact. Without admin rights + "Manage Topics" that fails — the symptom is "a customer wrote to me but nothing appears in the group".
The group only needs you and the bot — no other humans. If you add a partner, their replies in a topic trigger translation and sending just like yours.
4Pick one: ☁️ Cloud-hosted or 💻 Self-host
Everything on the phone side is done. Now choose your path — no server? Pick A: nothing to install.
☁️ Option A · Cloud-hosted (recommended: no server, no code, instant)
- DM the official activation bot @LingoDeskbot, send
/start, then paste the BOT_TOKEN from Step 1 right into the chat.
- Instant automatic activation: once the token validates it replies "🎉 Activated" (and deletes your token message). The Free plan covers 300 translated replies/month; upgrade to Pro (500 ⭐/mo) anytime for unlimited. Translation engine is on us — no API keys to sign up for.
- Follow its reply to finish linking, then send
/bind in your console group — the bot replies "✅ bound" and you're done. Jump to Step 5 to test. DM it /status any time, or /native en to set your own language.
Worried about handing over the token? It's stored encrypted and only used to relay the chats you authorized in Telegram Business — and you stay in control: revoke it any time in BotFather (/mybots → API Token → Revoke) and the old token dies instantly.
💻 Option B · Self-host (your own machine, your own data)
First grab a translation key at console.anthropic.com → API Keys → Create Key (sk-ant-…; a few dollars of credit lasts a long time at ~$0.001 per message). Then:
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
Once you see the banner, send /bind in your console group to link it (group ID and your user ID are detected automatically — no numbers to look up). On a server, Docker is one command: docker compose up -d — see the GitHub README.
One bot token = one running instance, globally (409 Conflict = an old process is still holding it). If we host you, don't also run a local instance.
5Test chat
From a different Telegram account (a second account or a friend), send a foreign-language DM to your personal account (not to the bot!) — say, "Hola, ¿cuánto cuesta?" in Spanish. Within seconds, a new topic named after the sender should appear in your console group:
📋 LingoDesk Console · topic: @amigo_es
my_lingodesk_bot🆕 New contact @amigo_es (es)
Original: Hola, ¿cuánto cuesta?
🌐 Hi, how much does it cost?
─────
↳ Type here in your language — it goes out in es, sent as you
Package A is $100 and includes all features.
my_lingodesk_bot📤 Translation preview (→es), sent only after you confirm:
El paquete A cuesta 100 dólares e incluye todas las funciones.
(Your message: Package A is $100…)
[ ✅ Send to customer ] [ ✏️ Cancel ]
Tap "✅ Send to customer" — the other side sees your personal account replying in fluent Spanish. The whole loop is now live 🎉
- Photos, files and voice messages they send are forwarded into the topic and archived automatically.
- Wrong language detected? Send
/lang es in the topic to correct it; /help lists all commands.
- Replying manually from your phone is fine too — the bot records it into the topic archive.
- You can start conversations too — no need to wait for them. Message anyone from your real account (even just "hi") and they instantly appear in the console with a topic created; from then on, type in your language here to keep chatting with them.
🔧 Troubleshooting
A customer wrote to me but nothing appears in the console group
Check in order: ① BotFather → Business Mode is turned on (Step 1a); ② Telegram Business → Chatbots has your bot linked and that chat is within scope (Step 2); ③ the bot is a group admin with "Manage Topics" (Step 3); ④ the console group is bound — send /bind in it; ⑤ self-hosters: the bot process is still running without errors.
Popup when adding the bot: "This bot doesn't support Telegram Business yet"
Business Mode isn't enabled in BotFather (Step 1a). Go to @BotFather → /mybots → your bot → Bot Settings → Business Mode → Turn on. It takes effect instantly — no need to recreate the bot or resubmit the token; just go back to Telegram Business → Chatbots and add it again. Cloud-hosted users can DM @LingoDeskbot /status to double-check this item.
I send /bind in the group and nothing happens
① Group Privacy is still on (Step 1b) — turn it off, then remove and re-add the bot; ② Topics aren't enabled on the group; ③ cloud-hosted users: make sure @LingoDeskbot replied "Activated" (DM it /status to check); ④ self-hosters: make sure the process is running.
Is it safe to hand over my BOT_TOKEN for cloud hosting?
The token is stored encrypted and only used to relay chats within the scope you authorized in Telegram Business — and you can exclude private contacts (Step 2). You stay in control: revoke it any time via BotFather → /mybots → API Token → Revoke; the old token dies instantly and the service stops. To resume, just send the new token to @LingoDeskbot.
I type in a topic and the bot does nothing
Nine times out of ten it's Group Privacy still on (Step 1b). BotFather → Bot Settings → Group Privacy → Turn off, then remove the bot from the group and re-add it (the change only applies after rejoining), and promote it to admin again.
Startup fails with 409 Conflict
Two instances are running on the same token. Find and stop the old process (Ctrl+C or pkill -f "tsx.*main.ts"), wait ten seconds, start again.
"Send to customer" fails with a generic error
Check in order of likelihood: ① the "Reply to messages" permission is off (most common) — Settings → Telegram Business → Chat Automation (Chatbots) → your bot → enable "Reply to messages"; without it the bot can read but never send; ② the customer's chat isn't within the bot's accessible-chats scope (same page); ③ the contact hasn't messaged you in over 24 hours — Telegram blocks bot-initiated sends; ask them to send anything first. Cloud-hosted users: DM @LingoDeskbot /status — the "reply permission" line gives you the answer directly.
"Send to customer" fails: contact inactive too long
A Telegram restriction: if a conversation has been idle too long, the bot can't initiate on your behalf (BUSINESS_PEER_USAGE_MISSING). Ask them to send anything to reactivate, or reply manually from your phone this once.
Send fails: business connection invalid
Go to Settings → Telegram Business → Chatbots, remove and re-add the bot — or simply wait for the customer's next message, which lets the bot capture a fresh connection automatically.
Wrong language detected / want a different target language
The language locks on the contact's first message (to avoid flip-flopping on short texts). Send /lang code in that contact's topic to correct it, e.g. /lang pt (Portuguese) or /lang ar (Arabic).
After a restart, old "Send / Cancel" buttons stopped working
Pending previews live in memory and expire on restart (the button will tell you). Just type your reply again in the topic. Contacts and chat history live in the database — nothing is lost.
🎉 All working?
From now on, customers write in whatever language they like — you just type in yours. If something breaks, run through the troubleshooting list above first; still stuck, email us with a screenshot of the terminal error.
✉️ [email protected]