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.
🧾 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 Business Mode (required)
Still inside BotFather:
/mybots→
@my_lingodesk_bot→
Bot Settings→
Business Mode→
Turn on
Without Business Mode your bot won't even show up in the Telegram Business chatbot list in Step 2. This is the single most common blocker.
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
- 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 beta is free, and the 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.
🔧 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.
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: 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]