El endpoint por lotes pasa hasta 20 textos por el motor antispam de Telm en un solo POST, devolviendo un veredicto para cada uno. Es solo de reglas (sin nivel de IA) y está disponible en el plan Pro y superior. La cuota se cobra por elemento, así que un lote de diez textos gasta diez llamadas. Para un solo texto con una comprobación de IA opcional, usa el endpoint normal de comprobación de spam.
1Qué hace la comprobación de spam por lotes
La comprobación de spam por lotes te permite puntuar muchos textos a la vez en lugar de hacer una petición por mensaje. Envías un POST a /spam/check-batch con un array de elementos y recibes de vuelta un array de veredictos en el mismo orden: ideal para clasificar una acumulación de mensajes, moderar un feed de comentarios, o evaluar la calidad de la detección sobre una muestra.
El lote ejecuta el mismo motor de reglas que protege los grupos en vivo, pero no ejecuta el nivel de IA, lo que mantiene cada petición rápida y predecible. Si necesitas la comprobación de IA, usa el endpoint de comprobación de spam individual con la opción de IA habilitada, un texto a la vez.
- Endpoint: POST /api/public/v1/spam/check-batch.
- Puntúa hasta 20 textos por petición, veredictos devueltos en el orden de entrada.
- Solo de reglas: el nivel de IA no se ejecuta en modo por lotes.
2Formato de petición
El cuerpo de la petición es un objeto JSON con un array items. Cada elemento tiene un campo text obligatorio y un objeto context opcional que refleja lo que ve el motor en vivo: el group_id, el user_telegram_id del remitente, si el remitente es un usuario nuevo, el username, y banderas como allow_sales y crypto_community.
Cuando un elemento incluye un group_id en su context, la comprobación aplica las reglas y ajustes personalizados de ese grupo, así que tu cuenta debe ser administradora de ese grupo o toda la petición se rechaza. Omite el contexto de grupo para puntuar contra el conjunto de reglas global en su lugar.
- Campo de nivel superior: items — un array de una a veinte entradas.
- Cada elemento: text (obligatorio) y un objeto context opcional.
- El contexto puede llevar group_id, user_telegram_id, is_new_user, username, allow_sales, crypto_community.
- Un contexto de grupo requiere que administres ese grupo.
3Formato de respuesta
La respuesta es un objeto JSON con un array results (un veredicto por elemento de entrada, en el mismo orden) y un objeto quota que muestra tu contador de uso, el límite diario y la hora de reinicio.
Cada veredicto te dice la clasificación y el porqué. El campo verdict es uno de spam, suspicious o clean. Junto a él obtienes un score y una confidence numéricos, una recommended_action (una de none, review, warn, mute, kick, ban o delete), una lista de categories, reasons legibles por humanos, los nombres de los matched_rules, y un mapa signals con las aportaciones de puntuación individuales.
- results — un veredicto por elemento, en el orden de entrada.
- verdict — spam, suspicious o clean.
- Cada veredicto también tiene score, confidence, recommended_action, categories, reasons, matched_rules y signals.
- quota — used, limit y reset_at, reflejados en el cuerpo.
4Límites y coste de cuota
Un lote está limitado a 20 elementos por petición, y cada texto está limitado a 10,000 caracteres. Todo el cuerpo de la petición también tiene un techo de tamaño, así que las cargas muy grandes se rechazan antes del procesamiento. Si tienes más de 20 textos, repártelos en varias peticiones.
La cuota se cobra por elemento, no por petición: un lote de diez textos gasta diez llamadas de tu cuota diaria. Este es el mismo presupuesto descrito en límites de tasa y cuotas de la API, y la respuesta lleva los encabezados habituales X-Quota-Limit, X-Quota-Used y X-Quota-Reset.
- Hasta 20 elementos por petición; hasta 10,000 caracteres por texto.
- El coste de cuota equivale al número de elementos del lote.
- Aplican los encabezados estándar X-Quota-*, más un objeto quota en el cuerpo.
5Errores y tiempos de espera
Las peticiones incorrectas devuelven 400 con un código específico: un array items vacío, un lote por encima del límite de elementos, un text ausente, o un texto por encima del límite de longitud. Un contexto de grupo que no administras devuelve 404 para ese elemento. Un plan por debajo de Pro devuelve 403 con un código plan_required.
Si procesar un lote supera su presupuesto de tiempo, la API devuelve 504 y reembolsa la cuota de los elementos que no terminó, así que solo se te cobra por el trabajo que se completó. Si ves tiempos de espera agotados, envía lotes más pequeños.
- 400 — empty_batch, batch_too_large, missing_text o text_too_long.
- 404 — un grupo en el contexto de un elemento no es uno que administres.
- 403 plan_required — el endpoint por lotes necesita Pro o superior.
- 504 timeout — el lote se ejecutó demasiado tiempo; los elementos sin terminar se reembolsan. Envía menos textos.