تُمرّر نقطة النهاية الدُّفعية حتى 20 نصًا عبر محرك مكافحة البريد المزعج في Telm في طلب POST واحد، معيدةً حكمًا لكل منها. وهي بالقواعد فقط (بلا مستوى ذكاء اصطناعي) ومتاحة على خطة Pro فأعلى. تُحسَب الحصة لكل عنصر، فدُفعة من عشرة نصوص تنفق عشرة استدعاءات. ولنص واحد بفحص ذكاء اصطناعي اختياري، استخدم نقطة نهاية فحص البريد المزعج العادية.
1ماذا يفعل فحص البريد المزعج الدُّفعي
يتيح لك فحص البريد المزعج الدُّفعي تقييم نصوص كثيرة دفعة واحدة بدل إجراء طلب لكل رسالة. ترسل POST إلى /spam/check-batch بمصفوفة عناصر وتستعيد مصفوفة أحكام بالترتيب نفسه — مثالي لتصنيف تراكم من الرسائل، أو الإشراف على موجز تعليقات، أو تقييم جودة الاكتشاف على عينة.
تشغّل الدُّفعة محرك القواعد نفسه الذي يحمي المجموعات الحية، لكنها لا تشغّل مستوى الذكاء الاصطناعي، ما يبقي كل طلب سريعًا ومتوقَّعًا. إن احتجت فحص الذكاء الاصطناعي، فاستخدم نقطة نهاية فحص البريد المزعج المفردة مع تفعيل خيار الذكاء الاصطناعي، نصًا واحدًا في المرة.
- نقطة النهاية: POST /api/public/v1/spam/check-batch.
- يقيّم حتى 20 نصًا لكل طلب، وتُعاد الأحكام بترتيب الإدخال.
- بالقواعد فقط: مستوى الذكاء الاصطناعي لا يُشغَّل في الوضع الدُّفعي.
2تنسيق الطلب
جسم الطلب كائن JSON بمصفوفة items. لكل عنصر حقل text مطلوب وكائن context اختياري يعكس ما يراه المحرك الحي — group_id، وuser_telegram_id للمرسل، وما إذا كان المرسل مستخدمًا جديدًا، وusername، وأعلام مثل allow_sales وcrypto_community.
حين يضم عنصر group_id في سياقه، يطبّق الفحص قواعد تلك المجموعة المخصصة وإعداداتها، فيجب أن يكون حسابك مشرفًا في تلك المجموعة وإلا رُفِض الطلب كله. احذف سياق المجموعة للتقييم مقابل مجموعة القواعد العالمية بدلًا من ذلك.
- الحقل الأعلى: items — مصفوفة من عنصر إلى عشرين.
- كل عنصر: text (مطلوب) وكائن context اختياري.
- يمكن للسياق حمل group_id وuser_telegram_id وis_new_user وusername وallow_sales وcrypto_community.
- سياق المجموعة يتطلب أن تدير تلك المجموعة.
3تنسيق الرد
الرد كائن JSON بمصفوفة results — حكم لكل عنصر إدخال، بالترتيب نفسه — وكائن quota يُظهر عدد المُستخدَم وحدك اليومي ووقت الإعادة.
يخبرك كل حكم بالتصنيف والسبب. حقل verdict هو أحد spam أو suspicious أو clean. إلى جانبه تحصل على score رقمي وconfidence، وrecommended_action (أحد none أو review أو warn أو mute أو kick أو ban أو delete)، وقائمة categories، وأسباب مقروءة بشريًا، وأسماء matched_rules، وخريطة signals بمساهمات التسجيل الفردية.
- results — حكم لكل عنصر، بترتيب الإدخال.
- verdict — spam أو suspicious أو clean.
- لكل حكم أيضًا score وconfidence وrecommended_action وcategories وreasons وmatched_rules وsignals.
- quota — used وlimit وreset_at، مردَّدة في الجسم.
4الحدود وكلفة الحصة
الدُّفعة مُقيَّدة بـ 20 عنصرًا لكل طلب، وكل نص محدود بـ 10000 حرف. لجسم الطلب كله سقف حجم أيضًا، فالحمولات الكبيرة جدًا تُرفَض قبل المعالجة. إن كان لديك أكثر من 20 نصًا، فقسّمها عبر عدة طلبات.
تُحسَب الحصة لكل عنصر، لا لكل طلب: دُفعة من عشرة نصوص تنفق عشرة استدعاءات من حصتك اليومية. هذه هي الميزانية نفسها الموصوفة في حدود وحصص API، ويحمل الرد ترويسات X-Quota-Limit وX-Quota-Used وX-Quota-Reset المعتادة.
- حتى 20 عنصرًا لكل طلب؛ حتى 10000 حرف لكل نص.
- كلفة الحصة تساوي عدد العناصر في الدُّفعة.
- ترويسات X-Quota-* القياسية تنطبق، مع كائن quota في الجسم.
5الأخطاء وانتهاءات المهلة
الطلبات السيئة تعيد 400 برمز محدد: مصفوفة items فارغة، أو دُفعة فوق حد العناصر، أو text مفقود، أو نص فوق حد الطول. سياق مجموعة لا تديرها يعيد 404 لذلك العنصر. خطة دون Pro تعيد 403 برمز plan_required.
إن تجاوزت معالجة دُفعة ميزانيتها الزمنية، يعيد API حالة 504 ويستردّ حصة العناصر التي لم يُنهِها، فلا تُحاسَب إلا على العمل الذي اكتمل. إن رأيت انتهاءات مهلة، فأرسل دُفعات أصغر.
- 400 — empty_batch أو batch_too_large أو missing_text أو text_too_long.
- 404 — مجموعة في سياق عنصر ليست مما تديره.
- 403 plan_required — الإندبوينت الدُّفعي يحتاج Pro فأعلى.
- 504 timeout — الدُّفعة استغرقت طويلًا؛ العناصر غير المُنهاة تُستردّ. أرسل نصوصًا أقل.