Panel de inteligencia de usuarios y análisis de grupos

Introducción

El sistema de inteligencia de usuarios y analítica de grupos proporciona información integral basada en datos sobre la salud de tu comunidad de Telegram, el comportamiento de los miembros y la eficacia de la moderación. Esta sofisticada plataforma de analítica va mucho más allá de simples recuentos de mensajes: ofrece análisis profundo del comportamiento, perfiles de evaluación de riesgos, capacidades de supervisión en tiempo real y desgloses estadísticos detallados que ayudan a los administradores a tomar decisiones de moderación bien fundamentadas.

A diferencia de las estadísticas básicas de grupo, que solo muestran métricas superficiales, el panel de inteligencia y analítica emplea técnicas avanzadas de ciencia de datos para revelar patrones, identificar posibles problemas antes de que escalen y proporcionar información accionable sobre usuarios individuales y sobre la dinámica general de la comunidad. El sistema combina análisis de datos históricos, flujos de eventos en tiempo real y modelos predictivos de riesgo para crear una visión completa del estado operativo de tu comunidad.

Este conjunto de funciones incluye informes de inteligencia de usuarios individuales (que muestran patrones de comportamiento, historial de infracciones y puntuaciones de riesgo de spam), paneles de estadísticas a nivel de grupo (que muestran métricas agregadas, desgloses de infracciones y patrones de interacción), feeds de castigos en directo (flujos en tiempo real de acciones de moderación en todos tus grupos) y acceso a API pública para la integración programática con herramientas externas.

Cómo funciona

Informes de inteligencia de usuarios

El sistema de inteligencia de usuarios mantiene perfiles de comportamiento detallados de cada usuario de tu comunidad. Cuando buscas a un usuario concreto por nombre, handle o Telegram ID, el sistema recupera su historial completo de interacciones, incluidos los mensajes enviados, las infracciones recibidas, la duración de los castigos, los patrones de pertenencia a grupos y las puntuaciones de riesgo calculadas.

El informe de inteligencia comienza con una evaluación integral del riesgo de spam calculada por el algoritmo AI Spam Intelligence. Esta valoración (de 0.0 a 1.0) refleja la probabilidad estadística de que el usuario sea un spammer o un actor malicioso, basándose en múltiples señales de comportamiento, como la tasa de infracciones, los niveles de confianza de las infracciones, las características del perfil y los patrones de interacción.

Debajo de la puntuación de riesgo, el sistema muestra estadísticas detalladas de infracciones con métricas de confianza (media, mediana, percentil 95), tasa de infracciones de alta confianza, tipos de infracción más comunes y motivos de infracción más habituales. Estas estadísticas ayudan a los administradores a entender no solo que un usuario infringió las normas, sino también con qué grado de confianza se detectaron esas infracciones y qué patrones caracterizan el comportamiento problemático del usuario.

El historial completo de infracciones aparece como una lista cronológica que muestra cada falta con su marca de tiempo, tipo de infracción (porno, contenido sexual, lenguaje tóxico, spam, badwords, etc.), nivel de confianza (0.0-1.0) y una explicación detallada del motivo que activó la detección. Esta transparencia permite a los administradores evaluar si las infracciones representan problemas reales o posibles falsos positivos.

Panel de estadísticas del grupo

El panel de estadísticas del grupo ofrece información agregada sobre la salud general de tu comunidad y la eficacia de la moderación. El sistema calcula y muestra varias categorías de métricas:

Métricas generales incluyen el estado del grupo (permitido/no permitido), el número total de miembros, el número de administradores, la verificación de presencia del bot y si el grupo tiene correctamente configurados una foto de perfil y un enlace de invitación.

Métricas de actividad muestran el total de mensajes enviados en el historial del grupo, el total de infracciones detectadas, el tiempo total de castigo aplicado (en minutos) y la relación entre estas cifras, indicando los niveles generales de cumplimiento de la comunidad.

Eficiencia de moderación calcula la tasa de castigos por cada 1,000 mensajes (mostrando con qué frecuencia se modera en relación con la actividad), la duración media de los castigos (indicando la gravedad típica de las infracciones) y la media de mensajes por miembro (indicador de participación).

