Telegram

Objetivo

Conecta un bot de Telegram para que un agente de IA responda tus conversaciones de Telegram. Telegram es el canal más simple de configurar: no necesita revisión de app ni OAuth — creas un bot con @BotFather y pegas su token. El webhook se registra por ti automáticamente, y los tokens se guardan cifrados y no se muestran de nuevo.

Acceso

Sidebar -> Messaging -> Telegram Rutas:

• /app/{tenant}/telegram (conectar y gestionar bots)
• Las conversaciones de Telegram se leen y responden en la bandeja compartida en /app/{tenant}/conversations, filtrada a Telegram (ver "Conversaciones" más abajo).

Roles

• owner, admin: conectar, editar, asignar agentes o equipos, activar/desactivar, cambiar el ajuste de adjuntos y desconectar bots.
• agent: puede abrir la página y trabajar las conversaciones de Telegram en la bandeja compartida, pero no puede gestionar las conexiones de bots.

Requisitos previos

• El módulo de Telegram se habilita por workspace. Cuando no está habilitado para el tuyo, la página no es accesible y te devuelve a tu panel.
• Tu plan decide si puedes usar Telegram y cuántos bots puedes tener. Se pueden añadir espacios de bot con el Social Accounts Pack.
• Un bot de Telegram creado con @BotFather (gratis, toma un minuto en la app de Telegram).
• Un agente que atienda Telegram. Estar activo ya no basta: esta página solo ofrece agentes que estén activos y tengan Telegram marcado en su pestaña Channels (Agents -> abre un agente -> Channels -> Telegram / "Answer Telegram chats"). Esa pestaña lo dice tal cual: "Choose the channels this agent can work on. On each channel page, only the agents ticked for that channel can be picked." Un agente que nunca declaró Telegram no se ofrece aquí, por muy activo que esté.
• Un email verificado (un workspace sin verificar no puede conectar un canal).
• Los bots responden solo chats privados: los mensajes en grupos o canales no se importan, así que añade tu bot donde los clientes le escriban directamente.

Indicadores de cabecera

Cuando tu plan incluye Telegram, la parte superior de la página muestra chips de estadísticas compactos:

• Needs you — conversaciones marcadas para atención; al pulsarlo abre Conversations ya filtrada a esa cola.
• Conversations — total de conversaciones de Telegram; abre Conversations filtrada a Telegram.
• bots — bots activos en uso; se pone ámbar cuando alcanzas el techo de tu plan. Es el único chip sin enlace, porque la lista de bots está justo debajo. A su lado, una línea simple dice "of N bots in your plan" (o "unlimited in your plan").

Si los conteos no se pueden leer, los chips se ocultan en lugar de mostrar ceros engañosos. El botón View conversations de la cabecera abre la bandeja compartida filtrada a Telegram.

Conectar un bot

1. En Telegram, abre @BotFather, crea un bot y copia su token.
2. En el módulo de Telegram, pulsa Connect bot.
3. Completa el modal (Connect Telegram bot — "Paste your bot token to connect."):

4. Pulsa Connect. El token se valida, el @username del bot se lee desde Telegram, y el webhook se registra automáticamente. Si el paso del webhook falla, el bot se guarda con la insignia Webhook pending y el mensaje "The bot was saved but the webhook could not be registered. Save again to retry." — guarda de nuevo para reintentar.

Elegir un agente o un equipo

El mismo selector se usa en el modal y en línea en cada fila de bot, y ambos aplican la misma regla: un agente aparece solo si declara Telegram.

• Los equipos están limitados dos veces. El grupo "Teams (can ask a specialist for help)" aparece solo cuando tu plan tiene equipos habilitados y al menos uno de los agentes ofrecidos coordina un equipo con un especialista aprobado. Un coordinador que no declara Telegram tampoco se ofrece aquí como equipo.
• Cada opción de equipo se lee "Team: nombre (N specialists)". Al seleccionar un equipo, una línea bajo el selector lo nombra, indica cuántos especialistas aprobados tiene y ofrece un enlace Manage a la página de Teams.
• El texto de ayuda del selector te dice exactamente en qué estado estás cuando nada califica:

Gestionar bots conectados

