AiHummer
Español▾
Iniciar sesiónCuenta
v1.6.x▾
{ }Swagger

Telegram

v1.6.x · actualizada 2026-11-11

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.

  1. 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 gustar 123456789:AA… — esta es la clave de acceso del bot, cópiala.
  2. 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).
  3. 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.
  4. Crear un agente (si aún no tienes uno) — ver Agentes: un nombre y una indicación del sistema son suficientes.
  5. 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.
  6. 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_URL y 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 Modelos Modelos
  • “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?

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.

Bot API 10.4