Análisis temporal muestra la actividad durante periodos recientes (últimos 7 días, últimos 30 días), reflejando tendencias en infracciones y patrones de castigo que ayudan a identificar si tu comunidad se está volviendo más o menos problemática con el tiempo.

Desglose de infracciones clasifica todas las infracciones por tipo (contenido pornográfico, contenido sexual, lenguaje tóxico, spam, infracciones de idioma, lenguaje ofensivo, insultos, amenazas, badwords, mensajes reenviados, medios prohibidos, enlaces de invitación, bots no autorizados) con recuentos exactos para cada categoría. Este desglose revela qué normas se infringen con más frecuencia, lo que ayuda a decidir si determinadas restricciones deben endurecerse o relajarse.

Feed de castigos en vivo

El feed de castigos en tiempo real usa suscripciones WebSocket para transmitir eventos de moderación a medida que ocurren en todos los grupos donde tu bot está activo. Esta vista en vivo muestra los 20 castigos más recientes de todo el sistema (no se limita a tus propios grupos), indicando el usuario castigado, el tipo de infracción, el motivo detallado, la puntuación de confianza y la marca de tiempo.

El feed se actualiza instantáneamente cuando se producen nuevas infracciones en cualquier lugar del ecosistema monitorizado, ofreciendo una ventana en tiempo real a la actividad de moderación en curso. Esta transparencia ayuda a los administradores a:

• Supervisar campañas activas de spam que afectan a varias comunidades
• Observar el proceso de toma de decisiones del bot en tiempo real
• Identificar usuarios que infringen las normas en varios grupos
• Ver qué tipos de infracción son actualmente los más comunes
• Verificar que el sistema de moderación está funcionando activamente

Cada entrada de castigo es clicable, lo que te permite generar un informe completo de inteligencia de usuario sobre el infractor con un solo clic. Esto te permite investigar rápidamente cuando detectas patrones preocupantes en el feed.

Acceso a la API pública

El sistema de inteligencia de usuarios expone un endpoint público de API REST que permite a cualquiera consultar valoraciones de spam de usuarios de Telegram proporcionando su ID de usuario. La API devuelve la valoración de spam (0.0-1.0) y la categoría de nivel de riesgo (Bajo, Medio, Alto, Crítico) en formato JSON sin requerir autenticación.

Esta API pública permite integraciones de terceros, de modo que otros desarrolladores de bots, investigadores o moderadores de comunidades puedan incorporar los datos de inteligencia a sus propias herramientas y flujos de trabajo. La documentación de la API incluye ejemplos de código en varios lenguajes (cURL, JavaScript, Python) que muestran cómo realizar solicitudes y procesar respuestas.

Aunque la valoración de spam es pública, los historiales detallados de infracciones y los análisis de comportamiento siguen siendo privados, visibles únicamente para los administradores de los grupos donde el usuario consultado es miembro. Este equilibrio de privacidad proporciona información útil sobre riesgos al ecosistema más amplio de Telegram, al tiempo que protege la privacidad de cada usuario.

Configuración

Acceder a la inteligencia de usuarios

Para ver informes de inteligencia de usuarios individuales:

1. Ve a la sección "Inteligencia de usuarios" desde el menú principal de tu panel
2. Selecciona la pestaña "Inteligencia de usuarios" (primera pestaña)
3. Usa la interfaz de búsqueda para encontrar usuarios por:
   • Nombre completo o coincidencia parcial del nombre
   • Nombre de usuario de Telegram (con o sin el símbolo @)
   • ID de usuario de Telegram (numérico)
4. Haz clic en un usuario en los resultados de búsqueda para ver su informe de inteligencia completo
5. Revisa su calificación de spam, las estadísticas de infracciones y el historial completo de infracciones

La función de búsqueda funciona con todos los usuarios de los grupos en los que eres administrador, lo que te permite investigar a cualquier miembro de la comunidad cuyo comportamiento te preocupe.

Ver estadísticas del grupo

Para acceder al panel de analíticas de tu grupo:

