1Moderación que dialoga con el resto de tu infraestructura
Un bot de moderación que vive por completo dentro de Telegram es útil, pero también es una isla. Las decisiones que toma —cada mensaje que elimina, cada usuario que verifica, cada raid que repele— quedan encerradas en una ventana de chat a menos que alguien abra Telegram para mirar. Para una sola comunidad, está bien. Para un equipo que gestiona la moderación como parte de una operación más grande, significa que el único sistema que más sabe sobre quién abusa de tus espacios es el único sistema que no puede comunicarse con nada más de lo que utilizas.
La API REST pública y los webhooks cierran esa brecha. Convierten a Telm de un bot autónomo en un componente que puedes conectar con las herramientas que ya tienes: tu sistema de monitorización y guardias, tu archivo de cumplimiento, tu propio producto, tus paneles internos. El mismo motor que protege tus grupos pasa a ser algo que tus otros sistemas pueden consultar, escuchar y controlar.
Esta guía repasa lo que la API y los webhooks exponen realmente —los endpoints, los eventos, el modelo de seguridad— y las cosas concretas que los equipos construyen con ellos. Todo lo que sigue es una capacidad real disponible hoy; no hay ningún SDK que esperar ni nada descrito aquí que el producto solo tenga previsto hacer.
2La API REST y tus claves
La API se encuentra en `https://api.telm.com/api/public/v1`. Es una interfaz REST sencilla: la llamas con solicitudes HTTPS y JSON corrientes, desde cualquier lenguaje, sin necesidad de una biblioteca cliente especial. Si tu código puede hacer una solicitud HTTP, puede comunicarse con Telm.
La autenticación se hace mediante clave de API. Creas las claves en el panel, en Ajustes → API y Webhooks, y cada una se te muestra exactamente una vez al crearla; cópiala a tu gestor de secretos en ese momento, porque después ya no se puede recuperar. Las claves llevan el prefijo `tk_live_` para que sean fáciles de reconocer en logs y configuración. Cada clave tiene un ámbito —lectura o escritura—, de modo que un servicio que solo necesita extraer el registro de decisiones puede tener una clave de solo lectura, mientras que una automatización que cambia ajustes recibe una clave de escritura. Genera una clave por sistema, y revocar una clave filtrada o retirada nunca afecta a las demás.
El uso se rige por una cuota diaria de solicitudes ligada a tu plan, de modo que el rendimiento es predecible y un script descontrolado no puede agotarlo todo. La comprobación más ligera —el análisis de spam en texto— está disponible en todos los planes dentro de esa cuota; la superficie más completa, desde el registro de decisiones hasta la gestión de ajustes y los webhooks, forma parte de los planes Pro y Business. Las cifras exactas se detallan al final.
3Verificar textos y usuarios bajo demanda
Dos endpoints te permiten aplicar el criterio de Telm bajo demanda, desde tu propio código, sin que ningún mensaje pase por un grupo de Telegram.
`POST /spam/check` envía un fragmento de texto a través del mismo motor de producción que protege tus comunidades —las señales compartidas sobre spammers, las reglas de patrones, los clasificadores— y devuelve un veredicto. Es la única llamada disponible en todos los planes, lo que la convierte en un filtro de spam natural para tu propio producto: filtra comentarios, biografías de registro, tickets de soporte o anuncios de un marketplace con la misma detección que protege tus espacios de Telegram. Añade `include_ai` para incorporar un veredicto de IA en los casos más difíciles y ambiguos (disponible en Pro y Business), y en esos planes puedes agrupar hasta veinte textos en una sola solicitud en lugar de llamar una vez por elemento.
`POST /users/check` verifica a una persona en lugar de un mensaje. Combina la lista de bloqueo global de CAS y el propio conjunto de datos de Telm, construido a partir de la moderación en muchas comunidades, y devuelve un nivel de riesgo (en Pro y Business) para que decidas cuánta fricción aplicar: dejar pasar directamente una cuenta limpia o retener una arriesgada para revisión. Integrarlo en tu propio onboarding te permite detectar a un actor malicioso conocido en la puerta de tu sitio web o app, no solo después de que se haya unido a un grupo de Telegram.
Ambas llamadas responden en línea: envías el texto o el usuario y recibes la evaluación en la respuesta. No hay ninguna cola que consultar ni ninguna devolución de llamada que esperar: la decisión llega con la respuesta.
4Recibir el aviso en el momento en que ocurre
Consultar el registro de moderación está bien para archivar, pero cuando quieres *reaccionar* a algo en el instante en que ocurre, quieres que te lo envíen, no preguntar. Los webhooks (en Pro y Business) hacen exactamente eso: registras un endpoint y Telm le envía una solicitud HTTP en el momento en que se dispara un evento relevante. Los eventos cubren los momentos que importan: `spam.detected` y `message.suspicious` para el contenido, y `user.banned`, `user.kicked`, `user.muted`, `user.joined` y `user.left` para la membresía.
El uso obvio es convertir una ola de spam en una alerta. Apunta `spam.detected` a tu sistema de monitorización o de guardias y un pico repentino se convierte en un aviso para quien esté de turno, en el mismo lugar donde llegan tus demás incidentes: nadie tiene que estar mirando Telegram para notar que empieza un ataque. El mismo flujo alimenta paneles en tiempo real, mantiene un sistema externo sincronizado con los baneos o dispara cualquier flujo de trabajo que quieras.
Como estas solicitudes llegan desde el mundo exterior a tu infraestructura, cada entrega va firmada. Cada solicitud lleva una cabecera `X-Telm-Signature` con la forma `v1=hex(hmac_sha256(secret, "timestamp.body"))`: un HMAC-SHA256 sobre la marca de tiempo y el cuerpo en bruto, con una clave secreta que solo tú y Telm compartís. Volver a calcular esa firma en tu lado demuestra que la solicitud vino realmente de Telm y no fue falsificada ni manipulada en tránsito; la marca de tiempo te permite rechazar reenvíos caducados. Verifica la firma antes de confiar en el payload: son unas pocas líneas de código y el paso más importante de un receptor de webhooks seguro.
5Una entrega en la que puedes confiar
Un modelo push solo es fiable si sabe manejar los momentos en que tu endpoint está lento, reiniciándose o brevemente caído, y el de Telm lo hace. La entrega es al menos una vez: cada evento lleva un `id` estable, y Telm sigue intentándolo hasta que tu endpoint lo confirma. Como «al menos una vez» significa que el mismo evento puede llegar legítimamente dos veces, deduplica por ese `id` —registra los que ya has procesado e ignora las repeticiones— y tu procesamiento seguirá siendo correcto sin importar cuántas veces se reintente una entrega.
Los reintentos siguen una programación que se va ampliando en lugar de martillear un endpoint con problemas: de inmediato, y luego tras un minuto, cinco minutos, treinta minutos, dos horas y seis horas; seis intentos en total, espaciados para dar margen a un servicio que se está recuperando. Si un endpoint sigue averiado —veinte fallos consecutivos y setenta y dos horas sin ninguna entrega correcta—, Telm deja de enviarle automáticamente y te avisa en Telegram, de modo que una URL muerta se convierte en una advertencia clara para arreglar tu receptor en lugar de una avalancha silenciosa de fallos acumulándose.
Para afinar una nueva integración, no tienes que provocar eventos reales para probarla. Un ping de prueba te permite lanzar una entrega de muestra a tu endpoint bajo demanda y confirmar que tu comprobación de firma y tu manejador funcionan, y un historial de entrega muestra qué se envió y cómo fue cada intento, de modo que puedes depurar un receptor que se comporta mal a partir del registro en lugar de adivinar.
6Un registro consultable de cada decisión
Todo lo que decide el motor queda registrado, y `GET journal` entrega ese registro a tu código. Cada entrada es una decisión: el veredicto, la puntuación que lo respalda, qué reglas se activaron y la acción que siguió. Como usa paginación por cursor, puedes recorrer todo el historial de forma fiable —página tras página, sin huecos ni duplicados— y llevarlo a donde guardes tus registros.
Eso convierte al registro de moderación en la columna vertebral de un archivo de cumplimiento. Los equipos que tienen que demostrar por qué se expulsó a un miembro —por una política de plataforma, un contrato con un cliente o un regulador— exportan el registro a su propio almacén a largo plazo de forma programada, lo que les da un relato independiente y consultable de cada acción de moderación que no depende de desplazarse hacia atrás en Telegram. Es la misma evidencia que el registro de auditoría del panel presenta a las personas, puesta a disposición de tus sistemas.
Junto a él, un endpoint de analítica devuelve series día a día —volúmenes y tendencias a lo largo del tiempo— para que puedas graficar la carga de moderación en tus propias herramientas de inteligencia de negocio junto a todo lo demás que sigues, en lugar de leerla en una pantalla. Tanto el registro de moderación como la analítica forman parte de los planes Pro y Business.
7Gestionar muchos grupos desde el código
La API no solo lee y escucha: también escribe. En Pro y Business puedes hacer `PATCH` sobre los ajustes de un grupo y ejecutar operaciones completas de crear/leer/actualizar/eliminar sobre sus reglas y su lista blanca, todo de forma programática. Cualquier cosa que configurarías a mano en el panel, la puedes configurar desde un script.
Eso es lo que hace práctico gestionar la moderación a escala. Una agencia o un gran operador que gestiona decenas de comunidades no quiere abrir cada una y repetir los mismos cambios a golpe de clic; quiere definir la política una vez y aplicarla en todas partes. Con la API despliegas una nueva regla, ajustas un umbral o añades una dirección a cada lista blanca de toda la flota en una sola pasada automatizada, y mantienes los grupos sincronizados a medida que evolucionan tus estándares.
También permite que la política de moderación viva en tu propio control de versiones. Mantén la configuración deseada como código, aplícala a través de la API, y cada cambio en cómo se gobiernan tus grupos queda revisado y versionado como el resto de tu infraestructura: muy lejos de tener que recordar qué ajustes activaste en qué chat.
8Qué incluye cada plan
La línea divisoria es sencilla. La comprobación de spam en texto está disponible en todos los planes, así que incluso el nivel gratuito puede usar la detección de Telm como filtro en su propio producto. La superficie completa —verificación de usuarios con niveles de riesgo, el registro de decisiones y la analítica, la gestión de ajustes y reglas, y los webhooks— forma parte de los planes Pro y Business.
Cada plan dispone de una cuota diaria de solicitudes, dimensionada para que las integraciones más pesadas estén en los planes más potentes:
- **Free**: 100 solicitudes de API al día, solo comprobación de spam.
- **Basic**: 1000 solicitudes de API al día, solo comprobación de spam.
- **Pro**: 10 000 solicitudes de API al día, además de la superficie completa de la API y los webhooks.
- **Business**: 50 000 solicitudes de API al día, además de la superficie completa de la API y los webhooks.
- Crea tus claves en Ajustes → API y Webhooks, guárdalas en tu gestor de secretos, verifica la firma de cada webhook, y el mismo motor que protege tus grupos pasará a formar parte de tu propia infraestructura.