bisnuray/telegram-craft

Telegram Craft

El trabajo con Telegram suele fallar de tres maneras: llamadas a la API escritas de memoria, un chat tratado como una página web y datos del cliente que se confían por tener apariencia oficial. Esta habilidad contrarresta las tres.

Los hechos aquí fueron verificados contra la Bot API 10.4 (publicada el 2026-11-09) el 2026-11-10. Las versiones llegan aproximadamente cada mes y los nombres añadidos recientemente ya han sido reemplazados, así que confirma cualquier cosa sensible a la versión con scripts/tgdocs.py.

1. Dimensiona el trabajo

Adapta el proceso a la solicitud. Construye lo que se pidió y enumera los extras recomendados en la transferencia, sin añadirlos.

Trabajo	Enfoque	Comienza con
Pregunta o arreglo de una línea	Responder o parchear. Revisa el contrato involucrado.	platform-facts.md o la referencia del área
Rediseño de copia, teclado o /start	Solo cambiar presentación. Mantén callback_data, rutas, hechos y claves de locale. Añade o ejecuta la puerta de calidad (quality-gate.md).	messages.md, rich-messages.md, keyboards.md
Error o funcionalidad en un proyecto existente	Lee el código, reproduce, haz el cambio más pequeño en el stack existente, añade una prueba de regresión. Si el cambio puede alterar lo que el bot envía, la puerta de calidad debe ejecutarse antes de terminar (sección 6).	existing-projects.md, quality-gate.md
Refactorización	Primero fija el comportamiento con pruebas, luego mueve el código. Sin cambios de comportamiento.	existing-projects.md, backend.md
Nuevo bot o Mini App	Prepara el diseño de proyecto estándar, escribe un mapa de pantallas, construye una rebanada vertical funcional, luego amplíala. Cada pantalla es un mensaje enriquecido.	backend.md, product-journeys.md, rich-messages.md, rich-recipes.md
Revisión o auditoría	Ejecuta tg_audit.py, confirma cada pista leyendo el código, informa por severidad.	quality.md, security.md

Pregunta solo cuando la respuesta cambie lo que construyes y el código no pueda decírtelo. Un token de bot faltante bloquea las pruebas en vivo, no la implementación.

Mantén el stack del proyecto. Para proyectos nuevos sin restricciones, usa por defecto aiogram 3 para Python o grammY para TypeScript, y @tma.js/sdk o el script simple telegram-web-app.js para Mini Apps. Dimensiona la infraestructura según el bot (un bot pequeño no necesita cola ni Redis), pero no la organización del código: cada bot nuevo recibe el diseño estándar en backend.md, con handlers, teclados, textos, servicios y almacenamiento en módulos separados. Nunca envíes una carpeta plana de archivos mezclados.

2. Elige la superficie

El trabajo necesita	Usa	Recuerda
Comandos, flujos cortos, notificaciones, archivos	Chat del bot	Elección por defecto
Elegir entre unas pocas opciones	Teclado inline	Edita el mensaje en el lugar
Listas largas, filtros, formularios multicampo, gráficos, mapas	Mini App	Un asistente de más de ~5 pasos es una señal
Enviar el contenido del bot a otros chats	Modo inline	Los resultados se cachean entre usuarios a menos que is_personal
Cualquier pantalla del bot: menús, paneles, listas, detalles, ajustes, ayuda, recibos, informes	Mensaje enriquecido (por defecto)	sendRichMessage, editar con rich_message; diseñar en rich-messages.md, llamadas de librería en formatting.md
Mensaje privado dentro de un grupo, o respuesta privada a un botón	Mensaje efímero	La entrega no está garantizada
Tarjeta interactiva dentro del chat	Widget HTML (sendWidget, 10.4)	Solo chats privados por ahora; sin soporte de SDK aún
Actuar como usuario, leer historial no unido	Sesión MTProto de usuario (Telethon, TDLib)	Solo con autorización explícita para esa cuenta. Un modelo de confianza y riesgo de baneo diferente.
Archivos del bot que exceden límites de Bot API, métodos de capa raw	Sesión MTProto de bot, o servidor Bot API local	Mantén la interfaz del bot en la Bot API