1. Ve a la página de gestión de tu grupo desde el panel
2. Selecciona la pestaña "Estadísticas"
3. Elige la subpestaña "Estadísticas del grupo"
4. Revisa las métricas completas que se muestran en varias secciones:
   • Resumen (estado, miembros, configuración del bot)
   • Actividad (mensajes, infracciones, castigos)
   • Eficiencia de moderación (tasas, promedios, participación)
   • Actividad reciente (tendencias de 7 y 30 días)
   • Principales infracciones (desglose por tipo)
   • Marcas de tiempo (última actividad, última actualización)

Las estadísticas se actualizan en tiempo real a medida que llegan nuevos datos, para que siempre veas métricas actualizadas.

Acceder a estadísticas de usuarios dentro de los grupos

Para ver los miembros más activos de un grupo específico:

1. En la página de gestión de tu grupo, selecciona la pestaña "Estadísticas"
2. Elige la subpestaña "Estadísticas de usuarios"
3. Usa la función de búsqueda para filtrar usuarios por nombre, nombre de usuario, ID o contenido de la biografía
4. Revisa la lista que muestra los 50 usuarios más activos por número de mensajes
5. Cada tarjeta de usuario muestra:
   • Avatar (si está disponible)
   • Nombre y nombre de usuario
   • Recuento total de mensajes en este grupo
   • Marca de tiempo de la última vez que fue visto
6. Haz clic en cualquier usuario para ver su informe de inteligencia completo

Esta función ayuda a identificar a los miembros más participativos de tu comunidad y a detectar patrones de actividad inusuales (por ejemplo, usuarios con recuentos de mensajes muy altos pero sin participación visible podrían ser bots de spam).

Monitorear el feed de castigos en vivo

Para ver eventos de moderación en tiempo real:

1. Ve a "Inteligencia de usuarios" desde el menú principal del panel
2. Selecciona la pestaña "Castigos en vivo"
3. Observa el flujo de infracciones recientes, que muestra:
   • Avatar y nombre del usuario
   • Tipo de infracción y motivo detallado
   • Puntuación de confianza
   • Marca de tiempo (tiempo relativo transcurrido)
   • Indicador de estado de la conexión (muestra el estado de WebSocket)
4. Haz clic en cualquier entrada de castigo para ver el informe de inteligencia completo del infractor

El feed se vuelve a conectar automáticamente si se pierde la conexión, lo que garantiza una supervisión continua.

Usar la API pública

Para acceder mediante programación a las calificaciones de spam de los usuarios:

1. Ve a la pestaña "Inteligencia de usuarios" → "Documentación de API"
2. Revisa la URL y el formato del endpoint de la API
3. Copia los ejemplos de código proporcionados en el lenguaje que prefieras:
   • cURL (línea de comandos)
   • JavaScript (fetch API)
   • Python (biblioteca requests)
4. Sustituye el ID de usuario de ejemplo por el ID que quieres consultar
5. Ejecuta la solicitud para recibir una respuesta JSON que contiene:
   • spam_rating: Puntuación numérica (0.0-1.0)
   • risk_level: Cadena de categoría (Bajo/Medio/Alto/Crítico)

La API tiene límites de frecuencia para evitar abusos, pero permite volúmenes de consultas razonables para casos de uso legítimos.

Escenarios reales

Escenario 1: Investigar nuevos miembros sospechosos

Un administrador de una comunidad observa que varios miembros nuevos se unen al mismo tiempo y se pregunta si forman parte de una operación coordinada de spam. Con la búsqueda de Inteligencia de usuarios, el administrador consulta el perfil de cada nuevo miembro.

Los informes de inteligencia revelan que todos los nuevos miembros tienen:

• Puntuaciones de spam superiores a 0.70 (alto riesgo)
• Sin nombres de usuario de Telegram (señal de alerta en cuentas de spam)
• Pertenencia a más de 200 grupos con muy pocos mensajes por grupo (característica de bot)
• Fotos de perfil NSFW (táctica habitual de spam)

Con esta información, el administrador bloquea preventivamente las cuentas antes de que puedan publicar spam, evitando interrupciones en la comunidad. Sin los datos de inteligencia, el administrador habría tenido que esperar a que aparecieran los primeros mensajes de spam antes de tomar medidas.

Escenario 2: Evaluar informes de falsos positivos

