Início rápido: do zero ao funcionamento, sem pular nenhum passo

O caminho padrão é hospedado na nuvem: só um celular e ~10 minutos — sem servidor, sem código. Cada passo diz qual tela abrir e onde tocar, além das armadilhas que as pessoas realmente encontram.

Conteúdo Checklist Passo 1 · Crie seu bot no BotFather (duas chaves críticas) Passo 2 · Vincule o bot no Telegram Business Passo 3 · Crie seu grupo de fórum do console Passo 4 · Escolha um: ☁️ Hospedado na nuvem (recomendado) / 💻 Auto-hospedado Passo 5 · Teste de conversa Solução de problemas

🧾 Checklist

1Crie seu bot no BotFather

No Telegram, procure por @BotFather (busque o selo azul de verificação) e tenha esta conversa:

🤖 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. Ative o Secretary Mode (obrigatório; antigo "Business Mode")

⚠️ Em maio de 2026 o Telegram renomeou esta chave para Secretary Mode; clientes mais antigos ainda podem exibi-la como Business Mode — é a mesma coisa. Faça isso dentro do chat com @BotFather (não na página de perfil do seu bot, nem nas configurações do Telegram no seu celular). Duas interfaces — qualquer uma funciona:

Interface ① Comandos clássicos — basta enviar mensagens:

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

Interface ② Novo painel de gerenciamento — toque no botão azul Open ao lado da caixa de mensagem do BotFather:

Open (painel)→ escolha seu bot→ Settings→ Mode Settings→ ative o Secretary Mode
Não consegue encontrar? ① Ele tem dois nomes: Secretary Mode nos clientes novos, Business Mode nos antigos — procure por qualquer um; ② confirme que você está dentro do @BotFather, não nas configurações do seu próprio bot; ③ a chave não tem nada a ver com o Telegram Premium — o Premium só importa para vincular no lado da sua conta no Passo 2; qualquer pessoa pode acionar essa chave.
Sem o Secretary Mode, o Telegram mostra um pop-up — "This bot doesn't support Telegram Business yet" — quando você tenta adicioná-lo no Passo 2. É o bloqueio mais comum de todos. Acione a chave: ela vale na hora, sem precisar recriar o bot; basta tentar adicioná-lo de novo.

1b. Desative o Group Privacy (obrigatório)

/mybots→ @my_lingodesk_bot→ Bot Settings→ Group Privacy→ Turn off
A privacidade vem ativada por padrão e, enquanto estiver ativada, o bot não consegue ver as respostas que você digita no seu grupo de console — o sintoma é "eu digito no tópico e nada acontece". Desative (o BotFather deve dizer Privacy mode is disabled).

2Vincule o bot no Telegram Business

No app mobile do Telegram (esta configuração atualmente existe só no celular):

⚙️ Configurações→ 💼 Telegram Business→ 🤖 Chatbots

Nos clientes mais novos este item chama-se "Chat Automation" — rótulo diferente, mesma entrada.

  1. Digite o username do seu bot (por exemplo, my_lingodesk_bot) na caixa de busca e selecione-o.
  2. Permissões: ative "Reply to messages" — sem isso o bot consegue ler, mas nunca poderá enviar em seu nome.
  3. Em "quais conversas", escolha All 1:1 Chats; adicione à lista de Excluded Chats qualquer contato privado que você queira manter fora do relé.
Uma vez vinculado, cada mensagem privada que você recebe é silenciosamente "copiada" para o bot — o outro lado não percebe nada, e a sua própria experiência de conversa não muda em nada.

3Crie seu grupo de fórum do console

Este grupo é a sua bancada de trabalho: um tópico por contato, com cartões de mensagem bilíngues surgindo dentro dele.

  1. Crie um grupo: Novo → Novo Grupo, adicione seu bot como único membro (busque pelo username dele). Dê qualquer nome, por exemplo "Console do LingoDesk".
  2. Ative os Tópicos: abra o grupo → toque no nome para ver o perfil → Editar → ative Tópicos. O grupo é promovido a supergrupo e ganha uma lista de tópicos.
  3. Promova o bot a administrador: perfil → Administradores → Adicionar Admin → seu bot → marque "Gerenciar Tópicos" (deixe o resto no padrão) → salvar.
