REST API: automatiza Telm desde tu propio código

1Qué te permite hacer la API

La REST API de Telm da a tu propio código el mismo alcance que el panel: pasar cualquier texto por el proceso antispam, consultar a un usuario de Telegram antes de dejarlo entrar, leer y cambiar los ajustes de protección de un grupo, gestionar reglas personalizadas y listas de permitidos, obtener el registro de moderación y las analíticas, y registrar webhooks para recibir eventos en tiempo real.

Así, Telm deja de ser un bot que vive dentro de tus grupos y se convierte en infraestructura que puedes conectar en cualquier parte: un formulario de registro en una web, un bot de CRM, tus propios bots de Telegram o un script que configura cien grupos a la vez.

• URL base: api.telm.com/api/public/v1, una ruta estable y versionada (la v1 es la versión del contrato).
• Todas las peticiones y respuestas son JSON sobre HTTPS.
• La documentación interactiva y la especificación OpenAPI 3.1 legible por máquinas están en la página para desarrolladores: carga la especificación en Postman, en un generador de código o en un agente de IA para crear la base de una integración en minutos.
• Las llamadas medidas devuelven los encabezados X-Quota-Limit, X-Quota-Used y X-Quota-Reset en cada respuesta.

2Cómo recorre Telm una petición

La API pública tiene su propio prefijo de ruta, /api/public/, separado del panel. Cada llamada se autentica con una clave de API en lugar de una sesión del navegador, se comprueba con tu plan y tu cuota, se ejecuta en el mismo motor en producción que modera tus grupos y se devuelve como JSON.

Como la API llega al mismo motor y a los mismos datos que el bot, todo lo que puedes ver o cambiar en el panel también lo puedes hacer desde código, y cualquier cambio que hagas desde código aparece en el panel al instante.

• Las peticiones no tienen estado: cada una lleva su propia clave y es independiente.
• Una clave actúa en nombre de tu cuenta y solo puede tocar los grupos donde tu cuenta es administradora.
• El endpoint de comprobación de spam usa exactamente el mismo proceso de reglas de producción, así que el veredicto de la API coincide con lo que haría el bot en el grupo.

3Autenticación con claves de API

Cada petición se autentica con una clave de API con el formato tk_live_ seguido de caracteres aleatorios, no con tu inicio de sesión del panel. Creas las claves en tu cuenta y envías la clave en el encabezado Authorization como token Bearer, o en un encabezado X-API-Key.

El secreto completo se muestra una sola vez, al crearlo. Después, el panel muestra cada clave solo por su prefijo corto, para que puedas reconocerla sin guardar nunca el valor completo. Si una clave se filtra, revócala y emite una nueva: la revocación surte efecto de inmediato.

• Envía la clave como Authorization: Bearer tk_live_your_key_here (también funciona un encabezado X-API-Key).
• Las claves tienen alcance de lectura o de escritura: lectura para las peticiones GET y escritura para todo lo que cambia datos. Una clave de solo lectura no puede crear ni editar.
• Puedes tener hasta diez claves activas a la vez, así que puedes usar una clave distinta para cada script o servicio.
• Si falta la clave o no es válida, la respuesta es 401; una clave sin el alcance necesario devuelve 403 insufficient_scope.

4Endpoints disponibles

La API se organiza en torno a las comprobaciones de spam y de usuarios, la gestión de grupos y el autoservicio de la cuenta. El endpoint de comprobación de spam individual está abierto a todos los planes; el resto forma parte de Pro y Business.

• POST /spam/check: pasa un texto por el mismo motor de reglas que modera el tráfico real (todos los planes). En Pro y superiores se puede activar una comprobación opcional con IA.
• POST /spam/check-batch: comprueba hasta 20 textos en una sola llamada, solo con reglas (Pro+).
• POST /users/check: consulta a un usuario de Telegram: estado en CAS, señales de las decisiones de spam de Telm y reputación en tus grupos (Pro+).
• GET /groups y GET /groups/{id}: lista y lee tus grupos (Pro+).
• GET y PATCH /groups/{id}/settings: lee y cambia los ajustes de protección de un grupo (Pro+).
• GET/POST/PUT/DELETE /groups/{id}/rules: gestiona las reglas de moderación personalizadas (Pro+).
• GET/POST/DELETE /groups/{id}/whitelist: gestiona la lista de permitidos del grupo (Pro+).
• GET /groups/{id}/journal y GET /groups/{id}/analytics: lee el registro de moderación y las analíticas (Pro+).
• GET/POST/PATCH/DELETE /webhooks: gestiona los webhooks de eventos en tiempo real (Pro+).
• GET /usage y GET /me: consulta tu cuota y la información de la clave; nunca consumen cuota (todos los planes).

