Integración con Telegram

Conecta tu agent a Telegram y deja que los usuarios chateen con él directamente en la app de Telegram.

Descripción General

La integración con Telegram ofrece:

• Respuestas en streaming en vivo (Bot API 9.5 sendMessageDraft con fallback de edición de mensajes)
• Mensajes de voz transcritos automáticamente con Whisper
• Formato MarkdownV2 que se renderiza limpio cada vez
• Campañas con deep links con welcome y respuestas sugeridas personalizadas
• Reacciones con emoji de un solo toque y clasificación de sentimiento
• Slash commands integrados (/start, /help, /reset, /new)
• Mensajes directos y chats grupales (sesiones por usuario en grupos)
• Una Tienda dentro del bot integrada — catálogo de productos multipágina, chat de IA por producto y toma de pedidos ligera, todo dentro de Telegram (gratis en todos los planes)
• Co-pilot opcional de Telegram Business para usuarios Premium (integración separada)
• Saba en Telegram para operadores (integración separada)

Requisitos Previos

• Una cuenta de Telegram
• Acceso a BotFather (la herramienta de creación de bots de Telegram)

Pasos de Configuración

1. Crear un Bot de Telegram

1. Abre Telegram y busca @BotFather
2. Inicia un chat y envía /newbot
3. Sigue las indicaciones:
   • Ingresa un nombre para tu bot (por ejemplo, “My Support Bot”)
   • Ingresa un nombre de usuario (debe terminar en “bot”, por ejemplo, “mysupportbot”)
4. BotFather te dará un Bot Token — guárdalo de forma segura

2. Conectar a Cuneiform Chat

1. Ve a Agents → Selecciona tu agent
2. Navega a la pestaña Integrations
3. Haz clic en Telegram
4. Pega tu Bot Token
5. Haz clic en Connect

3. Configurar tu Bot

Configuraciones opcionales del bot mediante BotFather:

• /setdescription — Lo que hace el bot
• /setabouttext — Información en el perfil del bot
• /setuserpic — Foto de perfil de tu bot

4. Probar tu Bot

1. Encuentra tu bot en Telegram buscando su nombre de usuario
2. Inicia una conversación con /start
3. Envía un mensaje y verifica que recibas una respuesta

Cómo Funciona

Usuario envía mensaje → Telegram → Cuneiform Chat → Agent procesa → Respuesta enviada de vuelta

Los mensajes se procesan en tiempo real. El agent busca en tu contenido y genera respuestas según tu configuración.

Funcionalidades

Respuestas en streaming en vivo

La respuesta del bot aparece en milisegundos y crece in situ a medida que el agent piensa — usando el sendMessageDraft nativo de Telegram (Bot API 9.5) donde está disponible, con un fallback de edición de mensajes con throttling en el resto de los casos. Se acabaron los 5 a 15 segundos de silencio entre la pregunta y la respuesta.

Mensajes de voz

Las notas de voz enviadas al bot se transcriben mediante Whisper y se responden como si hubieran sido escritas. El idioma se detecta automáticamente a partir de la conversación, por lo que los clips cortos en cualquier idioma siguen siendo precisos. Tope de 2 minutos por nota. Disponible en todos los planes, incluido el trial gratuito.

Formato MarkdownV2

Negritas, cursivas, bloques de código, listas y enlaces se renderizan exactamente como tu agent lo intenciona — sin markdown roto ni asteriscos perdidos. El escape está centralizado en la plataforma para que cada respuesta se mantenga limpia. MarkdownV2 es el predeterminado; el modo HTML está disponible por integración si es necesario.

Deep links y campañas de referidos

Genera enlaces t.me/your-bot?start=your-code desde la tarjeta de la integración. Cada código puede llevar un mensaje de bienvenida personalizado y hasta tres respuestas sugeridas. Se rastrean por código el click-through, los usuarios únicos y la conversión de conversaciones — útiles para campañas publicitarias, códigos QR y atribución multicanal.

Reacciones con emoji de un solo toque

Los usuarios reaccionan a los mensajes del bot con 👍, ❤, 😡 o cualquier emoji. El bot responde con el tono adecuado mediante breves respuestas de acuse de reacción. Un clasificador integrado mapea cualquier emoji a una señal positiva, negativa o neutra que puedes analizar luego. Actualmente activo en DMs.

Slash commands

La integración registra una lista de comandos predeterminada con Telegram al conectarse, de modo que los usuarios ven /start, /help, /reset y cualquier comando personalizado que crees en el menú nativo de autocompletar de Telegram. /start, /help, /reset y /new se manejan inline sin costo de AI. Arrastra para reordenar; hasta 32 entradas.

Mensajes directos

Los usuarios chatean con tu bot uno a uno para conversaciones de soporte privadas. Cada usuario tiene su propia sesión.

Chats grupales

Agrega tu bot a chats grupales:

1. Agrega el bot a un grupo
2. Conviértelo en admin (para acceso completo a los mensajes — ver Group Privacy abajo)
3. Los usuarios mencionan al bot (@your_bot) o responden a sus mensajes

Cada usuario en un grupo tiene su propio thread de conversación — el bot no mezcla sesiones entre miembros. Los grupos con forum-topic están soportados; los threads se mantienen acotados a su tema.