O bot cria um tópico automaticamente para cada contato. Sem os direitos de admin + "Gerenciar Tópicos" isso falha — o sintoma é "um cliente me escreveu, mas nada aparece no grupo".
O grupo só precisa de você e do bot — nenhum outro humano. Se você adicionar um parceiro, as respostas dele num tópico disparam a tradução e o envio, exatamente como as suas.

4Escolha um: ☁️ Hospedado na nuvem ou 💻 Auto-hospedado

Tudo do lado do celular está feito. Agora escolha o seu caminho — sem servidor? Escolha o A: nada para instalar.

☁️ Opção A · Hospedado na nuvem (recomendado: sem servidor, sem código, instantâneo)

  1. Mande uma DM para o bot oficial de ativação @LingoDeskbot, envie /start e depois cole o BOT_TOKEN do Passo 1 direto no chat.
  2. Ativação automática instantânea: assim que o token é validado, ele responde "🎉 Activated" (e apaga a mensagem com o seu token). O plano Gratuito cobre 300 respostas traduzidas/mês; faça upgrade para o Pro (500 ⭐/mês) quando quiser para ter ilimitado. O motor de tradução é por nossa conta — sem chaves de API para cadastrar.
  3. Siga a resposta dele para concluir a vinculação, depois envie /bind no seu grupo de console — o bot responde "✅ bound" e pronto. Pule para o Passo 5 para testar. Mande /status por DM a qualquer momento, ou /native pt para definir o seu próprio idioma.
Preocupado em entregar o token? Ele é armazenado criptografado e usado apenas para retransmitir as conversas que você autorizou no Telegram Business — e você mantém o controle: revogue-o a qualquer momento no BotFather (/mybots → API Token → Revoke) e o token antigo morre na hora.

💻 Opção B · Auto-hospedado (sua própria máquina, seus próprios dados)

Primeiro pegue uma chave de tradução em console.anthropic.com → API Keys → Create Key (sk-ant-…; alguns dólares de crédito duram bastante tempo a ~$0,001 por mensagem). Depois:

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

Assim que ver o banner, envie /bind no seu grupo de console para vinculá-lo (o ID do grupo e o seu ID de usuário são detectados automaticamente — nenhum número para procurar). Num servidor, o Docker é um único comando: docker compose up -d — veja o README no GitHub.

Um token de bot = uma instância em execução, globalmente (409 Conflict = um processo antigo ainda está segurando o token). Se hospedarmos você, não rode também uma instância local.

5Teste de conversa

De uma conta diferente do Telegram (uma segunda conta ou um amigo), envie uma DM em língua estrangeira para a sua conta pessoal (não para o bot!) — digamos, "Hola, ¿cuánto cuesta?" em espanhol. Em segundos, um novo tópico com o nome do remetente deve aparecer no seu grupo de console:

📋 Console do LingoDesk · tópico: @amigo_es
my_lingodesk_bot🆕 Novo contato @amigo_es (es)
Original: Hola, ¿cuánto cuesta?
🌐 Olá, quanto custa?
─────
↳ Digite aqui no seu idioma — sai em es, enviado como você
O Pacote A custa $100 e inclui todos os recursos.
my_lingodesk_bot📤 Prévia da tradução (→es), enviada só depois que você confirmar:

El paquete A cuesta 100 dólares e incluye todas las funciones.

(Sua mensagem: O Pacote A custa $100…)

[ ✅ Enviar ao cliente ] [ ✏️ Cancelar ]

Toque em "✅ Enviar ao cliente" — o outro lado vê a sua conta pessoal respondendo em espanhol fluente. Todo o ciclo está no ar agora 🎉

🔧 Solução de problemas

Um cliente me escreveu, mas nada aparece no grupo de console

Verifique nesta ordem: ① BotFather → Business Mode está ativado (Passo 1a); ② Telegram Business → Chatbots tem o seu bot vinculado e aquela conversa está dentro do escopo (Passo 2); ③ o bot é administrador do grupo com "Gerenciar Tópicos" (Passo 3); ④ o grupo de console está vinculado — envie /bind nele; ⑤ para auto-hospedados: o processo do bot ainda está rodando sem erros.