Un miembro antiguo de la comunidad escribe a los administradores afirmando que fue silenciado injustamente por publicar un mensaje legítimo. Los administradores no tienen claro si el bot cometió un error o si el usuario se está quejando de una medida justificada.

Con el informe de Inteligencia de usuarios, los administradores ven:

• Puntuación de spam: 0.15 (muy baja, usuario de confianza)
• Una sola infracción en un historial de 6 meses
• Confianza de la infracción: 0.52 (límite, baja confianza)
• Tipo de infracción: análisis de sentimiento - detección de lenguaje ofensivo
• Motivo detallado: el mensaje contenía una palabra que activó un falso positivo

La baja puntuación de confianza y la única infracción respaldan la afirmación del usuario de que se trata de un falso positivo. Los administradores explican el proceso de detección automatizada, aclaran que la restricción fue de solo 1 minuto y tranquilizan al usuario indicando que su reputación general en la comunidad sigue siendo excelente (puntuación de spam de 0.15).

Escenario 3: Supervisar la eficacia de la moderación

Una comunidad ha endurecido recientemente varias reglas de moderación y quiere evaluar el impacto. Con el panel de Estadísticas del grupo, los administradores revisan:

• Tasa de sanciones: aumentó de 2.5 a 4.8 por cada 1K mensajes
• Duración media de las sanciones: estable en 3.2 minutos
• Infracciones totales (últimos 7 días): 45 (frente a 28 la semana anterior)
• Infracción principal: imágenes NSFW (18 infracciones)

Las estadísticas muestran que el escaneo de imágenes más estricto está detectando más contenido inapropiado (lo esperado), pero la tasa de sanciones sigue siendo razonable (solo el 0.48% de los mensajes infringe las reglas). Los administradores concluyen que la nueva configuración funciona según lo previsto sin moderar en exceso.

Escenario 4: Identificar patrones de spam entre grupos

Un administrador que supervisa el feed de sanciones en vivo observa que los mismos nombres de usuario aparecen repetidamente con infracciones similares (detección de patrones de spam, enlaces de invitación) en distintos grupos con pocos minutos de diferencia.

Este patrón indica una campaña coordinada de spam dirigida a varias comunidades al mismo tiempo. El administrador revisa el informe de Inteligencia de usuarios de uno de los spammers, confirma una puntuación de spam alta (0.85+) y luego busca nombres de usuario similares para identificar cuentas relacionadas.

Al bloquear de forma proactiva estas cuentas relacionadas en sus propios grupos antes de que la oleada de spam llegue a ellos, el administrador evita el ataque en lugar de reaccionar después de que aparezca el spam.

Escenario 5: Optimización de reglas basada en datos

Una comunidad de videojuegos revisa mensualmente sus Estadísticas del grupo para optimizar la configuración de moderación. Los datos de este mes muestran:

• Infracción principal: aplicación de reglas de idioma (35 infracciones)
• Segunda: lenguaje tóxico (12 infracciones)
• Infracciones NSFW: 2

La alta cantidad de infracciones por aplicación de reglas de idioma sorprende a los administradores: descubren que su comunidad se ha vuelto más internacional, con miembros que hablan varios idiomas, pero el bot sigue aplicando reglas de solo inglés.

A partir de esta información basada en datos, desactivan la aplicación de reglas de idioma, al reconocer que su comunidad ha evolucionado de forma natural hasta ser multilingüe. Las estadísticas les ayudaron a identificar una regla que ya no era adecuada para la composición actual de su comunidad.

Buenas prácticas

Auditorías periódicas de inteligencia

Programa revisiones semanales o mensuales de las métricas clave de inteligencia:

• Revisa el panel de estadísticas del grupo para detectar tendencias
• Consulta los principales infractores en las estadísticas de usuarios
• Examina la distribución de tipos de infracción para identificar patrones
• Supervisa las tasas y duraciones de las sanciones

Las auditorías periódicas te ayudan a detectar problemas emergentes a tiempo y a verificar que la configuración de moderación siga siendo adecuada a medida que tu comunidad evoluciona.

Investigar anomalías

Cuando notes patrones inusuales en los datos, investiga de inmediato:

