Telegram
Telegram es el canal recomendado de AiHummer para producción. Es la forma más rápida de poner un agente funcional frente a personas reales: crear un bot con @BotFather, da al conector el token, y los mensajes entrantes comenzarán a fluir hacia la puerta de enlace.
El conector de Telegram se instala desde el producto Mercado y configurado en la interfaz de administración. Se ejecuta de manera nativa en el host y se comunica con la puerta de enlace a través de la API entrante, por lo que escala y se reinicia de manera independiente del motor de turnos.
Conectar Telegram en 6 pasos
Aquí está el camino de principio a fin desde cero hasta un bot que te responde en Telegram. Todo lo que necesitas es una cuenta de Telegram y acceso a tu interfaz de administración web de AiHummer.
- Crea un bot con BotFather. Abrir en Telegram
@BotFather, enviar
/newbot, y configura el nombre del bot y nombre de usuario. Lo que verás: BotFather devuelve un ficha gustar123456789:AA…— esta es la clave de acceso del bot, cópiala. - Instala el conector de Telegram. En la interfaz de administración, abrir Complementos/Mercado, encuentra el conector de Telegram en el catálogo y haga clic en “Instalar”. Espere a que la tarjeta se ponga “en línea” (una instalación se muestra la barra de progreso).
- Pega el token. Ve a la Canales pantalla → la Configurar canales instalados bloquear, abrir la tarjeta de Telegram y pegar el token de bot en el campo desde el formulario del conector. Guardar.
- Crear un agente (si aún no tienes uno) — ver Agentes: un nombre y una indicación del sistema son suficientes.
- Vincula el agente al canal. En el Canales pantalla, en la Enlaces bloquear, elegir un agente predeterminado para Telegram — el regla “las nuevas conversaciones de Telegram son manejadas por el agente Y”. La elección se guarda al instante.
- Envía un mensaje al bot. Abre tu bot en Telegram y envíale un mensaje. Qué verás: el agente responde en el chat, y aparece la conversación correspondiente en la pantalla “Sesiones” en la interfaz de administración.
[!NOTE] Por defecto, el agente responde solo usuarios conocidos (personas registradas en AiHummer). Si el bot permanece en silencio ante tu mensaje, agréguete a ti mismo como un usuario de la instancia, o desactivar “Responder solo a usuarios conocidos” en el Canales pantalla.
Por qué empezar con Telegram
Telegram tiene la menor fricción de cualquier canal de AiHummer: no hay operador, no hay pantalla de consentimiento OAuth, no hay revisión de la aplicación. Un token de bot es suficiente para enviar y recibir mensajes, y el mismo conector cubre tanto los chats internos del personal como los bots orientados al cliente. Debido a que es de nivel de producción y plenamente ejercido, es el canal que recomendamos conectar primero al evaluar AiHummer.
Encuestas o webhook
El conector admite ambos modos de ingestión, por lo que funciona tanto si su puerta de enlace es accesible desde Internet público como si no.
- Sondeo prolongado — el conector obtiene actualizaciones de Telegram. No hay puerto de entrada o se requiere TLS, lo que lo hace ideal para el desarrollo local y privado redes.
- Webhook — Telegram envía actualizaciones a una URL pública HTTPS. Menor latencia y mejor adecuado para la producción detrás de un proxy inverso que termina TLS.
El conector escucha en puerto 8800 en un despliegue normal, o 8091 para una ejecución local. Cada mensaje entrante se publica en la URL del gateway configurada en AIHUMMER_INBOUND_URL, autenticado con el secreto compartido de entrada.
Mensajes enriquecidos, reacciones de mensajes y encuestas
Más allá del texto plano, el canal de Telegram muestra Mensajes enriquecidos — respuestas formateadas que asignan la salida estructurada de un agente a las funciones de mensaje nativas de Telegram. También admite reacciones de mensajes y encuestas, para que un agente pueda reaccionar al mensaje de un usuario o poner una encuesta rápida en un chat como parte de un turno.
[!TIP] Telegram es el canal identificado para AiHummer como
telegram. Usa ese canal ID cuando vinculas un agente o filtras conversaciones por fuente.
Comportamiento en grupos y reacciones (conector 1.0.2)
Core 1.3 fija el conector de Telegram firmado 1.0.2: procesa las reacciones a los mensajes, transmite al núcleo el remitente correcto de los callbacks de botones y ha recibido ajustes de comportamiento en grupos. Todos están en la tarjeta del conector (pantalla «Canales» → «Configurar canales instalados»):
| Ajuste | Qué hace |
|---|---|
TELEGRAM_REQUIRE_MENTION |
En grupos, responder solo a los mensajes que @mencionan al bot (desactivado por defecto). |
TELEGRAM_GROUP_HISTORY_LIMIT / TELEGRAM_DM_HISTORY_LIMIT |
Cuántos mensajes del grupo o del chat privado (0–500) entran en el contexto del agente; 0 — según la política del agente. |
TELEGRAM_GROUP_ACK_REACTION |
Reacción emoji que el bot pone en un mensaje dirigido a él en un grupo; vacío — ninguna. |
TELEGRAM_FORWARD_REACTIONS |
Transmitir al núcleo las reacciones entrantes de los usuarios como eventos. |
TELEGRAM_GUEST_MODE |
Modo invitado: responder en cualquier chat, no solo a usuarios conocidos. |
TELEGRAM_ALLOW_BOT_TO_BOT |
Permitir intercambios con otros bots (con protección contra bucles). |
TELEGRAM_STREAMING |
Mostrar la respuesta a medida que se genera (activado por defecto). |
TELEGRAM_RICH_MESSAGES |
Rich Messages nativos (activado por defecto). |
Para que el bot vea los mensajes del grupo, en BotFather debe estar desactivado
el modo de privacidad (/setprivacy → Disable); de lo contrario, guarda
silencio.
Bot a bot con un guardia de bucle
Los agentes pueden hablar con otros bots. Para que eso sea seguro, el conector envía un protector de bucle: detecta y rompe los intercambios fuera de control entre bots antes de que se conviertan en un ping-pong infinito. Esto te permite componer flujos de trabajo con múltiples bots sin el clásico modo de fallo por bucle de retroalimentación.
Corretaje secreto sobre OIDC
El token del bot y otros secretos del conector nunca se codifican directamente en el servicio. En su lugar, el conector los obtiene en tiempo de ejecución desde un Servicio de secretos sobre OIDC — se autentica, luego recupera las credenciales que necesita. Los secretos permanecen en la bóveda encriptada y fuera de los archivos de configuración y de los argumentos del proceso.
[!NOTE] Los mensajes entrantes se publican en
AIHUMMER_INBOUND_URLy asegurado por el secreto HMAC compartido de entrada (AIHUMMER_INBOUND_SECRET). La puerta de enlace debe tener una espacio de trabajo predeterminado configurado para enviarlos.
Si no funcionó
- El conector de Telegram no está en la pantalla de “Canales” — instálalo primero en la Complementos/Mercado pantalla; hasta que esté instalada el canal no se muestra. Community incluye Telegram y MAX.
- El bot no responde — comprobar: (1) que el token esté pegado correctamente y el La tarjeta de Telegram está “en línea”; (2) el canal está vinculado a un agente en “Vínculos”; (3) el remitente está registrado en el sistema (por defecto el agente solo responde usuarios conocidos).
- Si no hay un proveedor configurado, aparece el error:
Aún no hay ningún proveedor de modelo de IA configurado; agregue uno en la sección ModelosModelos - “No autorizado” / token rechazado — el token es incorrecto o ha sido revocado; genera un
nuevo con @BotFather (
/token) y pégalo de nuevo. - El webhook no llega — en modo webhook, la pasarela debe ser accesible en una URL pública HTTPS; en una red privada usa sondeo largo, que no necesita entrada puerto o TLS.
¿A dónde vamos ahora?
- Comparar canales en el MÁX, Bitrix24 y Telefonía SIP guías.
- Configuración de enlaces y acceso — Canales.
- Para fuentes no relacionadas con el chat, vea Genérico entrante.
- ¿Construyendo contra la API? Ver chat/completions.
Widgets interactivos de Telegram
El conector Telegram 1.2.0 admite Bot API 10.4 y widgets HTML en chats privados con el bot: hasta 32 KiB UTF-8 y 4 KiB comprimidos. Las consultas mantienen los permisos del usuario actual; los datos de la cartera no son una aprobación. Un rechazo explícito por falta de compatibilidad permite un archivo HTML adjunto normal. Un resultado de entrega incierto no causa un reenvío a ciegas.