Быстрый старт: с нуля до запуска, без пропущенных шагов

Путь по умолчанию — облачный хостинг: только телефон и ~10 минут — без сервера, без кода. На каждом шаге указано, какой экран открыть и что нажать, а также ловушки, на которые реально попадаются.

Содержание Чек-лист Шаг 1 · Создайте бота в BotFather (два критичных переключателя) Шаг 2 · Привяжите бота в Telegram Business Шаг 3 · Создайте форум-группу консоли Шаг 4 · Выберите одно: ☁️ Облако (рекомендуется) / 💻 Свой сервер Шаг 5 · Тестовый чат Устранение неполадок

🧾 Чек-лист

1Создайте бота в BotFather

В Telegram найдите @BotFather (ищите синий значок верификации) и проведите такой диалог:

🤖 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…

1a. Включите Secretary Mode (обязательно; ранее «Business Mode»)

⚠️ В мае 2026 Telegram переименовал этот переключатель в Secretary Mode; старые клиенты могут по-прежнему называть его Business Mode — это одно и то же. Делайте это внутри чата с @BotFather (не на странице профиля вашего бота и не в настройках Telegram на телефоне). Два интерфейса — подойдёт любой:

Интерфейс ① Классические команды — просто отправляйте сообщения:

/mybots→ @my_lingodesk_bot→ Bot Settings→ Secretary Mode→ Turn on

Интерфейс ② Новая панель управления — нажмите синюю кнопку Open рядом с полем ввода BotFather:

Open (панель)→ выберите своего бота→ Settings→ Mode Settings→ включите Secretary Mode
Не можете найти? ① У переключателя два названия: Secretary Mode в новых клиентах и Business Mode в старых — ищите любое; ② убедитесь, что вы внутри @BotFather, а не в настройках собственного бота; ③ переключатель никак не связан с Telegram Premium — Premium важен только для привязки на стороне вашего аккаунта на шаге 2; включить его может кто угодно.
Без Secretary Mode Telegram покажет всплывающее окно — «This bot doesn't support Telegram Business yet» — при попытке добавить бота на шаге 2. Это самая частая причина затыка. Переключите тумблер: он срабатывает мгновенно, пересоздавать бота не нужно; просто попробуйте добавить снова.

1b. Отключите Group Privacy (обязательно)

/mybots→ @my_lingodesk_bot→ Bot Settings→ Group Privacy→ Turn off
Privacy включён по умолчанию, и пока он включён, бот не видит ответы, которые вы печатаете в группе-консоли — симптом: «печатаю в теме, и ничего не происходит». Отключите его (BotFather должен ответить Privacy mode is disabled).

2Привяжите бота в Telegram Business

В мобильном приложении Telegram (эта настройка сейчас есть только на мобильном):

⚙️ Настройки→ 💼 Telegram Business→ 🤖 Чат-боты

В новых клиентах этот пункт называется «Chat Automation» — другая надпись, тот же вход.

  1. Введите username вашего бота (например, my_lingodesk_bot) в поле поиска и выберите его.
  2. Разрешения: включите «Reply to messages» — без этого бот может читать, но никогда не сможет отправлять от вашего имени.
  3. Для «каких чатов» выберите All 1:1 Chats; добавьте любые личные контакты, которые хотите оставить вне ретрансляции, в список Excluded Chats.
После привязки каждое личное сообщение, которое вы получаете, тихо «дублируется» боту — собеседник ничего не замечает, а ваш собственный опыт переписки вообще не меняется.

3Создайте форум-группу консоли

Эта группа — ваш рабочий стол: по одной теме на контакт, внутри которых всплывают двуязычные карточки сообщений.

  1. Создайте группу: New → New Group, добавьте своего бота единственным участником (найдите по username). Назовите как угодно, например «LingoDesk Console».
  2. Включите Topics: откройте группу → нажмите на название для профиля → Edit → включите Topics. Группа станет супергруппой и получит список тем.
  3. Назначьте бота администратором: профиль → Administrators → Add Admin → ваш бот → отметьте «Manage Topics» (остальное оставьте по умолчанию) → сохраните.
Бот автоматически создаёт тему для каждого контакта. Без прав администратора и «Manage Topics» это не сработает — симптом: «клиент мне написал, но в группе ничего не появилось».
В группе нужны только вы и бот — других людей не требуется. Если вы добавите партнёра, его ответы в теме тоже вызывают перевод и отправку, как и ваши.

4Выберите одно: ☁️ Облако или 💻 Свой сервер

Всё на стороне телефона сделано. Теперь выберите путь — нет сервера? Выбирайте вариант A: ничего устанавливать не нужно.

☁️ Вариант A · Облако (рекомендуется: без сервера, без кода, мгновенно)

  1. Напишите официальному боту активации @LingoDeskbot, отправьте /start, затем вставьте BOT_TOKEN из шага 1 прямо в чат.
  2. Мгновенная автоматическая активация: как только токен проверится, он ответит «🎉 Activated» (и удалит сообщение с вашим токеном). Бесплатный тариф покрывает 300 переведённых ответов/месяц; перейдите на Pro (500 ⭐/мес) в любой момент для безлимита. Переводчик — за наш счёт, никаких API-ключей регистрировать не нужно.
  3. Следуйте его ответу, чтобы завершить привязку, затем отправьте /bind в вашей группе-консоли — бот ответит «✅ bound», и готово. Переходите к шагу 5 для теста. Напишите ему /status в любой момент или /native en, чтобы задать свой язык.
Переживаете из-за передачи токена? Он хранится в зашифрованном виде и используется только для ретрансляции чатов, которые вы разрешили в Telegram Business — и контроль остаётся у вас: отзовите его в любой момент в BotFather (/mybots → API Token → Revoke), и старый токен мгновенно умрёт.

