O endpoint em lote passa até 20 textos pelo motor antispam do Telm em um único POST, retornando um veredito para cada um. É somente regras (sem o nível de IA) e disponível no plano Pro e acima. A cota é cobrada por item, então um lote de dez textos gasta dez chamadas. Para um único texto com uma verificação de IA opcional, use o endpoint regular de verificação de spam.
1O que a verificação de spam em lote faz
A verificação de spam em lote permite que você pontue muitos textos de uma vez em vez de fazer uma requisição por mensagem. Você envia um POST para /spam/check-batch com um array de itens e recebe de volta um array de vereditos na mesma ordem — ideal para classificar um acúmulo de mensagens, moderar um feed de comentários ou avaliar a qualidade da detecção sobre uma amostra.
O lote roda o mesmo motor de regras que protege grupos ao vivo, mas não roda o nível de IA, o que mantém cada requisição rápida e previsível. Se você precisa da verificação de IA, use o endpoint de verificação de spam individual com a opção de IA ativada, um texto por vez.
- Endpoint: POST /api/public/v1/spam/check-batch.
- Pontua até 20 textos por requisição, vereditos retornados na ordem de entrada.
- Somente regras: o nível de IA não é rodado no modo em lote.
2Formato da requisição
O corpo da requisição é um objeto JSON com um array items. Cada item tem um campo text obrigatório e um objeto context opcional que espelha o que o motor ao vivo vê — o group_id, o user_telegram_id do remetente, se o remetente é um usuário novo, o username e flags como allow_sales e crypto_community.
Quando um item inclui um group_id no seu context, a verificação aplica as regras e configurações personalizadas daquele grupo, então a sua conta precisa ser admin dele ou a requisição inteira é rejeitada. Omita o contexto de grupo para pontuar contra o conjunto de regras global em vez disso.
- Campo de nível superior: items — um array de uma a vinte entradas.
- Cada item: text (obrigatório) e um objeto context opcional.
- O context pode carregar group_id, user_telegram_id, is_new_user, username, allow_sales, crypto_community.
- Um contexto de grupo requer que você administre aquele grupo.
3Formato da resposta
A resposta é um objeto JSON com um array results — um veredito por item de entrada, na mesma ordem — e um objeto quota mostrando a sua contagem de uso, o limite diário e o horário de reset.
Cada veredito te diz a classificação e o porquê. O campo verdict é um de spam, suspicious ou clean. Ao lado dele você recebe um score e uma confidence numéricos, uma recommended_action (uma de none, review, warn, mute, kick, ban ou delete), uma lista de categories, reasons legíveis por humanos, os nomes das matched_rules, e um mapa signals com as contribuições individuais de pontuação.
- results — um veredito por item, na ordem de entrada.
- verdict — spam, suspicious ou clean.
- Cada veredito também tem score, confidence, recommended_action, categories, reasons, matched_rules e signals.
- quota — used, limit e reset_at, ecoado no corpo.
4Limites e custo de cota
Um lote é limitado a 20 itens por requisição, e cada texto é limitado a 10.000 caracteres. O corpo inteiro da requisição também tem um teto de tamanho, então payloads muito grandes são rejeitados antes do processamento. Se você tem mais de 20 textos, divida-os em várias requisições.
A cota é cobrada por item, não por requisição: um lote de dez textos gasta dez chamadas da sua cota diária. Esse é o mesmo orçamento descrito em limites e cotas da API, e a resposta carrega os cabeçalhos usuais X-Quota-Limit, X-Quota-Used e X-Quota-Reset.
- Até 20 itens por requisição; até 10.000 caracteres por texto.
- O custo de cota é igual ao número de itens no lote.
- Cabeçalhos X-Quota-* padrão se aplicam, mais um objeto quota no corpo.
5Erros e timeouts
Requisições ruins retornam 400 com um código específico: um array items vazio, um lote acima do limite de itens, um text ausente, ou um texto acima do limite de comprimento. Um contexto de grupo que você não administra retorna 404 para aquele item. Um plano abaixo do Pro retorna 403 com um código plan_required.
Se o processamento de um lote exceder o seu orçamento de tempo, a API retorna 504 e reembolsa a cota dos itens que não terminou, então você só é cobrado pelo trabalho concluído. Se você vir timeouts, envie lotes menores.
- 400 — empty_batch, batch_too_large, missing_text ou text_too_long.
- 404 — um grupo no contexto de um item não é um que você administra.
- 403 plan_required — o endpoint em lote precisa de Pro ou superior.
- 504 timeout — o lote rodou por tempo demais; itens não terminados são reembolsados. Envie menos textos.