נקודת הקצה של האצווה מריצה עד 20 טקסטים דרך מנוע האנטי־ספאם של Telm ב־POST בודד, ומחזירה הכרעה לכל אחד. היא מבוססת־כללים בלבד (ללא רמת AI) וזמינה בתוכנית Pro ומעלה. המכסה מחויבת לכל פריט, כך שאצווה של עשרה טקסטים מוציאה עשר קריאות. עבור טקסט בודד עם בדיקת AI אופציונלית, השתמשו בנקודת הקצה הרגילה של בדיקת ספאם.
1מה בדיקת ספאם באצווה עושה
בדיקת ספאם באצווה מאפשרת לכם לנקד טקסטים רבים בבת אחת במקום לבצע בקשה אחת לכל הודעה. אתם שולחים POST אל /spam/check-batch עם מערך פריטים ומקבלים בחזרה מערך הכרעות באותו סדר — אידיאלי לסיווג צבר של הודעות, למודרציית פיד תגובות, או להערכת איכות זיהוי על מדגם.
האצווה מריצה את אותו מנוע כללים שמגן על קבוצות חיות, אך היא אינה מריצה את רמת ה־AI, מה ששומר על כל בקשה מהירה וצפויה. אם אתם צריכים את בדיקת ה־AI, השתמשו בנקודת הקצה הבודדת של בדיקת ספאם עם אפשרות ה־AI מופעלת, טקסט אחד בכל פעם.
- נקודת קצה: POST /api/public/v1/spam/check-batch.
- מנקדת עד 20 טקסטים לבקשה, ההכרעות מוחזרות בסדר הקלט.
- מבוססת־כללים בלבד: רמת ה־AI אינה מורצת במצב אצווה.
2פורמט הבקשה
גוף הבקשה הוא אובייקט JSON עם מערך items. לכל פריט יש שדה text נדרש ואובייקט context אופציונלי שמשקף את מה שהמנוע החי רואה — ה־group_id, ה־user_telegram_id של השולח, האם השולח משתמש חדש, ה־username, ודגלים כמו allow_sales ו־crypto_community.
כשפריט כולל group_id ב־context שלו, הבדיקה מחילה את הכללים המותאמים וההגדרות של אותה קבוצה, כך שהחשבון שלכם חייב להיות מנהל של אותה קבוצה או שכל הבקשה נדחית. השמיטו את context הקבוצה כדי לנקד מול מערך הכללים הגלובלי במקום.
- שדה עליון: items — מערך של אחד עד עשרים ערכים.
- כל פריט: text (נדרש) ואובייקט context אופציונלי.
- Context יכול לשאת group_id, user_telegram_id, is_new_user, username, allow_sales, crypto_community.
- context של קבוצה דורש שתנהלו את אותה קבוצה.
3פורמט התגובה
התגובה היא אובייקט JSON עם מערך results — הכרעה אחת לכל פריט קלט, באותו סדר — ואובייקט quota שמראה את ספירת השימוש, המגבלה היומית וזמן האיפוס שלכם.
כל הכרעה מספרת לכם את הסיווג ומדוע. שדה ה־verdict הוא אחד מ־spam, suspicious או clean. לצדו אתם מקבלים score מספרי ו־confidence, recommended_action (אחד מ־none, review, warn, mute, kick, ban או delete), רשימת categories, reasons קריאות־אדם, שמות ה־matched_rules, ומפת signals עם תרומות הניקוד הבודדות.
- results — הכרעה אחת לכל פריט, בסדר הקלט.
- verdict — spam, suspicious או clean.
- לכל הכרעה יש גם score, confidence, recommended_action, categories, reasons, matched_rules ו־signals.
- quota — used, limit ו־reset_at, מהדהד בגוף.
4מגבלות ועלות מכסה
אצווה מוגבלת ל־20 פריטים לבקשה, וכל טקסט מוגבל ל־10,000 תווים. לכל גוף הבקשה יש גם תקרת גודל, כך שמטענים גדולים מאוד נדחים לפני העיבוד. אם יש לכם יותר מ־20 טקסטים, פצלו אותם על פני מספר בקשות.
המכסה מחויבת לכל פריט, לא לכל בקשה: אצווה של עשרה טקסטים מוציאה עשר קריאות מהמכסה היומית שלכם. זהו אותו תקציב המתואר במגבלות קצב ומכסות API, והתגובה נושאת את כותרות X-Quota-Limit, X-Quota-Used ו־X-Quota-Reset הרגילות.
- עד 20 פריטים לבקשה; עד 10,000 תווים לטקסט.
- עלות המכסה שווה למספר הפריטים באצווה.
- כותרות X-Quota-* סטנדרטיות חלות, בתוספת אובייקט quota בגוף.
5שגיאות ופסקי זמן
בקשות שגויות מחזירות 400 עם קוד ספציפי: מערך items ריק, אצווה מעל מגבלת הפריטים, text חסר, או text מעל מגבלת האורך. context של קבוצה שאינכם מנהלים מחזיר 404 עבור אותו פריט. תוכנית מתחת ל־Pro מחזירה 403 עם קוד plan_required.
אם עיבוד אצווה חורג מתקציב הזמן שלה, ה־API מחזיר 504 ומחזיר את המכסה עבור הפריטים שלא סיים, כך שאתם מחויבים רק על עבודה שהושלמה. אם אתם רואים פסקי זמן, שלחו אצוות קטנות יותר.
- 400 — empty_batch, batch_too_large, missing_text או text_too_long.
- 404 — קבוצה ב־context של פריט אינה כזו שאתם מנהלים.
- 403 plan_required — נקודת הקצה של האצווה דורשת Pro ומעלה.
- 504 timeout — האצווה רצה זמן רב מדי; פריטים שלא הושלמו מוחזרים. שלחו פחות טקסטים.