Cómo redujimos a cero la configuración de Telegram

Durante casi todo el primer año de Vyneron, quien quería Telegram tenía cinco pasos por delante. La mayoría no pasaba del segundo.

El problema: configurar un bot propio mataba los registros

Antes, la parte de Telegram del producto funcionaba así:

Abre Telegram. Escribe a @BotFather. Crea un bot nuevo. Copia un token de 46 caracteres que parece basura. Abre los ajustes de Vyneron. Pega el token en «Usa tu propio bot». Espera a que se registre el webhook. Por fin puedes escribir a tu lista de tareas.

Cada registro que quería Telegram tenía que hacer los cinco. La mayoría nunca terminaba el segundo.

No era que la gente que se registraba tuviera poca motivación. Era que cada paso era de esos que solo disfruta un desarrollador: engendrar un bot, ponerle nombre, encontrar un usuario que no estuviera cogido, copiar y pegar un token entre dos apps, confiar en que el pegado se guardó de verdad. Para alguien que solo quería mandar comprar leche mañana desde el chat donde ya organiza la cena, ese ritual no guardaba ninguna proporción con el valor.

Así que se iban. Y la superficie de Telegram, posiblemente lo más distintivo de Vyneron, se quedaba ahí, detrás de un muro de fricción que el resto del producto no tenía.

Este artículo es la historia de quitar ese muro. Lo que lanzamos es un bot de Telegram compartido: cada cuenta de Vyneron habla con el mismo @VyneronAIBot, y el bot averigua a qué espacio de trabajo pertenece el mensaje. Sin tokens propios. Sin copiar y pegar. Sin visitar a @BotFather.

En resumen

En resumen: Vyneron sustituyó el modelo de «cada cuenta configura su propio token» por un único @VyneronAIBot compartido que cualquier cuenta enlaza en menos de diez segundos. El enlace de la cuenta ocurre pegando en el chat del bot un código corto de seis caracteres generado en la app web. La app web sigue siendo la superficie principal; Telegram es una capa acompañante opcional, para quien ya vive en su mensajería. Toda la migración llevó unas 24 horas: treinta y tres commits, una migración de base de datos única y un corte limpio que no rompió a los dos usuarios ya enlazados.

Por qué un bot compartido llevó un año

La respuesta honesta: los tokens por cuenta eran más fáciles de lanzar primero.

Cuando salió Vyneron, «cada cuenta trae su propio bot» era una historia de aislamiento limpia. El tráfico de Telegram de cada espacio de trabajo pasaba por su propio webhook, los tokens se guardaban cifrados por empresa, y no había identidad compartida que razonar. Si algo fallaba en el bot de un cliente, era su bot: la depuración seguía siendo local, y no había nada global que tirar por accidente.

El precio era el de arriba: cada interesado en Telegram tenía que meterse cinco pasos en territorio de herramientas de desarrollo antes de obtener valor. Lo tolerábamos al principio porque la base de usuarios era lo bastante pequeña para acompañarlos uno a uno. Cuando la fricción empezó a verse en los datos reales del embudo (cuentas que se registraban, nunca conectaban Telegram y se alejaban en silencio), el cálculo cambió.

Así el bot compartido pasó de «estaría bien» a «es la restricción». El trabajo: conservar cada garantía de aislamiento que daban los tokens por cuenta, y a la vez reducir la configuración a un único mensaje en el chat.

La arquitectura, en claro

En el modelo compartido hay exactamente un bot de Telegram para todo el producto: @VyneronAIBot. El webhook de Telegram dirige cada mensaje entrante a un único punto del backend, que tiene que responder una pregunta antes de hacer nada útil:

¿Qué cuenta de Vyneron es este usuario de Telegram?

Mientras el usuario no esté enlazado, la respuesta es «nadie que conozcamos». Su mensaje recibe una invitación amable y limitada a registrarse, y nada más: sin crear tareas, sin llamadas de IA, sin filtración de cuentas. (El límite existe porque el flujo /start de un único bot compartido también es buen blanco de ruido, así que los remitentes no enlazados reciben una respuesta amable como mucho una vez por minuto.)