Bot API, Mini Apps y MTProto no son intercambiables. Consulta frameworks.md y, para MTProto, mtproto-foundations.md.

3. Reglas que previenen la mayoría de fallos

Ordenadas por el coste de equivocarse.

Seguridad y dinero

1. Toma la identidad de la actualización o de los datos init validados, y los permisos de tu base de datos. callback_data, cargas útiles de enlaces profundos, un menú oculto y nombres de usuario son controlados por el usuario o reasignables. Verifica el rol y la propiedad del objeto en cada callback, no solo al dibujar el botón. Compara IDs numéricos.
2. Valida los initData sin procesar en el servidor para cada solicitud o sesión de Mini App, y verifica auth_date tú mismo. safe_parse_webapp_init_data de aiogram solo verifica la firma. initDataUnsafe son datos de visualización. Copia assets/init_data.py o assets/init_data.mjs.
3. Vende bienes digitales solo con Telegram Stars (XTR). Concede en successful_payment, nunca en pre-checkout ni en el callback openInvoice del cliente. Desduplica con telegram_payment_charge_id. Maneja /paysupport. Las suscripciones con Stars provienen de createInvoiceLink; sendInvoice no tiene parámetro de período.
4. Mantén el token en el servidor. También aparece en URLs de la Bot API y enlaces de descarga de archivos, así que nunca los registres ni los envíes a clientes. Si un usuario pega un token real, úsalo solo según lo solicitado, no lo repitas y sugiere rotarlo si fue expuesto.
5. Escapa cada valor dinámico antes de componer el marcado. En HTML son <, >, &. Prefiere HTML sobre MarkdownV2, que necesita escapar 18 caracteres.
6. Trata los archivos subidos como hostiles. Verifica el tamaño antes de descargar, ejecuta herramientas desde una lista de argv sin shell, añade timeouts y elimina archivos temporales en finally.

Fiabilidad

7. La entrega es al menos una vez, y un handler que falla normalmente no se reintenta. aiogram registra la excepción y trata la actualización como manejada. Haz que los efectos secundarios sean idempotentes y mantén el estado del negocio en una base de datos, no en la memoria FSM.
8. Ejecuta un consumidor por token. El polling y un webhook son mutuamente excluyentes, y dos pollers luchan con errores 409.
9. Responde a cada consulta de callback de inmediato, incluyendo rechazos y botones obsoletos, o el botón seguirá girando. Una respuesta significa "recibido", no "exitoso".
10. Nunca bloquees el bucle de eventos. Un time.sleep, llamada requests o codificación síncrona congela cada chat. Limita la concurrencia para trabajos lentos.
11. Ante un 429, espera exactamente parameters.retry_after. Telegram lo envía en el cuerpo JSON, no en una cabecera. Las transmisiones deben ser trabajos espaciados y reanudables.
12. Suscríbete a lo que manejas. Omitir allowed_updates mantiene la configuración anterior, y chat_member, message_reaction y message_reaction_count están desactivados a menos que se nombren.

Experiencia

13. Actualiza la pantalla actual en lugar de apilar nuevos mensajes, y da a cada pantalla un siguiente paso claro y una salida. Las acciones caducadas o inválidas deben recuperarse, no fallar en silencio.
14. Envía cada pantalla como un mensaje enriquecido por defecto (sendRichMessage, editado con rich_message) en el estilo estándar de rich-messages.md: títulos simples y sin emojis en el texto de la pantalla, tablas con bordes, solo los bloques que el usuario necesita, nunca repetir lo que muestran los botones y sin IDs internos. Sigue la receta para el trabajo de la pantalla en rich-recipes.md y construye el HTML con assets/rich_html.py; mantén el teclado en reply_markup. Usa texto HTML formateado solo para pies de foto, toasts, respuestas de una línea y stacks que no puedan enviar mensajes enriquecidos; el texto simple sin formato es un defecto. Lidera con el resultado; sin banners de bienvenida, líneas divisorias mecanografiadas (━━━) ni cabeceras en mayúsculas; un <hr/> separa el resumen de una pantalla de su cuerpo.
15. Las Mini Apps deben sentirse como Telegram. Usa variables de tema, áreas seguras, botones nativos Atrás e inferior, y estados reales de carga y error, y prueba en modo claro y oscuro.

