Endpoint batch menjalankan hingga 20 teks melalui mesin anti-spam Telm dalam satu POST, mengembalikan sebuah vonis untuk masing-masing. Ia berbasis aturan saja (tanpa level AI) dan tersedia pada paket Pro dan di atasnya. Kuota dibebankan per item, jadi batch berisi sepuluh teks menghabiskan sepuluh panggilan. Untuk satu teks dengan pemeriksaan AI opsional, gunakan endpoint pemeriksaan spam biasa.
1Apa yang dilakukan pemeriksaan spam batch
Pemeriksaan spam batch memungkinkan Anda menilai banyak teks sekaligus alih-alih membuat satu permintaan per pesan. Anda mengirim POST ke /spam/check-batch dengan sebuah larik item dan mendapat kembali sebuah larik vonis dalam urutan yang sama — ideal untuk mengklasifikasikan tumpukan pesan, memoderasi umpan komentar, atau mengevaluasi kualitas deteksi atas sebuah sampel.
Batch menjalankan mesin aturan yang sama yang melindungi grup langsung, tetapi ia tidak menjalankan level AI, yang menjaga setiap permintaan tetap cepat dan dapat diprediksi. Jika Anda butuh pemeriksaan AI, gunakan endpoint pemeriksaan spam tunggal dengan opsi AI diaktifkan, satu teks pada satu waktu.
- Endpoint: POST /api/public/v1/spam/check-batch.
- Menilai hingga 20 teks per permintaan, vonis dikembalikan dalam urutan masukan.
- Berbasis aturan saja: level AI tidak dijalankan dalam mode batch.
2Format permintaan
Body permintaan adalah objek JSON dengan sebuah larik items. Setiap item memiliki bidang text yang wajib dan sebuah objek context opsional yang mencerminkan apa yang dilihat mesin langsung — group_id, user_telegram_id pengirim, apakah pengirim adalah pengguna baru, username, dan flag seperti allow_sales dan crypto_community.
Ketika sebuah item menyertakan group_id di context-nya, pemeriksaan menerapkan aturan kustom dan pengaturan grup itu, jadi akun Anda harus menjadi admin grup itu atau seluruh permintaan ditolak. Hilangkan konteks grup untuk menilai terhadap rangkaian aturan global sebagai gantinya.
- Bidang tingkat atas: items — sebuah larik berisi satu hingga dua puluh entri.
- Setiap item: text (wajib) dan sebuah objek context opsional.
- Context dapat membawa group_id, user_telegram_id, is_new_user, username, allow_sales, crypto_community.
- Konteks grup mengharuskan Anda mengelola grup itu.
3Format respons
Respons adalah objek JSON dengan sebuah larik results — satu vonis per item masukan, dalam urutan yang sama — dan sebuah objek quota yang menunjukkan jumlah terpakai, batas harian, dan waktu pengaturan ulang Anda.
Setiap vonis memberi tahu Anda klasifikasi dan alasannya. Bidang verdict adalah salah satu dari spam, suspicious, atau clean. Di sampingnya Anda mendapat score dan confidence numerik, sebuah recommended_action (salah satu dari none, review, warn, mute, kick, ban, atau delete), sebuah daftar categories, reasons yang dapat dibaca manusia, nama-nama matched_rules, dan sebuah peta signals dengan masing-masing kontribusi penilaian.
- results — satu vonis per item, dalam urutan masukan.
- verdict — spam, suspicious, atau clean.
- Setiap vonis juga memiliki score, confidence, recommended_action, categories, reasons, matched_rules, dan signals.
- quota — used, limit, dan reset_at, digemakan di body.
4Batas dan biaya kuota
Sebuah batch dibatasi hingga 20 item per permintaan, dan setiap teks dibatasi hingga 10.000 karakter. Seluruh body permintaan juga memiliki batas ukuran, sehingga payload yang sangat besar ditolak sebelum diproses. Jika Anda memiliki lebih dari 20 teks, bagi mereka di beberapa permintaan.
Kuota dibebankan per item, bukan per permintaan: batch berisi sepuluh teks menghabiskan sepuluh panggilan dari kuota harian Anda. Ini adalah anggaran yang sama yang dijelaskan di batas laju dan kuota API, dan respons membawa header X-Quota-Limit, X-Quota-Used, dan X-Quota-Reset yang biasa.
- Hingga 20 item per permintaan; hingga 10.000 karakter per teks.
- Biaya kuota sama dengan jumlah item dalam batch.
- Header X-Quota-* standar berlaku, plus sebuah objek quota di body.
5Kesalahan dan tenggat waktu
Permintaan buruk mengembalikan 400 dengan kode spesifik: larik items yang kosong, sebuah batch di atas batas item, teks yang hilang, atau teks di atas batas panjang. Konteks grup yang tidak Anda kelola mengembalikan 404 untuk item itu. Paket di bawah Pro mengembalikan 403 dengan kode plan_required.
Jika memproses sebuah batch melampaui anggaran waktunya, API mengembalikan 504 dan mengembalikan kuota untuk item yang tidak selesai, sehingga Anda hanya dibebankan untuk pekerjaan yang selesai. Jika Anda melihat tenggat waktu, kirim batch yang lebih kecil.
- 400 — empty_batch, batch_too_large, missing_text, atau text_too_long.
- 404 — sebuah grup di konteks item bukan grup yang Anda kelola.
- 403 plan_required — endpoint batch membutuhkan Pro atau lebih tinggi.
- 504 timeout — batch berjalan terlalu lama; item yang tak selesai dikembalikan. Kirim lebih sedikit teks.