Cada bot conectado es una fila en una sola lista: un punto de estado, el icono de Telegram, su @username (con el Bot ID numérico debajo), insignias de estado, un selector de agente/equipo en línea, el interruptor activo/inactivo y un menú con Edit y Disconnect. Hasta asignar un agente, el interruptor está deshabilitado con "Select an agent to start replying."

Los detalles secundarios no están escondidos tras un control de expandir — se muestran en una franja justo debajo de cada fila: la casilla Accept attachments, el Bot ID y, cuando la conexión no está sana, el mensaje de salud con un botón Reconnect.

Insignias de estado que puedes ver: Solo o Team (con el número de especialistas), Webhook pending, Needs reconnection, Linked agent inactive y Paused by plan limit.

Notas:

• La política Accept attachments se guarda en el agente vinculado, así que es por agente, aplica a cada conexión que use ese agente y queda deshabilitada hasta asignar uno.
• Si el agente actual del bot deja de calificar — desactivado, o con Telegram desmarcado — se mantiene en el selector con un sufijo que nombra cuál de los dos casos es: "(Linked agent inactive)" o "(This channel is off on the agent)". Se arreglan en pantallas distintas, y mantener la entrada evita que un guardado posterior borre una asignación que no tocaste.
• Quitar el agente desactiva automáticamente el bot.
• ¿Necesitas otro bot? Créalo con @BotFather y conéctalo aquí con su token.

Editar y reconectar

• Edit abre el mismo modal titulado "Edit Telegram bot". El bot token es opcional aquí — "Leave blank to keep the current token." Guarda con Save.
• Si un token se revoca, el bot muestra Needs reconnection con "The bot token was revoked or is no longer valid. Paste a new token to reconnect." Pulsa Reconnect en la franja bajo la fila (abre el modal de edición), pega un token nuevo de @BotFather y pulsa Save.
• Reconectar funciona incluso cuando el agente vinculado ya no califica para Telegram: el modal retiene ese agente en el selector, así que pegar un token nuevo no pierde la asignación.

Desconectar

Disconnect pide confirmar (Disconnect bot): "Disconnect {name}? Your agent will stop replying to its Telegram conversations. This cannot be undone." Quita el webhook y elimina la conexión permanentemente.

Límites del plan

• Una línea de uso bajo Connected bots muestra cuántos bots activos usas del total de tu plan (o "unlimited").
• Sin el permiso del plan, la página muestra "Telegram is not in your plan" con un botón View plans.
• Los límites se aplican al conectar y al activar un bot; alcanzar un límite abre un diálogo de mejora. En el techo, el botón Connect bot queda deshabilitado, con "You've reached your plan's Telegram bot limit." como tooltip. El Social Accounts Pack añade un espacio de bot por unidad, y el límite mostrado ya lo incluye.
• Si la aplicación del plan pausa un bot, muestra la insignia Paused by plan limit hasta que mejores el plan o liberes un espacio.

Conversaciones

Las conversaciones de Telegram viven en la bandeja compartida: View conversations (o cualquier chip de estadísticas) abre /app/{tenant}/conversations filtrada a Telegram, con búsqueda, vista previa de mensajes, el panel de contacto y la cola de atención pendiente. Abrir una conversación muestra la vista de detalle de Telegram con control humano Take over / Hand back to AI, un redactor de respuesta y una insignia Team-assisted cuando ayudó un equipo; la flecha de volver regresa a Conversations filtrada a Telegram.

Buenas prácticas

• Marca Telegram en la pestaña Channels del agente antes de venir aquí; si no, el selector de esta página no tendrá nada que ofrecer.
• Asigna el agente antes de activar el bot; un bot sin agente no puede activarse.
• Si el selector de un bot muestra su agente con "(This channel is off on the agent)", no elijas a otro sin más — decide si ese agente debe atender Telegram y marca la casilla, o reasigna deliberadamente.
• Si las respuestas se detienen, busca una insignia Needs reconnection y pega un token nuevo.
• Mantén Accept attachments activado si los clientes envían fotos o notas de voz que quieres que el agente maneje — y recuerda que aplica a cada conexión que use el mismo agente.
• Comparte con tus clientes el enlace directo del @username de tu bot; los mensajes enviados en grupos o canales no se importan.

Errores comunes

Relacionado

• Agentes de IA
• Equipos
• Conversaciones
• Facturación y uso