Una vez enlazado, la respuesta es una fila en una tabla pequeña: telegram_user_id → user_id. A partir de ahí, el backend trata los mensajes entrantes igual que el viejo flujo por cuenta. La misma canalización de IA, la misma creación de tareas, la misma vuelta al panel. El bot compartido es un enrutador; la lógica del espacio de trabajo no cambió.

Una imagen simplificada:

Telegram → webhook @VyneronAIBot → backend
                                     │
                                     ├─ ¿telegram_user_id conocido?
                                     │      ├─ sí  → cargar la cuenta → ejecutar la canalización
                                     │      └─ no  → invitación a registrarse (limitada)
                                     │
                                     └─ la canalización escribe en la BD de la app web
                                              │
                                              └─ la app web lo recoge

La parte que más cuidado llevó fue el tercer paso del enrutamiento: convertir el primerísimo mensaje de un desconocido en un enlace verificado, sin pedirle nunca que pegue un token.

Cómo funciona de verdad el enlace de cuenta

Cuando un usuario con sesión abierta entra en Ajustes → Integraciones y pulsa Conectar Telegram, el backend acuña un código de enlace corto:

code        = "8X4-K2Q"       # 6 caracteres, alfabeto sin 0/O/1/I
user_id     = 42
expires_at  = now + 10 minutos
consumed    = false

La app web muestra el código y un enlace directo como t.me/VyneronAIBot?start=8X4-K2Q. Desde ahí el usuario tiene dos caminos igual de cortos:

• Tocar el enlace directo. Telegram se abre, el bot le saluda, y la carga start llega en la primera actualización.
• Teclear el código a mano en el bot. El mismo final, solo que más lento.

En ambos casos, el backend acaba con una única actualización de Telegram que contiene un código y un campo from.id (el identificador numérico del lado de Telegram). A partir de ahí:

1. Buscar el código. Si no existe, ha caducado o ya se usó, responder con un error claro.
2. Marcarlo como usado de forma atómica. El mismo código no se puede reclamar dos veces, ni siquiera por el mismo usuario en dos toques en paralelo.
3. Escribir telegram_user_id = from.id en la cuenta de Vyneron correspondiente.
4. Responder en el chat: «✅ Conectado a tu espacio de trabajo.»

Todo el flujo es una sola petición HTTP desde el punto de vista del usuario, y tres operaciones de base de datos en el backend. Sin token. Sin copiar y pegar. Sin @BotFather. Y sin ningún escenario en el que un desconocido a la cuenta pueda enlazar su identificador de Telegram sin antes tener la sesión abierta en la app web y haber pulsado el botón que generó el código.

Algunos detalles que importan más de lo que parecen:

• El código es corto. Seis caracteres con un alfabeto amable hacen realista teclearlo en un móvil. Diez habrían sido técnicamente más seguros; seis fue el equilibrio justo frente a las tasas de errata que medimos durante la migración.
• Caduca en diez minutos. Suficiente para ir del portátil al móvil, lo bastante corto para que una captura filtrada no sirva de nada para cuando alguien se dé cuenta.
• Los códigos son de un solo uso y se invalidan al generar uno nuevo. Pulsar «Conectar Telegram» una segunda vez quema el anterior: el intento más reciente es siempre el único válido. Eso elimina el lío de «pulsé dos veces y ya no sé qué código está vivo».

El despliegue en 24 horas

Toda la migración salió en, más o menos, un día natural, en dos fases.

Fase 1 — backend. Veintitrés commits para levantar el bot compartido, la tabla de códigos de enlace, la invitación limitada y el enrutamiento. Luego nueve correcciones tras la revisión para cerrar los casos límite que solo se ven cuando dejas de confiar en el camino feliz: la tarea de fondo del ciclo de vida que no se esperaba, el código de enlace que se podía usar dos veces si dos peticiones competían, el comando de ayuda que se caía en silencio para los no enlazados, la comparación de tiempo constante que el commit original había olvidado, un límite de peticiones demasiado celoso, y algunos más.