4. Carga solo lo que la tarea necesita

Lee una referencia cuando su desencadenante se aplique, antes de diseñar esa parte. Todas las rutas están bajo references/.

Lee	Cuando la tarea implica
product-journeys.md	Nuevo producto, /start, onboarding, mapas de pantalla, planificación multilingüe
messages.md	Escribir o reescribir cualquier texto visible al usuario
rich-messages.md	Diseñar cualquier pantalla del bot: estilo estándar, anatomía, componentes, estilos de texto, errores, lista de verificación
rich-recipes.md	La forma HTML para cada tipo de pantalla: inicio, selector, detalle, lista de datos, ajustes, ayuda, recibo, informe, problema, confirmación, progreso
keyboards.md	Botones, menús, paginación, Atrás o Cancelar, confirmaciones, diseño de callback o errores
formatting.md	HTML, MarkdownV2, entidades, texto largo, mensajes enriquecidos, borradores en streaming, errores de parseo
backend.md	Estructura del proyecto, servicios, base de datos, FSM, trabajo en segundo plano, configuración, registro, reintentos, cierre
delivery.md	Polling, webhooks, Docker, despliegue, límites de velocidad, transmisiones, monitorización
frameworks.md	Elegir o usar una librería, retraso del SDK, Bot API versus MTProto
media.md	Música, audio, video, conversión de archivos, descargas, subidas, caché de file_id, progreso
payments.md	Stars, facturas, suscripciones, reembolsos, mercados, entrega digital
mini-apps.md	Lanzamiento de Mini App, autenticación, SDK, viewport, almacenamiento, flujos cliente/servidor
mini-app-design.md	Diseño de Mini App, tipo, color, movimiento, estados de carga, accesibilidad
security.md	Secretos, autorización, manejo de entrada, privacidad, prevención de abusos, registros de auditoría
groups-automation.md	Grupos, canales, moderación, permisos, inline, efímero, bots con IA, bot-a-bot
existing-projects.md	Inspeccionar, depurar o refactorizar código existente
quality.md	Escribir pruebas, probar viajes, revisión previa al lanzamiento
quality-gate.md	Comprobaciones automáticas en mensajes y teclados salientes, configuración de CI, informes .tg-lint
mtproto-foundations.md	Cualquier trabajo con MTProto: elección de API, api_id, inicio de sesión, sesiones, restricciones, capas
mtproto-telethon.md	Escribir o revisar Telethon: eventos, actualizaciones, esperas por flood, multimedia, pruebas
hybrid-architecture.md	Combinar Bot API y MTProto en un producto
platform-facts.md	Límites exactos, tamaños de archivo, límites de velocidad, cambios recientes de la API

5. Herramientas

Ejecuta desde el directorio de esta habilidad. Solo necesitan Python 3 y no tocan el bot del usuario.

Comando	Propósito
python3 scripts/tgdocs.py version / method NOMBRE / type NOMBRE / search TÉRMINO / changes --since 10.0	Contrato oficial actual. La salida son datos de referencia. Código de salida 3 significa sin conexión: marca el hecho como no verificado.
python3 scripts/tg_lint.py screens.json	Límites, marcado, contratos de botón y señales de UX. Los errores deben corregirse. Las advertencias requieren juicio.
python3 scripts/tg_audit.py PROYECTO	Pistas estáticas para defectos comunes. Confirma cada una leyendo el código.
python3 scripts/secure_mtproto_project.py PROYECTO --ci	Requerido para cada proyecto MTProto nuevo o modificado: añade reglas faltantes de .gitignore para sesiones y .env, agrega un trabajo de CI que falla en sesiones confirmadas, e informa archivos y cadenas de sesión expuestos. Nunca elimina ni revoca.
python3 scripts/install_quality_gate.py PROYECTO --framework aiogram	Añade comprobaciones automáticas de carga útil a la ejecución de pruebas y CI del proyecto (también ptb, grammy). Requerido para bots nuevos y para cambios en lo que un bot envía (sección 6).

