Batch-endpointen kör upp till 20 texter genom Telms antispam-motor i en enda POST och returnerar ett utlåtande för var och en. Den använder bara regler (ingen AI-nivå) och finns på Pro-planen och uppåt. Kvoten debiteras per objekt, så en batch med tio texter förbrukar tio anrop. För en enskild text med en valfri AI-kontroll använder du den vanliga spamkontroll-endpointen.
1Vad batch-spamkontroll gör
Batch-spamkontroll låter dig poängsätta många texter på en gång istället för att göra ett anrop per meddelande. Du skickar en POST till /spam/check-batch med en array av objekt och får tillbaka en array av verdikt i samma ordning — perfekt för att klassificera en eftersläpning av meddelanden, moderera ett kommentarsflöde, eller utvärdera detekteringskvalitet över ett urval.
Batchen kör samma regelmotor som skyddar livegrupper, men den kör inte AI-nivån, vilket håller varje anrop snabbt och förutsägbart. Om du behöver AI-kontrollen, använd den enskilda spamkontroll-endpointen med AI-alternativet aktiverat, en text i taget.
- Endpoint: POST /api/public/v1/spam/check-batch.
- Poängsätter upp till 20 texter per anrop, verdikt returneras i inmatningsordning.
- Endast regler: AI-nivån körs inte i batchläge.
2Anropsformat
Anropskroppen är ett JSON-objekt med en items-array. Varje objekt har ett obligatoriskt text-fält och ett valfritt context-objekt som speglar vad livemotorn ser — group_id, avsändarens user_telegram_id, huruvida avsändaren är en ny användare, username, och flaggor som allow_sales och crypto_community.
När ett objekt inkluderar ett group_id i sitt context tillämpar kontrollen den gruppens egna regler och inställningar, så ditt konto måste vara administratör av den gruppen annars avvisas hela anropet. Utelämna gruppkontexten för att poängsätta mot den globala regeluppsättningen istället.
- Toppnivåfält: items — en array med ett till tjugo poster.
- Varje objekt: text (obligatoriskt) och ett valfritt context-objekt.
- Context kan bära group_id, user_telegram_id, is_new_user, username, allow_sales, crypto_community.
- En gruppkontext kräver att du administrerar den gruppen.
3Svarsformat
Svaret är ett JSON-objekt med en results-array — ett utlåtande per inmatningsobjekt, i samma ordning — och ett quota-objekt som visar ditt förbrukade antal, din dagliga gräns och nollställningstiden.
Varje utlåtande talar om klassificeringen och varför. verdict-fältet är ett av spam, suspicious eller clean. Vid sidan av det får du en numerisk score och confidence, en recommended_action (ett av none, review, warn, mute, kick, ban eller delete), en lista med categories, människoläsbara reasons, namnen på de matched_rules och en signals-karta med de individuella poängbidragen.
- results — ett utlåtande per objekt, i inmatningsordning.
- verdict — spam, suspicious eller clean.
- Varje utlåtande har också score, confidence, recommended_action, categories, reasons, matched_rules och signals.
- quota — used, limit och reset_at, återges i svaret.
4Gränser och kvotkostnad
En batch är begränsad till 20 objekt per anrop, och varje text är begränsad till 10 000 tecken. Hela anropskroppen har också ett storlekstak, så mycket stora nyttolaster avvisas före behandling. Om du har fler än 20 texter, dela upp dem över flera anrop.
Kvoten debiteras per objekt, inte per anrop: en batch med tio texter förbrukar tio anrop från din dagliga kvot. Detta är samma budget som beskrivs i API-hastighetsgränser och kvoter, och svaret innehåller de vanliga X-Quota-Limit-, X-Quota-Used- och X-Quota-Reset-headerna.
- Upp till 20 objekt per anrop; upp till 10 000 tecken per text.
- Kvotkostnaden är lika med antalet objekt i batchen.
- Vanliga X-Quota-*-headers gäller, plus ett quota-objekt i svaret.
5Fel och timeouts
Felaktiga anrop returnerar 400 med en specifik kod: en tom items-array, en batch över objektgränsen, en saknad text, eller en text över längdgränsen. En gruppkontext du inte administrerar returnerar 404 för det objektet. En plan under Pro returnerar 403 med en plan_required-kod.
Om behandling av en batch överskrider sin tidsbudget returnerar API:et 504 och återbetalar kvoten för de objekt den inte hann klart, så du debiteras bara för arbete som slutfördes. Om du ser timeouts, skicka mindre batchar.
- 400 — empty_batch, batch_too_large, missing_text eller text_too_long.
- 404 — en grupp i ett objekts context är inte en du administrerar.
- 403 plan_required — batch-endpointen kräver Pro eller högre.
- 504 timeout — batchen körde för länge; oavslutade objekt återbetalas. Skicka färre texter.