• Un aumento repentino de infracciones podría indicar un ataque de spam o una configuración incorrecta
• Calificaciones de spam inusualmente altas para usuarios conocidos y confiables podrían indicar falsos positivos
• Un recuento alto de mensajes con poca interacción podría indicar bots
• Distribuciones inusuales de confianza en las infracciones podrían revelar problemas sistemáticos de detección

Los datos de inteligencia te ayudan a detectar estas anomalías; la investigación te ayuda a comprenderlas y abordarlas.

Usar la inteligencia para apelaciones de baneos

Cuando los usuarios soliciten que se les retire un baneo o apelen restricciones, usa los informes de inteligencia para tomar decisiones fundamentadas:

• Revisa su historial completo de infracciones (no solo el incidente más reciente)
• Examina las puntuaciones de confianza (las infracciones con baja confianza podrían ser falsos positivos)
• Comprueba la calificación de spam (0.2 o menos suele indicar un usuario legítimo)
• Considera los patrones de infracción (incidente aislado frente a problemas repetidos)

La evaluación de apelaciones basada en datos garantiza decisiones de moderación coherentes y justas.

Compartir información con coadministradores

Usa los paneles de estadísticas como herramienta de comunicación entre tu equipo de moderación:

• Comparte capturas de las estadísticas semanales en el chat de administradores
• Habla sobre las tendencias y si es necesario ajustar la configuración
• Coordina respuestas ante patrones de spam emergentes
• Construye conocimiento institucional sobre la dinámica de tu comunidad

La transparencia con tu equipo favorece una mejor moderación colectiva.

Usar la API pública para integraciones

Si gestionas varias comunidades o usas herramientas de moderación adicionales, integra la API pública:

• Consulta las calificaciones de spam antes de aceptar nuevos miembros
• Contrástalas con bases de datos externas de spam
• Crea paneles personalizados que combinen datos de varias fuentes
• Automatiza decisiones de moderación basadas en el riesgo

La API permite flujos de trabajo avanzados más allá de la interfaz web.

Supervisar periódicamente el feed en vivo

Haz que revisar el feed en vivo de sanciones forme parte de tu rutina habitual de administración:

• Comprueba de forma puntual que la aplicación de sanciones funcione correctamente
• Identifica a tiempo campañas coordinadas de spam
• Haz seguimiento de qué tipos de infracción son actualmente los más comunes
• Verifica que las puntuaciones de confianza coincidan con la calidad real del contenido

El feed en tiempo real proporciona conocimiento de la situación que las estadísticas diferidas no pueden ofrecer.

Integración con otras funciones

Base para la inteligencia antispam con AI

Los informes de inteligencia de usuarios aportan la transparencia que hace confiable a la inteligencia antispam con AI. Cuando la AI expulsa automáticamente a un usuario con una calificación de spam superior a 0.75, los administradores pueden revisar el informe de inteligencia para entender exactamente por qué se calculó esa calificación y comprobar que la decisión fue adecuada.

El historial de infracciones, las estadísticas de confianza y el análisis de comportamiento que se muestran en los informes de inteligencia son los datos sin procesar que alimentan el algoritmo de cálculo de riesgo de la AI. Esta integración crea un ciclo cerrado: la AI toma decisiones basadas en datos, y los administradores pueden auditar esas decisiones consultando esos mismos datos.

Complemento de la moderación manual

Aunque los sistemas automatizados gestionan la aplicación rutinaria de las normas, los datos de inteligencia ayudan a los administradores a tomar decisiones con más matices en casos límite:

• Las puntuaciones de spam en el límite (0.60-0.74) podrían justificar advertencias en lugar de expulsiones
• Las infracciones con baja confianza podrían merecer segundas oportunidades
• Los usuarios con un buen historial a largo plazo pero infracciones recientes podrían recibir orientación en lugar de ser castigados

El sistema de inteligencia proporciona el contexto que la automatización pura no puede ofrecer.

Amplificación de la detección de patrones

Los informes de inteligencia individuales muestran patrones a nivel de usuario, mientras que las estadísticas del grupo revelan patrones a nivel de comunidad:

• Que muchos usuarios infrinjan la misma regla sugiere que la regla podría ser demasiado estricta
• Las tasas altas de infracciones en horarios concretos indican cuándo se producen campañas de spam
• Los cambios en la distribución de los tipos de infracción muestran cómo evolucionan las tácticas de spam con el tiempo

