Integración de Clawdbot con Telegram

Descripción General de la Integración de Clawdbot con Telegram

La integración de Clawdbot con Telegram te permite conectar tu asistente de IA personal a Telegram usando la Bot API a través de grammY. Está listo para producción en DMs de bots y grupos, con long-polling por defecto y soporte opcional de webhook.

¿Por Qué Usar Clawdbot con Telegram?

Telegram ofrece potentes APIs de bots y funciones de privacidad. Integrar Clawdbot con Telegram proporciona:

Configuración Rápida (Principiante)

1. Crea un bot con @BotFather (enlace directo)
2. Confirma que el handle es exactamente @BotFather, luego copia el token
3. Configura el token vía env (TELEGRAM_BOT_TOKEN=...) o config (channels.telegram.botToken)
4. Inicia la puerta de enlace
5. El acceso por DM es por emparejamiento por defecto; aprueba el código de emparejamiento en el primer contacto

Configuración mínima:

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

Configurando Clawdbot Telegram

Requisitos Previos

Antes de conectar Clawdbot a Telegram, asegúrate de tener:

• Clawdbot instalado en tu dispositivo
• Una cuenta de Telegram
• Un Token de Bot de Telegram de @BotFather

Paso 1: Crear un Bot de Telegram

Crea un bot a través del BotFather de Telegram:

1. Abre Telegram y chatea con @BotFather (enlace directo)
2. Confirma que el handle es exactamente @BotFather
3. Ejecuta /newbot, luego sigue las indicaciones (nombre + nombre de usuario terminando en bot)
4. Copia el token y guárdalo de forma segura

Configuraciones opcionales de BotFather:

• /setjoingroups — permitir/denegar agregar el bot a grupos
• /setprivacy — controlar si el bot ve todos los mensajes del grupo

Paso 2: Configurar el Token

Configura el token vía variable de entorno o config:

Variable de entorno:

TELEGRAM_BOT_TOKEN=123:abc

Archivo de configuración (~/.clawdbot/clawdbot.json):

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

Si tanto env como config están configurados, config tiene prioridad.

Paso 3: Iniciar la Puerta de Enlace

clawdbot gateway --port 18789

Telegram inicia cuando se resuelve un token (config primero, env como respaldo).

Paso 4: Verificar Conexión

Verifica el estado de tu Clawdbot Telegram:

clawdbot channels status telegram

Token + Privacidad + Permisos

Creación de Token (BotFather)

• /newbot crea el bot y devuelve el token (mantenlo secreto)
• Si un token se filtra, revócalo/regenera vía @BotFather y actualiza tu config

Visibilidad de Mensajes de Grupo (Modo Privacidad)

Los bots de Telegram por defecto están en Modo Privacidad, que limita qué mensajes de grupo reciben. Opciones:

1. Deshabilita el modo privacidad con /setprivacy
2. Agrega el bot como administrador del grupo (los bots admin reciben todos los mensajes)

Nota: Cuando activas/desactivas el modo privacidad, Telegram requiere remover + re-agregar el bot a cada grupo para que el cambio tome efecto.

Permisos de Grupo (Derechos de Admin)

El estado de admin se establece dentro del grupo (UI de Telegram). Los bots admin siempre reciben todos los mensajes del grupo.

Características de Clawdbot Telegram

Cómo Funciona

• Los mensajes entrantes se normalizan en el sobre de canal compartido con contexto de respuesta y marcadores de posición de medios
• Las respuestas de grupo requieren una mención por defecto (@mención nativa o patrones configurados)
• Las respuestas siempre se enrutan de vuelta al mismo chat de Telegram
• Long-polling usa grammY runner con secuenciación por chat

Streaming de Borradores

Clawdbot puede transmitir respuestas parciales en DMs de Telegram usando sendMessageDraft.

Requisitos:

• Modo Threading habilitado para el bot en @BotFather (modo de tema de foro)
• Solo hilos de chat privado
• channels.telegram.streamMode no establecido en "off"

El streaming de borradores es solo para DM; Telegram no lo soporta en grupos o canales.

Formateo (Telegram HTML)

• El texto saliente de Telegram usa parse_mode: "HTML"
• La entrada tipo Markdown se renderiza en HTML seguro para Telegram
• El HTML raw de modelos se escapa para evitar errores de parseo de Telegram

Comandos

Clawdbot Telegram soporta comandos personalizados:

Configuración de Clawdbot Telegram

Ejemplo de Configuración Completa

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

Control de Acceso (DMs + Grupos)

Acceso DM:

• dmPolicy: "pairing" — Los remitentes desconocidos obtienen un código de emparejamiento; aprobar con CLI
• dmPolicy: "allowlist" — Solo responder a usuarios en la lista permitida
• dmPolicy: "open" — Responder a todos (no recomendado)

Acceso a Grupos:

• Configura channels.telegram.groups con clave por id de grupo o "*" para todos los grupos
• Usa requireMention: true para solo responder cuando se menciona

Encontrar tu ID de Usuario de Telegram

Usa @userinfobot o bots similares para obtener tu ID numérico de usuario de Telegram.

Almacenamiento de Credenciales de Clawdbot Telegram

Clawdbot almacena las credenciales de Telegram de forma segura:

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

Tus datos de Clawdbot Telegram permanecen en tu máquina local.

Solución de Problemas de Clawdbot Telegram

Bot No Responde

Si tu bot Clawdbot Telegram no responde:

1. Verifica el token: clawdbot channels verify telegram
2. Verifica el estado del bot con @BotFather
3. Revisa los registros: cat /tmp/clawdbot/telegram.log

Activación de Grupo

Para activar Clawdbot en un grupo:

Vía config (recomendado):

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

Vía comando (nivel de sesión): Usa /activate en el chat del grupo.

Obtener el ID del Chat de Grupo

Reenvía un mensaje del grupo a @userinfobot o usa la API de Telegram.

Mejores Prácticas de Clawdbot Telegram

1. Usa el Modo de Emparejamiento: Seguro por defecto con códigos de emparejamiento
2. Configura el Modo de Privacidad: Configura en @BotFather según tus necesidades
3. Maneja Límites de Tasa: Implementa límites de tasa apropiados
4. Monitorea el Uso: Rastrea analíticas del bot Clawdbot Telegram

Próximos Pasos

• Integración de Clawdbot con WhatsApp - Conecta Clawdbot a WhatsApp
• Integración de Clawdbot con Discord - Configura Clawdbot en Discord
• Guía de Configuración de Clawdbot - Guía de instalación completa