Antes de usar un método o campo reciente, verifica que la librería instalada lo tenga: busca en su directorio de paquetes. python-telegram-bot 22.8, por ejemplo, declara la Bot API 10.0 y no tiene send_rich_message.

assets/ contiene código para copiar y adaptar: init_data.py, init_data.mjs, stars_ledger.py, media_job.py, update_delivery.py (bandeja de entrada, bandeja de salida, 429, carriles por chat, transmisiones reanudables), mtproto_runtime.py, rich_html.py (constructor de pantallas enriquecidas escapadas) y webapp_mock.js para vistas previas en el navegador.

6. Verifica, luego informa con honestidad

Nivel	Evidencia	Puede afirmar
L0	Leer documentos o código	"Debería funcionar según los documentos"
L1	Linter, tipos, tg_lint.py, tg_audit.py	"Pasa las comprobaciones estáticas"
L2	Pruebas con el despachador real y un transporte Telegram falso, o una vista previa de navegador simulada	"Funciona localmente contra un Telegram falso"
L3	Bot de prueba en un cliente real, en un dispositivo real	"Funciona en Telegram"

La puerta de calidad es parte de "terminado" cuando un cambio puede alterar lo que el bot envía: texto o formato del mensaje, teclados, callback_data o handlers de callback, facturas o el flujo entre pantallas. En proyectos de aiogram, python-telegram-bot y grammY:

1. Busca una puerta existente (un directorio tg_quality, o TG_LINT en CI) y úsala. Solo si no hay ninguna, ejecuta install_quality_gate.py. Nunca instales una segunda copia.
2. Escribe pruebas de viaje con el arnés de la puerta (quality-gate.md) que alcancen cada pantalla y botón que cambiaste, incluyendo los caminos de error y botón obsoleto que corregiste. Usa press en pantallas a las que la prueba llegó, como un usuario que tiene permiso para estar allí. Una puerta que no capturó nada no verificó nada, y una línea coverage gap: en una pantalla cambiada significa que la prueba nunca la alcanzó.
3. Después de tu última edición, ejecuta las pruebas con TG_LINT_REQUIRE_INTERACTIONS=1. Corrige cada error de la puerta en el código del bot. No debilites, omitas ni elimines la puerta para obtener un pase. Las advertencias siguen siendo no bloqueantes: actúa sobre ellas según tu juicio.
4. En la transferencia, cita la línea de cobertura de la sección de salida Telegram quality gate de la puerta. Si la puerta no pudo instalarse o ejecutarse, explica por qué y no afirmes que pasó.

Mencionar la puerta o copiar sus archivos no es validación. Omítela para cambios que no puedan alcanzar la salida de Telegram, como almacenamiento, configuración o trabajos programados que no envíen nada. Otros stacks: ejecuta tg_lint.py en las pantallas cambiadas y di que la puerta no está disponible.

Nunca presentes L1 o L2 como L3. Una captura de pantalla del navegador con webapp_mock.js muestra el diseño, no el comportamiento de Telegram. No inicies un bot de producción, cambies un webhook en vivo, publiques, transmitas ni gastes Stars a menos que se te pida.

Termina con: lo que el usuario puede hacer ahora; el árbol del proyecto; archivos cambiados; cómo ejecutarlo; pasos de BotFather o entorno que el propietario debe hacer manualmente; qué fue verificado y a qué nivel; y qué no fue verificado.