Tienda dentro del bot

Cada bot de Telegram que conectes viene con una Tienda integrada — un sitio web multipágina pulido dentro del bot que se abre dentro de Telegram cuando los usuarios finales tocan el botón de menú junto al compositor de mensajes. Tarjetas de producto, galerías, videos, páginas con temas, chat de IA por producto y toma de pedidos ligera que pasa a un humano real en tu inbox — todo sin instalar una app ni un sitio web aparte.

Cableado automático al conectar: el botón del menú de chat abre la tienda, etiquetada como “Shop” si publicas un producto o “Open” en caso contrario. Disponible en todos los planes, incluido el trial gratuito.

La guía completa de la funcionalidad — compositor, bloques, temas, chat por producto, CTAs de pedido, límites por tier — vive en una página dedicada:

→ Tienda de Telegram para la configuración completa, la referencia de bloques y el flujo del cliente.

Un pequeño panel de soporte Help Center queda fijado al final del menú de páginas de la tienda para accesos rápidos de FAQ + preguntar al bot. La mayoría de las tiendas no se apoyan mucho en él — los productos y los CTAs de pedido responden las preguntas del flujo de compra en la tienda misma. Crea entradas desde el menú de tres puntos de la tarjeta del bot → Help Center (hasta ~50 entradas, arrastra para reordenar, ~5 minutos de caché del servidor).

Co-pilot de Telegram Business

Los usuarios de Telegram con plan Premium pueden hacer que tu bot responda DMs en su cuenta personal mediante el modo Business de Telegram. El bot responde a través del business_connection_id del usuario Premium, así que los contactos ven lo que parece ser la respuesta del propio usuario Premium — útil para founders, creadores y equipos pequeños que reciben DMs en sus cuentas personales todo el día.

La configuración es una integración separada en el panel de administración (“Telegram Business co-pilot”). Invariantes clave:

• 1 bot = 1 customer agent. Un bot de Telegram solo puede apuntar a un webhook a la vez — no puedes compartir un bot con la integración regular de Telegram ni con Saba en Telegram. Crea un bot nuevo de BotFather para el modo Business.
• El toggle Business Mode de BotFather es obligatorio. Sin él, los usuarios Premium ven “this bot doesn’t support Telegram Business yet” al agregarlo. Actívalo en Bot Settings → Business Mode.
• N usuarios Premium por integración. Cada uno se vincula una vez mediante /start <code> en un DM regular con el bot.
• Solo DMs. Las conexiones Business no cubren chats grupales.
• El takeover manual es automático. Cuando el usuario Premium escribe una respuesta él mismo, el bot se pausa en ese chat por una ventana deslizante para no interrumpir una conversación en vivo.
• Kill switch a nivel de conexión. Activa “Disable auto-reply” en la tarjeta de la integración para pausar el bot en todos los usuarios Premium vinculados sin desconectar.

Consulta Connect Business bot en la sección Telegram Business co-pilot de la página Integrations del panel de administración para el playbook completo de configuración.

Saba en Telegram

Los operadores también pueden chatear con Saba (el asistente de la plataforma) desde un bot de Telegram dedicado. Mismos permisos y acceso a datos que el panel de administración — útil cuando estás lejos de tu laptop y necesitas revisar estadísticas de agents, billing o actividad reciente.

Dos superficies sobre el mismo canal:

• DM bot — respuestas de texto en un DM regular de Telegram, con botones de acción inline que hacen deep-link de vuelta a la página correcta del panel de administración (?from=saba_telegram para atribución).
• Saba Mini App — una superficie de chat más rica dentro de Telegram en saba-mini.cuneiform.chat con historial de conversaciones, detalle de tool-call, entrada de voz por navegador y exportación a markdown. Cada respuesta de DM lleva un botón inline “Open in Mini App” para cambiar de superficie a mitad de la conversación.

La configuración es del lado admin: conecta un bot nuevo de BotFather en “Saba on Telegram” en Integrations. Cada miembro de la organización vincula luego su cuenta personal con un código de 10 minutos.

Consulta Platform Assistant → From Telegram para la experiencia del lado del usuario.

Comandos del Bot

Puedes configurar comandos personalizados mediante BotFather:

Solución de Problemas

El Bot No Responde

1. Verifica que el bot token sea correcto
2. Comprueba que la integración esté conectada en Cuneiform Chat
3. Asegúrate de que tu agent esté configurado correctamente
4. Prueba primero el agent en el Playground

Problemas con el Token

Si necesitas un token nuevo:

1. Ve a BotFather
2. Envía /mybots → Selecciona tu bot → API Token → Revoke
3. Actualiza el nuevo token en Cuneiform Chat

Problemas en Chats Grupales

• Asegúrate de que el bot tenga permisos de admin
• Comprueba la configuración del modo de privacidad mediante BotFather (/setprivacy)

Seguridad

• Los bot tokens están cifrados y almacenados de forma segura
• Las conversaciones se procesan a través de conexiones seguras

Desconectar

Para eliminar la integración con Telegram:

1. Ve a Agents → Selecciona el agent → Integrations
2. Haz clic en Telegram → Disconnect

Esto detiene las respuestas del bot pero no elimina el bot de Telegram en sí. Bórralo mediante BotFather si es necesario.