Het batch-endpoint haalt tot 20 teksten door de Telm antispam-engine in één POST en geeft voor elk een verdict terug. Het is alleen-regels (geen AI-niveau) en beschikbaar op het Pro-plan en hoger. Quotum wordt per item in rekening gebracht, dus een batch van tien teksten kost tien aanroepen. Voor één tekst met een optionele AI-controle gebruik je het gewone spam-check-endpoint.
1Wat batch-spamcontrole doet
Met batch-spamcontrole kun je veel teksten in één keer scoren in plaats van één verzoek per bericht te doen. Je stuurt een POST naar /spam/check-batch met een array van items en krijgt een array van verdicts terug in dezelfde volgorde — ideaal voor het classificeren van een achterstand aan berichten, het modereren van een reactiefeed of het evalueren van de detectiekwaliteit over een steekproef.
De batch draait dezelfde regels-engine die live groepen beschermt, maar draait niet het AI-niveau, wat elk verzoek snel en voorspelbaar houdt. Heb je de AI-controle nodig, gebruik dan het losse spam-check-endpoint met de AI-optie ingeschakeld, één tekst per keer.
- Endpoint: POST /api/public/v1/spam/check-batch.
- Scoort tot 20 teksten per verzoek, verdicts geretourneerd in invoervolgorde.
- Alleen-regels: het AI-niveau wordt in batchmodus niet gedraaid.
2Verzoekformaat
De verzoekbody is een JSON-object met een items-array. Elk item heeft een verplicht text-veld en een optioneel context-object dat weerspiegelt wat de live engine ziet — de group_id, de afzender user_telegram_id, of de afzender een nieuwe gebruiker is, de username en vlaggen zoals allow_sales en crypto_community.
Wanneer een item een group_id in zijn context bevat, past de controle de aangepaste regels en instellingen van die groep toe, dus je account moet beheerder van die groep zijn of het hele verzoek wordt afgewezen. Laat de groepscontext weg om tegen de globale regelset te scoren.
- Veld op hoofdniveau: items — een array van één tot twintig entries.
- Elk item: text (verplicht) en een optioneel context-object.
- Context kan group_id, user_telegram_id, is_new_user, username, allow_sales, crypto_community dragen.
- Een groepscontext vereist dat je die groep beheert.
3Antwoordformaat
Het antwoord is een JSON-object met een results-array — één verdict per invoeritem, in dezelfde volgorde — en een quota-object dat je gebruiksaantal, dagelijkse limiet en resettijd toont.
Elk verdict vertelt je de classificatie en waarom. Het verdict-veld is een van spam, suspicious of clean. Daarnaast krijg je een numerieke score en confidence, een recommended_action (een van none, review, warn, mute, kick, ban of delete), een lijst met categories, menselijk leesbare reasons, de namen van de matched_rules en een signals-map met de afzonderlijke scorebijdragen.
- results — één verdict per item, in invoervolgorde.
- verdict — spam, suspicious of clean.
- Elk verdict heeft ook score, confidence, recommended_action, categories, reasons, matched_rules en signals.
- quota — used, limit en reset_at, geëchood in de body.
4Limieten en quotumkosten
Een batch is begrensd tot 20 items per verzoek, en elke tekst is beperkt tot 10.000 tekens. De hele verzoekbody heeft ook een groottegrens, dus zeer grote payloads worden vóór verwerking afgewezen. Heb je meer dan 20 teksten, verdeel ze dan over meerdere verzoeken.
Quotum wordt per item in rekening gebracht, niet per verzoek: een batch van tien teksten kost tien aanroepen uit je dagelijkse quotum. Dit is hetzelfde budget dat wordt beschreven in API-ratelimieten en quota, en het antwoord draagt de gebruikelijke X-Quota-Limit, X-Quota-Used en X-Quota-Reset headers.
- Tot 20 items per verzoek; tot 10.000 tekens per tekst.
- Quotumkosten zijn gelijk aan het aantal items in de batch.
- Standaard X-Quota-*-headers zijn van toepassing, plus een quota-object in de body.
5Fouten en time-outs
Ongeldige verzoeken geven 400 met een specifieke code: een lege items-array, een batch boven de itemlimiet, een ontbrekende text of een text boven de lengtelimiet. Een groepscontext die je niet beheert geeft 404 voor dat item. Een plan onder Pro geeft 403 met een plan_required-code.
Als het verwerken van een batch zijn tijdsbudget overschrijdt, geeft de API 504 en vergoedt het quotum voor de items die niet zijn afgerond, zodat je alleen wordt belast voor voltooid werk. Zie je time-outs, stuur dan kleinere batches.
- 400 — empty_batch, batch_too_large, missing_text of text_too_long.
- 404 — een groep in een itemcontext is er geen die je beheert.
- 403 plan_required — het batch-endpoint vereist Pro of hoger.
- 504 timeout — de batch draaide te lang; onafgeronde items worden vergoed. Stuur minder teksten.