Integração do Clawdbot com Telegram

Visão Geral da Integração do Clawdbot com Telegram

A integração do Clawdbot com Telegram permite que você conecte seu assistente de IA pessoal ao Telegram usando a Bot API via grammY. Está pronto para produção em DMs de bots e grupos, com long-polling por padrão e suporte opcional a webhook.

Por Que Usar Clawdbot com Telegram?

O Telegram oferece APIs de bots poderosas e recursos de privacidade. Integrar Clawdbot com Telegram oferece:

Configuração Rápida (Iniciante)

1. Crie um bot com @BotFather (link direto)
2. Confirme que o handle é exatamente @BotFather, então copie o token
3. Configure o token via env (TELEGRAM_BOT_TOKEN=...) ou config (channels.telegram.botToken)
4. Inicie o gateway
5. O acesso por DM é por pareamento por padrão; aprove o código de pareamento no primeiro contato

Configuração mínima:

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "123:abc",
      "dmPolicy": "pairing"
    }
  }
}

Configurando Clawdbot Telegram

Pré-requisitos

Antes de conectar Clawdbot ao Telegram, certifique-se de ter:

• Clawdbot instalado no seu dispositivo
• Uma conta Telegram
• Um Token de Bot do Telegram do @BotFather

Passo 1: Criar um Bot do Telegram

Crie um bot através do BotFather do Telegram:

1. Abra o Telegram e converse com @BotFather (link direto)
2. Confirme que o handle é exatamente @BotFather
3. Execute /newbot, então siga as instruções (nome + nome de usuário terminando em bot)
4. Copie o token e guarde-o com segurança

Configurações opcionais do BotFather:

• /setjoingroups — permitir/negar adicionar o bot a grupos
• /setprivacy — controlar se o bot vê todas as mensagens do grupo

Passo 2: Configurar o Token

Configure o token via variável de ambiente ou config:

Variável de ambiente:

TELEGRAM_BOT_TOKEN=123:abc

Arquivo de configuração (~/.clawdbot/clawdbot.json):

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "123:abc",
      "dmPolicy": "pairing",
      "groups": {
        "*": { "requireMention": true }
      }
    }
  }
}

Se tanto env quanto config estiverem definidos, config tem precedência.

Passo 3: Iniciar o Gateway

clawdbot gateway --port 18789

O Telegram inicia quando um token é resolvido (config primeiro, env como fallback).

Passo 4: Verificar Conexão

Verifique o status do seu Clawdbot Telegram:

clawdbot channels status telegram

Token + Privacidade + Permissões

Criação do Token (BotFather)

• /newbot cria o bot e retorna o token (mantenha-o secreto)
• Se um token vazar, revogue/regenere via @BotFather e atualize sua config

Visibilidade de Mensagens de Grupo (Modo de Privacidade)

Bots do Telegram por padrão estão em Modo de Privacidade, que limita quais mensagens de grupo eles recebem. Opções:

1. Desabilite o modo de privacidade com /setprivacy
2. Adicione o bot como admin do grupo (bots admin recebem todas as mensagens)

Nota: Quando você alterna o modo de privacidade, o Telegram requer remover + re-adicionar o bot a cada grupo para a mudança ter efeito.

Permissões de Grupo (Direitos de Admin)

O status de admin é definido dentro do grupo (UI do Telegram). Bots admin sempre recebem todas as mensagens do grupo.

Recursos do Clawdbot Telegram

Como Funciona

• Mensagens de entrada são normalizadas no envelope de canal compartilhado com contexto de resposta e placeholders de mídia
• Respostas de grupo requerem uma menção por padrão (@menção nativa ou padrões configurados)
• Respostas sempre são roteadas de volta para o mesmo chat do Telegram
• Long-polling usa grammY runner com sequenciamento por chat

Streaming de Rascunhos

Clawdbot pode transmitir respostas parciais em DMs do Telegram usando sendMessageDraft.

Requisitos:

• Modo Threaded habilitado para o bot no @BotFather (modo de tópico de fórum)
• Apenas threads de chat privado
• channels.telegram.streamMode não definido como "off"

O streaming de rascunhos é apenas para DM; o Telegram não suporta em grupos ou canais.

Formatação (Telegram HTML)

• Texto de saída do Telegram usa parse_mode: "HTML"
• Entrada tipo Markdown é renderizada em HTML seguro para Telegram
• HTML bruto de modelos é escapado para evitar erros de parse do Telegram

Comandos

Clawdbot Telegram suporta comandos personalizados:

Configuração do Clawdbot Telegram

Exemplo de Configuração Completa

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "123:abc",
      "dmPolicy": "pairing",
      "groups": {
        "*": { "requireMention": true }
      }
    }
  }
}

Controle de Acesso (DMs + Grupos)

Acesso DM:

• dmPolicy: "pairing" — Remetentes desconhecidos recebem um código de pareamento; aprove com CLI
• dmPolicy: "allowlist" — Responder apenas a usuários na allowlist
• dmPolicy: "open" — Responder a todos (não recomendado)

Acesso a Grupos:

• Configure channels.telegram.groups com chave por id de grupo ou "*" para todos os grupos
• Use requireMention: true para responder apenas quando mencionado

Encontrando seu ID de Usuário do Telegram

Use @userinfobot ou bots similares para obter seu ID numérico de usuário do Telegram.

Armazenamento de Credenciais do Clawdbot Telegram

Clawdbot armazena credenciais do Telegram de forma segura:

~/.clawdbot/credentials/telegram/bot_token
~/.clawdbot/credentials/telegram/session.json

Seus dados do Clawdbot Telegram permanecem na sua máquina local.

Solução de Problemas do Clawdbot Telegram

Bot Não Responde

Se seu bot Clawdbot Telegram não responde:

1. Verifique o token: clawdbot channels verify telegram
2. Verifique o status do bot com @BotFather
3. Revise os logs: cat /tmp/clawdbot/telegram.log

Ativação de Grupo

Para ativar Clawdbot em um grupo:

Via config (recomendado):

{
  "channels": {
    "telegram": {
      "groups": {
        "<group_id>": { "requireMention": true }
      }
    }
  }
}

Via comando (nível de sessão): Use /activate no chat do grupo.

Obtendo o ID do Chat de Grupo

Encaminhe uma mensagem do grupo para @userinfobot ou use a API do Telegram.

Melhores Práticas do Clawdbot Telegram

1. Use o Modo de Pareamento: Seguro por padrão com códigos de pareamento
2. Configure o Modo de Privacidade: Configure no @BotFather baseado em suas necessidades
3. Trate Limites de Taxa: Implemente limitação de taxa adequada
4. Monitore o Uso: Rastreie análises do bot Clawdbot Telegram

Próximos Passos

• Integração do Clawdbot com WhatsApp - Conecte Clawdbot ao WhatsApp
• Integração do Clawdbot com Discord - Configure Clawdbot no Discord
• Guia de Configuração do Clawdbot - Guia de instalação completo