Combinar ambas perspectivas crea una conciencia integral de los patrones.

Validación de la configuración de funciones

Usa las estadísticas para validar si los ajustes de tus funciones están funcionando como se esperaba:

• Si la detección de NSFW genera muchas infracciones, está detectando contenido (funciona)
• Si el análisis de sentimiento muestra cero infracciones a pesar de que el chat es tóxico, el umbral podría ser demasiado alto
• Si la detección de spam no detecta spam evidente, el umbral podría ser demasiado estricto

La validación basada en datos garantiza que las funciones estén configuradas de forma óptima para tu comunidad.

Uso avanzado

Análisis de correlación

Los administradores avanzados pueden correlacionar distintas métricas para obtener información útil:

• Tasa de sanciones vs. nivel de actividad: Los grupos con mucha actividad y bajas tasas de sanciones tienen culturas saludables
• Confianza de la infracción vs. tipo de infracción: Las infracciones NSFW con baja confianza podrían indicar un umbral demasiado sensible
• Calificación de spam del usuario vs. número de grupos a los que pertenece: Los usuarios presentes en muchos grupos y con calificaciones de spam altas probablemente sean spammers profesionales
• Patrones temporales: Las infracciones agrupadas en ciertos horarios podrían indicar campañas de spam dirigidas

Busca estas correlaciones para comprender patrones más profundos en la dinámica de tu comunidad.

Análisis de cohortes usando estadísticas de usuario

Haz seguimiento de cohortes específicas de usuarios para entender la salud de la comunidad:

• Nuevos miembros (se unieron en los últimos 30 días): ¿Qué porcentaje acumula infracciones?
• Principales colaboradores (alto número de mensajes): ¿Tienen calificaciones de spam bajas?
• Miembros inactivos (sin actividad reciente): ¿Están volviendo a participar o se están yendo?

El análisis de cohortes revela si tu comunidad está reteniendo miembros de calidad e integrando con éxito a los recién llegados.

Análisis de la distribución de confianza de las infracciones

El informe de inteligencia muestra la media, la mediana y el percentil 95 de confianza. Úsalos para entender la calidad de la detección:

• Media alta + mediana alta (ambas >0.7): Detecciones sólidas y confiables
• Media baja + percentil 95 alto: Detecciones mayormente débiles, con algunas sólidas ocasionales
• Desviación estándar alta (gran diferencia entre la media y el percentil): Calidad de detección inconsistente

Estos patrones te ayudan a evaluar si la configuración de moderación está produciendo resultados fiables.

Comparación con datos históricos

Haz seguimiento de métricas clave a lo largo del tiempo para establecer líneas base e identificar tendencias:

• ¿Cuál es tu tasa normal de sanciones por cada 1K mensajes?
• ¿Cuál es la distribución típica de infracciones (qué tipos son los más comunes)?
• ¿Cómo se ve la distribución de calificaciones de spam en tu comunidad?

Una vez establecidas las líneas base históricas, las anomalías se vuelven evidentes de inmediato.

Estratificación de riesgos

Clasifica a los usuarios en niveles de riesgo según sus calificaciones de spam:

• 0.00-0.30: Usuarios de confianza (verde)
• 0.31-0.60: Usuarios normales (amarillo)
• 0.61-0.74: Riesgo elevado (naranja)
• 0.75+: Alto riesgo (rojo, expulsión automática si AI está habilitada)

Aplica distintas políticas de supervisión o aplicación de normas a cada nivel. Por ejemplo, los usuarios con riesgo elevado podrían recibir una escalada más rápida hacia restricciones, mientras que los usuarios de confianza podrían recibir un trato más flexible ante infracciones dudosas.

Implementación técnica

El sistema User Intelligence funciona como parte del microservicio telegram_intelligence, que mantiene una base de datos actualizada de forma continua con perfiles de comportamiento derivados de eventos de infracción, estadísticas de mensajes, datos de pertenencia a grupos e información de perfil.

