Telegram Bot API 10.4: widgets, miniaplicaciones y pagos TON

2026-11-12
Widgets dentro del chat, pagos con TON y mensajes efímeros: los siete cambios del Bot API 10.4 de Telegram, ordenados por impacto real para tu bot.
Telegram publicó el Bot API 10.4 el 9 de noviembre, y no es una actualización de mantenimiento. Los bots pueden enviar widgets HTML dentro de un mensaje, recibir consultas desde esos widgets y cobrar con la cartera TON sin salir de la conversación. Para los desarrolladores de Telegram, el mensaje deja de ser texto con botones y pasa a ser una superficie de aplicación.
He leído el changelog oficial completo y lo he ordenado por lo que cambia de verdad en el trabajo diario. El criterio es simple: primero lo que obliga a replantear el producto, después lo que ahorra código, y al final lo que solo afecta a casos concretos.
Si tienes un bot en producción, hay dos cosas que conviene saber antes de tocar nada. La primera es que los widgets solo se pueden enviar a chats privados en el entorno de producción. La segunda es que el contenido de esos widgets se marca como protegido y no se puede reenviar ni copiar con los métodos de copia.
Tabla de cambios de Telegram Bot API 10.4, por impacto
| Puesto | Cambio | Qué permite | Por qué está aquí |
|---|---|---|---|
| Uno | Widgets HTML en mensajes | Miniaplicaciones dentro del chat | Reemplaza el flujo de abrir un Web App |
| Dos | Consultas de widget con TON | Recibir datos y pagos | Convierte el mensaje en punto de venta |
| Tres | Mensajes efímeros | Respuestas que no quedan | Cambia cómo se responden los botones |
| Cuatro | Tarjetas de cartera TON | Mostrar wallet y NFT en el perfil | Identidad y pagos en el mismo sitio |
| Cinco | Citas de mensajes enriquecidos | Citar fragmentos con formato | Mejora la conversación en grupos |
| Seis | Temas para compartir chats | Enlaces con tema visual | Nuevo gancho de crecimiento |
| Siete | Regalos únicos y usuarios secundarios | Consultas y nombres con sufijo | Detalles de producto y de marca |
Puesto uno: los widgets convierten el mensaje en una miniaplicación
El cambio central de la versión. Se añade la clase Widget y el campo widget a Message y a ExternalReplyInfo, junto con el método sendWidget, que permite a un bot enviar un mensaje con un widget HTML dentro.
La diferencia con las miniaplicaciones de Telegram que ya existían es de fricción. Antes el usuario tocaba un botón, se abría una vista web a pantalla completa y volvía al chat. Ahora el widget vive en la burbuja del mensaje, así que la interacción ocurre donde ya está el usuario.
Ese detalle parece menor y no lo es. Un formulario de dos campos dentro del chat se rellena el doble de veces que el mismo formulario en una Web App, porque no hay cambio de contexto ni espera de carga.
Los límites son importantes y conviene tenerlos claros antes de diseñar. En producción, los widgets solo se envían a chats privados, tienen contenido protegido y no se pueden reenviar. Tampoco se pueden enviar como respuesta a consultas inline en el entorno de producción, aunque el método InputWidgetMessageContent ya existe para cuando se habilite.
Puesto dos: las consultas de widget y la cartera TON
Un widget que no devuelve nada es un póster. La versión 10.4 añade la clase WidgetQuery y el campo widget_query en Update, más la clase SharedWidgetQuery para los widgets compartidos de mensajes reenviados.
Con answerWidgetQuery, el bot responde a lo que el usuario hizo dentro del widget. Y aquí está la parte interesante para quien cobra: los tipos de consulta incluyen datos, datos firmados por una cartera TON y notificaciones de transacciones enviadas desde una cartera TON.
Eso significa que un bot puede pedir un pago, recibir la firma y confirmar la transacción sin abrir un navegador ni pedir al usuario que copie una dirección. Para la cartera TON de Telegram, el chat pasa a ser la pasarela.
Para los desarrolladores de Telegram que llevan tiempo peleando con flujos de pago externos, este es el cambio que más trabajo ahorra. Para quien no cobra nada, sigue siendo relevante: el mismo mecanismo sirve para confirmar una reserva, un formulario o una encuesta.
Qué cambia para las miniaplicaciones de Telegram que ya tienes
Las miniaplicaciones de Telegram no desaparecen con esta versión, y conviene decirlo porque la lectura fácil es que los widgets las sustituyen. No es así: comparten propósito pero no alcance.
Una miniaplicación abre una vista completa, con navegación propia y acceso a todo el ancho de la pantalla. Un widget vive dentro de la burbuja y está pensado para una tarea corta: elegir una opción, confirmar un pedido, enseñar un estado. Si trasladaras una tienda entera a un widget, el usuario acabaría desplazándose dentro de una burbuja de chat.
La forma sensata de combinarlos es la que ya están usando los bots grandes. El mensaje lleva el widget con la acción principal, y la Web App queda para el flujo profundo, los formularios largos y las pantallas que necesitan navegación.
Los widgets interactivos de Telegram también cambian el coste de mantenimiento. Un widget es HTML servido por tu bot, así que puedes actualizarlo sin publicar una versión nueva de la app. Para equipos pequeños, eso es la diferencia entre iterar en una tarde y esperar una revisión.
Hay un límite que sorprende a quien viene del desarrollo web: los widgets enviados tienen contenido protegido y no se pueden copiar con copyMessage ni reenviar. Si tu producto dependía de que el usuario compartiera el mensaje, tendrás que ofrecerle otra vía.
Puesto tres: mensajes efímeros en cualquier chat
Los mensajes efímeros existían, pero estaban atados a un caso concreto. Ahora los bots pueden enviar respuestas efímeras a las consultas de callback en cualquier chat, excepto en los chats de canal con mensajes directos, indicando el callback_query_id sin receiver_user_id.
En la práctica, tu bot puede responder a un botón con un mensaje que solo ve quien lo pulsó. Se acabó eso de ensuciar el grupo con un "recibido" cada vez que alguien toca un botón.
Los campos receiver_user_id y chat_id pasan a ser opcionales en los métodos afectados, lo que simplifica el código existente. Si ya enviabas respuestas efímeras en un caso concreto, la migración no rompe nada: solo amplía dónde funciona.
Para los grupos grandes, este es el cambio más útil después de los widgets. Y para los canales de noticias, evita el ruido de confirmaciones públicas.
Puesto cuatro: la tarjeta de cartera TON en el perfil
La versión añade las clases TonWalletCard, TonWalletCardSticker, TonNft y TonNftAttribute, más el campo ton_wallet_card en ChatFullInfo. También aparece TonWalletTransfer y el campo ton_wallet_transfer en Message para los mensajes de servicio de transferencias.
Traducido: un chat puede mostrar la cartera del usuario y sus NFT en la ficha del perfil, y los bots pueden detectar transferencias como mensajes de servicio.
Ahí hay una decisión de privacidad que cada desarrollador tiene que tomar. Mostrar la cartera en el perfil es cómodo para cobrar y para verificar propiedad, pero también expone el historial público de una dirección a cualquiera que abra el chat.
La clase StoryAreaPosition se renombra a AreaPosition porque ahora también describe la posición de stickers en las tarjetas de cartera TON. Es un cambio de nombre que rompe código si lo usabas: revisa tus imports antes de actualizar.
Puesto cinco: citas de mensajes enriquecidos
TextQuote gana el campo rich_texts, y ReplyParameters añade quote_rich_texts. Con eso, un bot puede citar un fragmento de un mensaje enriquecido conservando el formato, no solo el texto plano.
Suena a detalle de implementación, y en parte lo es. Pero en grupos donde la gente pega bloques de código o listas con formato, citar sin perder el formato evita el clásico "no sé a qué parte respondes".
El impacto es bajo comparado con los widgets, y por eso está en el puesto cinco. Aun así, es el tipo de mejora que se nota a los dos días y que no requiere migración: si no la usas, todo sigue funcionando.
Puesto seis: temas para compartir chats
ChatFullInfo recibe el campo share_theme, con las clases ChatShareTheme, ChatShareThemeEmoji y ChatShareThemeUniqueGift. Se suman EmojiType y sus variantes, más ChatShareThemeBackdrop y el método getChatShareThemeBackdrops.
El caso de uso es el enlace de invitación: cuando alguien comparte un chat, la pantalla puede llevar un tema visual concreto, con emoji y fondo propios. Para comunidades que compiten por atención, es un gancho de crecimiento barato.
Para un bot de servicios, en cambio, aporta poco. Está en el ranking por lo que habilita a las comunidades, no por lo que resuelve a un desarrollador de herramientas.
Puesto séptimo: regalos únicos y nombres de usuario secundarios
El changelog cierra con dos cambios pequeños. El método getUniqueGift permite consultar un regalo único por su nombre, y deleteBusinessAccountGift deja borrar regalos normales de una cuenta de empresa gestionada sin recibir Estrellas.
En el apartado general, los usuarios con suscripción Premium pueden asignar nombres de usuario secundarios terminados en agent, ai, app, game o gay a hasta dos bots propios. Es una decisión de producto más que técnica: los bots ganan identidad dentro del ecosistema.
Ninguno de los dos cambia tu arquitectura. Los pongo al final porque afectan a casos muy concretos y porque el resto de la versión se come la mayor parte del tiempo de migración.
Cómo migrar tu bot a Telegram Bot API 10.4 sin romperlo
Empieza por lo aburrido: revisa si usas StoryAreaPosition en algún sitio, porque el renombrado a AreaPosition rompe la compilación. Es el único cambio que obliga a tocar código existente sin que puedas ignorarlo.
Después decide si los widgets entran en tu producto. Si tu bot ya tiene una Web App, no la borres: los widgets solo funcionan en chats privados en producción, y la Web App sigue siendo la vía para grupos y para flujos largos.
Y revisa los permisos. El derecho can_send_other_messages de ChatPermissions ahora también permite enviar widgets, así que un grupo con esa restricción activa puede rechazar tus mensajes nuevos sin que el error sea evidente.
Prueba los widgets con la cuenta de un usuario real, no con un cliente de pruebas. El comportamiento del desenfoque, del teclado y de la altura del mensaje cambia entre Android, iOS y escritorio, y el chat privado de producción es el único sitio donde puedes comprobarlo tal cual lo verá la gente.
Por último, deja una vía de escape. Si el widget falla al cargar, el bot debería responder con un mensaje de texto con botones en lugar de quedarse en silencio. Los primeros días de una función nueva son los que más errores de red acumulan.
La 10.4 es la actualización más grande del Bot API en años, y la que más cambia la relación entre un bot y su usuario: menos saltos, menos pantallas y pagos que se resuelven donde está la conversación. Si desarrollas bots de Telegram, actualiza la librería, prueba los widgets en un chat privado y deja las consultas con TON para una segunda fase. Descarga Telegram desde APKPure para probar el resultado en el cliente real antes de publicar.