5El endpoint de comprobación de spam en detalle

POST /spam/check es el corazón de la API y el único endpoint que puedes probar en cualquier plan. Envía un cuerpo JSON con el texto que quieres comprobar; la respuesta devuelve un veredicto, una puntuación numérica, un valor de confianza y una acción recomendada que puedes aplicar en tu propio producto.

Un solo texto puede tener hasta 10.000 caracteres. En Pro y superiores puedes activar una comprobación con IA para los casos más difíciles, que se descuenta de una cuota diaria aparte de comprobaciones con IA. Para grandes volúmenes, el endpoint por lotes comprueba hasta 20 textos en una sola llamada y cuenta la cuota por elemento.

• Usa el veredicto y la puntuación para decidir qué hace tu propio producto: bloquear el envío de un formulario, marcar un contacto comercial o eliminar automáticamente un mensaje en tu propio bot.
• El endpoint por lotes usa solo reglas; la escalera de IA solo está disponible en el endpoint de texto individual.
• Los cuerpos de las peticiones tienen un tamaño máximo (unos 64 KB para una comprobación individual y 256 KB para un lote); los cuerpos demasiado grandes devuelven 413.

6Planes, límites de tasa y cuotas diarias

El acceso se mide de dos formas: un límite de tasa por minuto (un tope para los picos) y una cuota diaria de llamadas que se reinicia a medianoche UTC. Ambos se cuentan por cuenta y se comparten entre todas tus claves de API. Puedes probar el endpoint de comprobación de spam individual en cualquier plan, pero una integración real que use reglas, ajustes, comprobaciones por lotes y webhooks necesita Pro o superior.

• Free: 100 llamadas/día, solo comprobación de spam.
• Pro: 10.000 llamadas/día, API completa y webhooks, además de 1.000 comprobaciones con IA al día.
• Business: 50.000 llamadas/día, API completa y webhooks, además de 10.000 comprobaciones con IA al día.
• Los límites de tasa por minuto también crecen: 60 peticiones por minuto en Free, 600 en Pro y 1.800 en Business.
• GET /usage y GET /me nunca cuentan para tu cuota, así que puedes consultar lo que te queda en cualquier momento.

7Gestión de errores y códigos de estado

La API usa códigos de estado HTTP estándar con un código de error legible por máquinas en el cuerpo. Diseña tu cliente para que lea estos códigos y espere o sugiera una mejora de plan en lugar de reintentar a ciegas.

Cuando superas tu cuota diaria, una llamada medida devuelve 429 con el código daily_quota_exceeded, un encabezado Retry-After y un cuerpo con tu plan, el límite, el número de llamadas usadas, la hora de reinicio y una sugerencia para mejorar el plan. Los endpoints que requieren un plan superior devuelven 403 plan_required con el plan necesario.

• 401: falta la clave de API o no es válida.
• 403 plan_required: el endpoint requiere Pro o superior.
• 403 insufficient_scope: la clave no tiene alcance de escritura para una llamada que cambia datos.
• 429 daily_quota_exceeded o rate_limit_exceeded: espera a la hora de reinicio o mejora el plan; respeta el encabezado Retry-After.
• Lee los encabezados de respuesta X-Quota-* para adelantarte al límite.

8Buenas prácticas para una integración sólida

Algunos hábitos mantienen una integración fiable y segura a medida que crece.

• Guarda las claves en un gestor de secretos, nunca en código del lado del cliente ni en un repositorio git; usa una clave distinta por servicio para poder revocar una sin romper las demás.
• Vigila los encabezados X-Quota-Used y X-Quota-Limit (o consulta GET /usage) y reduce el ritmo antes de llegar al límite, no después.
• Ante un 429, respeta Retry-After y espera; ante un 403 plan_required, muestra una sugerencia para mejorar el plan en lugar de reintentar.
• Para reaccionar en tiempo real, usa webhooks en lugar de consultas periódicas: deja que Telm te envíe los eventos.
• Rota las claves periódicamente, y de inmediato si alguna puede haberse filtrado.

9Situaciones de integración habituales

La API se usa para mucho más que moderar mensajes de Telegram.

• Registro en webs y apps: pasa el texto enviado o los nombres de usuario por POST /spam/check antes de aceptar un registro o un comentario.
• Tus propios bots de Telegram: reutiliza la inteligencia de Telm en un bot que Telm no gestiona llamando al endpoint de comprobación desde tu manejador.
• Configuración masiva: aplica por script las mismas reglas, listas de permitidos y ajustes en decenas de grupos con los endpoints de ajustes y reglas.
• Datos y alertas: registra webhooks para enviar en tiempo real los eventos de moderación a un almacén de datos, un panel o un canal de alertas.