💻 Вариант B · Свой сервер (ваша машина, ваши данные)

Сначала получите ключ для перевода на console.anthropic.com → API Keys → Create Key (sk-ant-…; нескольких долларов кредита хватает надолго при ~$0,001 за сообщение). Затем:

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

Как только увидите баннер, отправьте /bind в вашей группе-консоли, чтобы привязать её (ID группы и ваш ID пользователя определяются автоматически — никаких чисел искать не нужно). На сервере Docker — это одна команда: docker compose up -d — смотрите README на GitHub.

Один токен бота = один запущенный экземпляр во всём мире (409 Conflict = старый процесс всё ещё держит его). Если хостинг у нас, не запускайте параллельно локальный экземпляр.

5Тестовый чат

С другого аккаунта Telegram (второй аккаунт или друг) отправьте личное сообщение на иностранном языке в ваш личный аккаунт (не боту!) — например, «Hola, ¿cuánto cuesta?» по-испански. За считанные секунды в вашей группе-консоли должна появиться новая тема с именем отправителя:

📋 LingoDesk Console · тема: @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…)

[ ✅ Отправить клиенту ] [ ✏️ Отмена ]

Нажмите «✅ Отправить клиенту» — собеседник видит, как ваш личный аккаунт отвечает на беглом испанском. Весь цикл теперь работает 🎉

🔧 Устранение неполадок

Клиент мне написал, но в группе-консоли ничего не появилось

Проверьте по порядку: ① BotFather → Business Mode включён (шаг 1a); ② Telegram Business → Chatbots: ваш бот привязан и этот чат в области действия (шаг 2); ③ бот — администратор группы с «Manage Topics» (шаг 3); ④ группа-консоль привязана — отправьте в ней /bind; ⑤ для своего сервера: процесс бота ещё работает без ошибок.

Всплывающее окно при добавлении бота: «This bot doesn't support Telegram Business yet»

Business Mode не включён в BotFather (шаг 1a). Зайдите в @BotFather → /mybots → ваш бот → Bot Settings → Business Mode → Turn on. Срабатывает мгновенно — пересоздавать бота или заново отправлять токен не нужно; просто вернитесь в Telegram Business → Chatbots и добавьте его снова. Пользователи облака могут написать @LingoDeskbot /status, чтобы перепроверить этот пункт.

Отправляю /bind в группе, и ничего не происходит

① Group Privacy всё ещё включён (шаг 1b) — отключите его, затем удалите и заново добавьте бота; ② Topics не включены в группе; ③ пользователи облака: убедитесь, что @LingoDeskbot ответил «Activated» (напишите ему /status для проверки); ④ для своего сервера: убедитесь, что процесс запущен.

Безопасно ли передавать мой BOT_TOKEN для облачного хостинга?

Токен хранится в зашифрованном виде и используется только для ретрансляции чатов в пределах области, которую вы разрешили в Telegram Business, — и вы можете исключить личные контакты (шаг 2). Контроль остаётся у вас: отзовите токен в любой момент через BotFather → /mybots → API Token → Revoke; старый токен мгновенно умрёт, и сервис остановится. Чтобы возобновить, просто отправьте новый токен @LingoDeskbot.

Печатаю в теме, а бот ничего не делает

В девяти случаях из десяти это всё ещё включённый Group Privacy (шаг 1b). BotFather → Bot Settings → Group Privacy → Turn off, затем удалите бота из группы и добавьте его заново (изменение вступает в силу только после повторного входа) и снова назначьте администратором.

Запуск падает с ошибкой 409 Conflict

На одном токене запущены два экземпляра. Найдите и остановите старый процесс (Ctrl+C или pkill -f "tsx.*main.ts"), подождите десять секунд, запустите снова.

«Отправить клиенту» падает с общей ошибкой

Проверьте по порядку вероятности: ① отключено разрешение «Reply to messages» (самое частое) — Settings → Telegram Business → Chat Automation (Chatbots) → ваш бот → включите «Reply to messages»; без него бот может читать, но никогда не отправит; ② чат клиента вне области доступных боту чатов (та же страница); ③ контакт не писал вам более 24 часов — Telegram блокирует отправки по инициативе бота; попросите его сначала прислать что-нибудь. Пользователи облака: напишите @LingoDeskbot /status — строка «reply permission» сразу даст ответ.

«Отправить клиенту» падает: контакт слишком долго неактивен

Ограничение Telegram: если разговор простаивал слишком долго, бот не может инициировать отправку от вашего имени (BUSINESS_PEER_USAGE_MISSING). Попросите собеседника прислать что-нибудь для повторной активации или ответьте вручную с телефона в этот раз.

Отправка не удалась: business connection invalid

Зайдите в Settings → Telegram Business → Chatbots, удалите и заново добавьте бота — или просто дождитесь следующего сообщения клиента, которое позволит боту автоматически захватить свежее соединение.

Определился не тот язык / хочу другой целевой язык

Язык фиксируется на первом сообщении контакта (чтобы не скакать на коротких текстах). Отправьте /lang code в теме этого контакта, чтобы поправить, например /lang pt (португальский) или /lang ar (арабский).

После перезапуска старые кнопки «Отправить / Отмена» перестали работать

Ожидающие предпросмотры живут в памяти и истекают при перезапуске (кнопка сообщит об этом). Просто напишите ответ в теме заново. Контакты и история переписки хранятся в базе данных — ничего не теряется.

🎉 Всё работает?

Отныне клиенты пишут на любом удобном им языке — а вы просто печатаете на своём. Если что-то сломалось, сначала пройдитесь по списку устранения неполадок выше; если всё ещё не выходит — напишите нам письмо со скриншотом ошибки в терминале.

✉️ [email protected]