Integração com Telegram — configuração e uso

Um bot por projeto. Cada AI-worker recebe seu próprio tópico em um Supergroup do Telegram — as mensagens são roteadas automaticamente para o worker certo e a resposta volta no mesmo tópico.

Como fica na prática

Supergroup "My Project"
├── 📌 General          ← chat geral (sem vínculo)
├── 🔵 Developer        ← mensagens → worker Developer
└── 🟢 Consultant       ← mensagens → worker Consultant

Você escreve no tópico Developer → o Arc OS processa via Claude → a resposta aparece no mesmo tópico.

Telegram e CRM Dashboard são dois canais para o mesmo worker. Você pode começar o diálogo no Telegram e continuar no CRM — o contexto é preservado.

Configuração

Passo 1 — Criar o bot no BotFather

1. Abra o @BotFather no Telegram
2. Envie /newbot
3. Digite o nome do bot (por exemplo: My Project)
4. Digite o username — precisa terminar em bot (por exemplo: my_project_arc_bot)
5. O BotFather retornará um token no formato 123456789:AABBccDDee...

⚠️ Guarde o token — você vai precisar dele na configuração do CRM.

Passo 2 — Criar um Supergroup com Topics

2.1 Criar o grupo

Telegram Desktop / Mobile:

1. Toque no ícone do lápis → New Group
2. Adicione qualquer participante (pode remover depois)
3. Dê um nome ao grupo → Create

2.2 Habilitar Topics

1. Abra as configurações do grupo (toque no nome no topo)
2. Edit → encontre a seção Topics
3. Ative o interruptor — o Telegram converte o grupo automaticamente em Supergroup

2.3 Descobrir o Supergroup ID

O Supergroup ID sempre começa com -100.

Opção A — via @userinfobot:

1. Encaminhe qualquer mensagem do grupo para o bot @userinfobot
2. O bot retornará o ID no formato -1001234567890

Opção B — via Telegram Web:

1. Abra o grupo em web.telegram.org
2. Na barra de endereço haverá uma URL do tipo #-1001234567890
3. Copie o número junto com o sinal de menos

Passo 3 — Adicionar o bot como administrador

1. Abra as configurações do grupo → Administrators
2. Add Admin → na busca, digite @username_do_seu_bot (username completo com @)
3. Selecione o bot na lista → OK
4. As permissões padrão servem — deixe como está

⚠️ O bot não aparecerá na busca se você digitar o username incompleto ou sem @. Digite o @username exato.

Passo 4 — Criar tópicos para os workers

No grupo, toque em + → New Topic:

• Nomeie os tópicos conforme os workers: Developer, Consultant, ou nomes personalizados
• Você pode escolher cores/ícones para facilitar

Passo 5 — Conectar no CRM

1. Abra arc-os.co → escolha o projeto → Project Settings
2. Encontre a seção Channels → clique em Connect Telegram

5.1 Inserir os dados do bot

Clique em Verify & get topics.

5.2 Verificação

O CRM vai checar:

• ✅ Token válido
• ✅ O bot é administrador do grupo
• ✅ Lista de tópicos carregada

5.3 Vincular tópicos aos workers

Para cada tópico, escolha um worker no dropdown:

Developer  →  [developer     ▾]
Consultant →  [consultant    ▾]
General    →  [(não vinculado)]

Clique em Save bindings.

Passo 6 — Teste

1. Escreva qualquer mensagem no tópico Developer
2. O bot responderá no mesmo tópico, como worker Developer
3. Repita para o Consultant

Uso no dia a dia

Trabalho via tópicos (recomendado)

Basta escrever o texto da tarefa no tópico certo — nenhum prefixo é necessário:

[Tópico Developer]
Corrija o bug no formulário de login — o campo email não está sendo validado

[Tópico Consultant]
Analise a arquitetura do módulo de auth, o que dá para melhorar?

Se o tópico não estiver vinculado a um worker — responde o worker padrão.

Comandos no chat privado com o bot

No chat privado com o bot há troca manual de workers via prefixos:

Exemplos:

/c Analise a arquitetura do módulo de auth
/d Corrija o bug no formulário de login
/w:sentinel Faça um security audit das últimas mudanças

Mensagem sem prefixo vai para o worker ativo atual — depois de /d Corrija o bug, as próximas mensagens sem prefixo também irão para o Developer.

Botões inline abaixo da resposta

Após cada resposta do AI-worker, aparecem botões de controle:

Controle do processo:

Contexto e feedback:

Navegação:

Contexto e memória

• Cada worker tem memória separada (até 50 mensagens)
• Reply em uma mensagem → o texto dela é adicionado como contexto da requisição
• O Context Router seleciona automaticamente as top-5 skills relevantes para a sua mensagem
• Feedback 👎 → o sistema memoriza o erro e o leva em conta nas próximas requisições

Comandos de controle do bot

Conexão com o CRM Dashboard

Tópico Telegram ──┐
                  ├──► Child Bot ──► Claude ──► Resposta
CRM Dashboard   ──┘                              │
                                                 ▼
                                        Telegram + CRM (simultaneamente)

• Mensagens do CRM são processadas a cada 500ms
• As respostas aparecem ao mesmo tempo no Telegram e no CRM
• Anexos (imagens, PDF) são suportados via CRM Dashboard
• Você pode começar o diálogo no Telegram e continuar no CRM — o contexto é preservado

Desconectando o bot

CRM → Project Settings → Channels → Disconnect.

Isso remove o token e todos os vínculos de tópicos. O bot permanece no grupo — remova-o dos administradores manualmente, se necessário.

Solução de problemas