Integración de grammY para Telegram Bot API

Gestionar bots de Telegram puede ser frustrante cuando tienes que lidiar con fetch manual y errores de FormData para enviar archivos. Si buscas una forma estable de manejar rate limits y tipos de media sin complicaciones, grammY es la mejor opción disponible.

Te recomiendo usar grammY porque es un cliente de Bot API enfocado en TypeScript que ya incluye herramientas para long-poll, webhooks y middleware. Olvídate de construir peticiones a mano; este cliente es más limpio y soporta todos los métodos de la Bot API de forma nativa.

What You’ll Need

Para poner en marcha esta integración, necesitas tener listos estos parámetros de configuración:

• channels.telegram.botToken (obtenido de BotFather)
• channels.telegram.dmPolicy y channels.telegram.groups
• channels.telegram.webhookUrl y channels.telegram.webhookSecret (si planeas usar webhooks)
• channels.telegram.proxy (opcional, si usas undici.ProxyAgent)

Quick Start

Sigue estos pasos para configurar grammY como tu único cliente de Telegram en menos de 5 minutos:

1. Configura el Token: Añade tu botToken en la configuración. grammY ahora es el único cliente encargado tanto de los envíos como del Gateway, eliminando la implementación basada en fetch.
2. Define el Modo de Conexión: El Gateway detectará automáticamente cómo conectarse. Si defines webhookUrl y webhookSecret, activará el modo webhook usando webhookCallback. Si no los defines, usará long-polling por defecto.
3. Establece las Políticas de Chat: Configura dmPolicy para chats privados y groups para definir el allowlist y las menciones en grupos. El sistema colapsará los chats directos en la sesión principal del agente (agent:<agentId>:<mainKey>), mientras que los grupos usarán una sesión específica por chatId.
4. Activa el Throttler: No necesitas hacer nada extra; el throttler de grammY viene activado por defecto para gestionar los límites de velocidad de la API de Telegram.

Troubleshooting

Si encuentras problemas durante la implementación, revisa estos puntos basados en los reportes de integración:

• Errores 429 (Too Many Requests): Aunque el throttler está activo por defecto, podrías alcanzar límites si envías ráfagas masivas. Estamos evaluando plugins adicionales de grammY para casos extremos.
• Puerto del Webhook: Actualmente, el puerto para escuchar webhooks está fijado en 8787. Asegúrate de que tu infraestructura no bloquee este puerto si no lo estás enviando a través del Gateway.
• Media y Archivos: Si tienes problemas descargando archivos, el Gateway utiliza getFile y download. Verifica que el tamaño no exceda lo configurado en channels.telegram.mediaMaxMb.
• Streaming de Borradores: Si streamMode no funciona, asegúrate de estar usando una versión de Bot API 9.3 o superior en chats privados.

Para resolver dudas específicas sobre tu configuración, consulta al AI Setup Assistant.

What’s Next

• Configuración avanzada de channels.telegram.proxy mediante undici
• Gestión de sesiones y agentId en canales de Telegram