El cálculo de la calificación de spam emplea un modelo estadístico que combina la teoría de probabilidad bayesiana con curvas de riesgo logísticas. El algoritmo pondera múltiples factores, entre ellos la tasa de infracciones (infracciones / mensajes), las distribuciones de confianza (media, mediana, percentil), la prevalencia por tipo de infracción, las señales de comportamiento (características del perfil, patrones de pertenencia a grupos) y factores de reputación (estado de administrador, niveles de interacción).

Las estadísticas de grupo se calculan mediante consultas de agregación a la base de datos que suman infracciones, recuentos de mensajes, duraciones de sanciones y otras métricas en todos los eventos registrados del grupo. Las consultas emplean indexación y caché eficientes para garantizar que los tiempos de carga del panel sigan siendo rápidos incluso en grupos con un historial extenso.

El feed de sanciones en vivo utiliza suscripciones GraphQL a través de conexiones WebSocket, transmitiendo eventos en tiempo real desde la tabla tg_punishments a medida que se insertan nuevas filas. La consulta de suscripción incluye un límite (las 20 sanciones más recientes) y ordena por marca de tiempo de creación en orden descendente para mostrar primero los eventos más recientes.

El endpoint público de la API proporciona una interfaz REST sencilla que acepta parámetros de ID de usuario y consulta la base de datos de inteligencia para obtener la calificación de spam correspondiente. El formato de la respuesta sigue las convenciones estándar de JSON con encabezados CORS adecuados para permitir solicitudes entre orígenes desde aplicaciones web.

Todos los datos de inteligencia se almacenan en la base de datos PostgreSQL con índices adecuados en los campos consultados con frecuencia (user_id, group_id, created_at, violation_type), lo que garantiza una recuperación rápida incluso a medida que el conjunto de datos crece hasta alcanzar millones de registros.

Privacidad y gestión de datos

El sistema de User Intelligence procesa y almacena:

• Registros de infracciones: Tipo, marca de tiempo, nivel de confianza, detalles
• Estadísticas de mensajes: Recuentos por usuario y por grupo
• Pertenencia a grupos: A qué grupos pertenecen los usuarios
• Información de perfil: Estado NSFW, presencia de nombre de usuario, contenido de la biografía (si se analiza)
• Métricas calculadas: Calificaciones de spam, estadísticas de confianza

Todos los datos se derivan de información disponible a través de la API de Telegram o se generan mediante las acciones de moderación del bot. El sistema no accede directamente al contenido de los mensajes: recibe informes de infracciones de sistemas de análisis de contenido que ya han escaneado los mensajes según la configuración de moderación establecida.

Las protecciones de privacidad incluyen:

• Control de acceso: Solo los administradores de grupo pueden ver información detallada de los usuarios en sus grupos
• Limitaciones de la API: La API pública solo proporciona la calificación de spam, no el historial detallado de infracciones
• Minimización de datos: Los registros de infracciones almacenan el tipo de infracción y el nivel de confianza, no el contenido completo del mensaje
• Anonimización: Las estadísticas agregadas no revelan la identidad de usuarios individuales

Los usuarios no pueden optar por excluirse del análisis de su comportamiento (ya que esto permitiría a los spammers eludir la detección), pero sus historiales detallados permanecen privados para los administradores de sus grupos. La exposición limitada de datos de la API pública equilibra la protección de la comunidad (al compartir información de riesgo) con la privacidad individual (al proteger los detalles de las infracciones).

Solución de problemas

"No se encuentra un usuario específico en la búsqueda de inteligencia"

Posibles causas:

• El usuario no ha interactuado con ningún grupo en el que esté presente tu bot
• Se está buscando con un formato de nombre/handle incorrecto
• El usuario se unió recientemente y aún no se ha indexado por completo

Solución: Los usuarios solo aparecen en la búsqueda si han estado activos en grupos supervisados por el bot. Asegúrate de buscar por el handle exacto de Telegram (prueba con y sin el símbolo @) o por el ID numérico de usuario. Los usuarios nuevos pueden tardar unos minutos en indexarse por completo después de su primera actividad.

"Las estadísticas del grupo muestran cero infracciones pese a que se conocen incumplimientos de las reglas"

Posibles causas:

• Las infracciones ocurrieron antes de que el bot se añadiera al grupo
• La función que detectaría las infracciones no está activada
• Las infracciones están ocurriendo, pero no se registran correctamente