Fase 2 — canario de ocho pruebas. Antes de abrir la puerta principal, ejecutamos un guion explícito: un mensaje no enlazado recibe la invitación, el código de enlace funciona en el camino feliz, el mismo código no se reutiliza, regenerar un código invalida el anterior, el comando de ayuda se porta bien con enlazados y no enlazados, el webhook devuelve 200 aun cuando el mensaje no se puede procesar (Telegram reintenta para siempre ante cualquier cosa que no sea 200), y el bot central sigue sano en /api/health. Cada comprobación tenía que pasar antes del cambio del frontend.

Fase 3 — frontend. La interfaz de «Usa tu propio bot» de los ajustes desapareció. En su lugar: una única sección de Telegram con tres estados — No conectado (un botón), Código visible (cuenta atrás, copiar, enlace directo) y Conectado (tarjeta de cuenta con Desconectar). Veintiuna claves de traducción nuevas en seis idiomas.

El corte limpio funcionó porque a estas alturas la base de usuarios era minúscula (el fundador y un amigo), y ambos se volvieron a enlazar con el nuevo flujo esa misma noche. Para una base mayor, la misma migración habría querido una bandera de función y una ventana de tolerancia. Evitamos esa complejidad a propósito, porque habría costado más tiempo que toda la base de usuarios.

Lo que no cambió: la app web sigue siendo central

Dicho sin rodeos: nada de esto hace que Telegram sea obligatorio.

La app web es y sigue siendo la superficie principal de Vyneron. Tareas, rutinas, notas, archivos y búsqueda por IA funcionan en el navegador sin abrir nunca Telegram. Si te registraras mañana y nunca enlazaras el bot, tendrías el producto completo. El correo de activación que enviamos 24 horas tras el registro dice justo esto: la app web está lista, y Telegram es una superficie extra opcional para quien ya vive en su mensajería.

El trabajo del bot compartido iba de quitar fricción a quien quería Telegram, no de imponer la superficie a quien no. Tratar Telegram como un superpoder y no como una obligación es la línea a la que siempre volvemos. Mucha gente de Vyneron nunca enlazará una cuenta de Telegram, y el producto debe sentirse completo para ellos también.

Qué sigue

El bot compartido abre algunas puertas que el modelo por cuenta mantenía cerradas.

• Mini Apps de Telegram. Una sola identidad de bot nos deja añadir una dirección Web App t.me/VyneronAIBot/app y dejar que la gente abra toda la PWA desde Telegram con un toque, además de generar enlaces directos compartibles a tareas y notas concretas. Es trabajo posterior al lanzamiento: escala con la base de usuarios, así que rinde más tarde.
• Modo en línea. @VyneronAIBot buscar factura desde cualquier otro chat de Telegram, con resultados en línea. El espacio para eso vive tras la misma identidad compartida.
• Bienvenida inteligente. Con un solo bot, podemos iterar la primerísima respuesta /start para toda la gente a la vez: cambios de texto, sugerencias de comandos, detección de idioma vía from.language_code.

Pero antes de todo eso, lo más útil es lo más pequeño: mantener la fricción a cero. La victoria no fue «lanzamos un bot compartido». Fue que alguien puede ir ahora del registro a una tarea de Telegram funcionando en menos de un minuto, sin un solo ritual de desarrollador, conservando una superficie web principal a la que le da igual si abre el bot algún día o no.

Esa clase de trabajo es invisible cuando aterriza, que es justo el objetivo.

Vyneron es un espacio de trabajo de productividad con IA, pensado para Telegram, con conocimiento integrado de los días festivos de más de 250 países, precios BYOK y OCR para fotos y archivos. La app web es la superficie principal; Telegram es opcional. Prueba Vyneron gratis o echa un vistazo al estudio de bots de tareas de Telegram para el contexto del ecosistema.