Pop-up ao adicionar o bot: "This bot doesn't support Telegram Business yet"

O Business Mode não está ativado no BotFather (Passo 1a). Vá em @BotFather → /mybots → seu bot → Bot Settings → Business Mode → Turn on. Ele vale na hora, instantaneamente — sem precisar recriar o bot ou reenviar o token; basta voltar ao Telegram Business → Chatbots e adicioná-lo de novo. Usuários hospedados na nuvem podem mandar /status por DM para @LingoDeskbot para conferir este item.

Eu envio /bind no grupo e nada acontece

① O Group Privacy ainda está ativado (Passo 1b) — desative, depois remova e adicione o bot de novo; ② os Tópicos não estão ativados no grupo; ③ usuários hospedados na nuvem: confirme que o @LingoDeskbot respondeu "Activated" (mande /status por DM para verificar); ④ auto-hospedados: confirme que o processo está rodando.

É seguro entregar o meu BOT_TOKEN para a hospedagem na nuvem?

O token é armazenado criptografado e usado apenas para retransmitir conversas dentro do escopo que você autorizou no Telegram Business — e você pode excluir contatos privados (Passo 2). Você mantém o controle: revogue-o a qualquer momento pelo BotFather → /mybots → API Token → Revoke; o token antigo morre na hora e o serviço para. Para retomar, basta enviar o novo token para @LingoDeskbot.

Eu digito num tópico e o bot não faz nada

Nove em cada dez vezes é o Group Privacy ainda ativado (Passo 1b). BotFather → Bot Settings → Group Privacy → Turn off, depois remova o bot do grupo e adicione-o de novo (a mudança só vale após reentrar) e promova-o a administrador novamente.

A inicialização falha com 409 Conflict

Duas instâncias estão rodando com o mesmo token. Encontre e pare o processo antigo (Ctrl+C ou pkill -f "tsx.*main.ts"), espere dez segundos e inicie de novo.

"Enviar ao cliente" falha com um erro genérico

Verifique por ordem de probabilidade: ① a permissão "Reply to messages" está desativada (a mais comum) — Configurações → Telegram Business → Chat Automation (Chatbots) → seu bot → ative "Reply to messages"; sem isso o bot consegue ler, mas nunca enviar; ② a conversa do cliente não está dentro do escopo de conversas acessíveis ao bot (mesma página); ③ o contato não te manda mensagem há mais de 24 horas — o Telegram bloqueia envios iniciados por bot; peça para ele enviar qualquer coisa primeiro. Usuários hospedados na nuvem: mande /status por DM para @LingoDeskbot — a linha "reply permission" te dá a resposta na hora.

"Enviar ao cliente" falha: contato inativo há tempo demais

Uma restrição do Telegram: se uma conversa ficou parada tempo demais, o bot não consegue iniciar em seu nome (BUSINESS_PEER_USAGE_MISSING). Peça para o contato enviar qualquer coisa para reativar, ou responda manualmente pelo celular desta vez.

O envio falha: conexão de negócios inválida

Vá em Configurações → Telegram Business → Chatbots, remova e adicione o bot de novo — ou simplesmente espere a próxima mensagem do cliente, que permite ao bot capturar uma conexão nova automaticamente.

Idioma detectado errado / quero um idioma de destino diferente

O idioma é fixado na primeira mensagem do contato (para evitar oscilações em textos curtos). Envie /lang código no tópico daquele contato para corrigir, por exemplo /lang pt (português) ou /lang ar (árabe).

Depois de reiniciar, os botões antigos de "Enviar / Cancelar" pararam de funcionar

As prévias pendentes ficam na memória e expiram ao reiniciar (o botão vai te avisar). Basta digitar a sua resposta de novo no tópico. Contatos e histórico de conversa ficam no banco de dados — nada é perdido.

🎉 Tudo funcionando?

De agora em diante, os clientes escrevem no idioma que quiserem — você só digita no seu. Se algo quebrar, percorra primeiro a lista de solução de problemas acima; se ainda estiver travado, envie um e-mail com uma captura de tela do erro do terminal.

✉️ [email protected]