Solución: Comprueba que las funciones de moderación relevantes estén realmente activadas en la configuración. Revisa los informes de inteligencia de usuarios individuales de los infractores conocidos para verificar que sus infracciones se estén registrando. Las estadísticas solo incluyen infracciones detectadas por el bot, no problemas preexistentes.

"El feed de castigos en directo muestra el estado 'desconectado'"

Posibles causas:

• Se perdió la conexión WebSocket debido a un problema de red
• La pestaña del navegador estuvo inactiva durante un periodo prolongado
• Mantenimiento o reinicio del servidor

Solución: El feed debería reconectarse automáticamente en un plazo de 30 segundos. Si sigue desconectado, actualiza la página. Comprueba el indicador de estado de conexión: si muestra "conectado" pero no aparecen castigos, esto podría indicar un periodo sin infracciones (algo normal durante momentos de poca actividad).

"Las puntuaciones de spam parecen más bajas de lo esperado para spammers evidentes"

Posibles causas:

• El spammer aún no ha acumulado suficientes infracciones
• Las infracciones tienen puntuaciones de confianza bajas
• El spammer tiene señales positivas de reputación que compensan las infracciones

Solución: Las puntuaciones de spam reflejan la probabilidad estadística basada en los datos acumulados. Los spammers nuevos con pocas infracciones no tendrán puntuaciones altas hasta que establezcan un patrón. Revisa su informe de inteligencia para ver las puntuaciones de confianza: si las infracciones tienen una confianza baja (0.50-0.60), el algoritmo asigna adecuadamente un riesgo menor. La puntuación aumentará a medida que se acumulen más infracciones de alta confianza.

"La API pública devuelve un error o una respuesta vacía"

Posibles causas:

• Formato de ID de usuario no válido
• El usuario nunca ha interactuado con grupos supervisados por el bot
• Se activó la limitación de tasa

Solución: Asegúrate de proporcionar un ID numérico válido de usuario de Telegram, no un nombre de usuario ni un handle. La API solo devuelve datos de usuarios que han estado activos en grupos donde opera el bot. Si haces muchas solicitudes, reduce la velocidad para evitar límites de tasa (máximo 100 solicitudes por minuto por IP).

"User Statistics muestra menos de 50 usuarios pese a que el grupo es más grande"

Posibles causas:

• Muchos miembros tienen cero mensajes
• Hay un filtro de búsqueda activo que limita los resultados
• Los miembros inactivos no se incluyen en la lista de principales colaboradores

Solución: La lista de Users Statistics solo muestra usuarios que han enviado al menos un mensaje, ordenados por número de mensajes. Los miembros que se unieron pero nunca participaron no aparecerán. Borra cualquier filtro de búsqueda activo para ver la lista completa. El recuento solo incluye participantes activos, no el total de miembros.

Conclusión

El sistema de inteligencia de usuarios y analíticas de grupos te ofrece visibilidad sobre la dinámica de tu comunidad, el comportamiento de los miembros y la eficacia de la moderación. Combina perfiles de comportamiento individuales con estadísticas agregadas, supervisión en tiempo real y acceso público a la API.

Tanto si necesitas investigar a un usuario sospechoso, evaluar si tu configuración de moderación está funcionando correctamente, supervisar campañas de spam en curso en tiempo real o integrar datos de inteligencia en herramientas externas, el panel de analíticas te proporciona la información que necesitas para tomar decisiones fundamentadas con rapidez y confianza.

La transparencia de los informes de inteligencia garantiza que las decisiones de moderación automatizada sigan siendo auditables y explicables: los administradores siempre pueden revisar exactamente por qué un usuario recibió una determinada calificación de spam o qué infracciones contribuyeron a una medida de aplicación. Esta responsabilidad hace que la moderación automatizada sea confiable y ayuda a los administradores a mantener la confianza de la comunidad incluso cuando se aplican medidas de cumplimiento.

Usados de forma habitual, estos informes te permiten moderar de manera proactiva en lugar de reactiva: revisar las calificaciones de spam y el feed de sanciones permite detectar problemas antes de que se propaguen, y el registro de auditoría mantiene cada decisión automatizada disponible para su revisión.