Endpoint hàng loạt chạy tối đa 20 văn bản qua công cụ chống spam của Telm trong một POST duy nhất, trả về một phán quyết cho mỗi văn bản. Nó chỉ dùng quy tắc (không có lớp AI) và khả dụng trên gói Pro trở lên. Hạn mức được tính theo từng mục, nên một lô mười văn bản tiêu tốn mười lệnh gọi. Với một văn bản đơn kèm một lần kiểm tra AI tùy chọn, hãy dùng endpoint kiểm tra spam thông thường.
1Kiểm tra spam hàng loạt làm gì
Kiểm tra spam hàng loạt cho phép bạn chấm điểm nhiều văn bản cùng lúc thay vì thực hiện một yêu cầu cho mỗi tin nhắn. Bạn gửi một POST tới /spam/check-batch với một mảng các mục và nhận về một mảng các phán quyết theo cùng thứ tự — lý tưởng để phân loại một tồn đọng tin nhắn, kiểm duyệt một luồng bình luận, hoặc đánh giá chất lượng nhận diện trên một mẫu.
Lô chạy cùng công cụ quy tắc bảo vệ các nhóm đang hoạt động, nhưng nó không chạy lớp AI, điều này giữ mỗi yêu cầu nhanh và dễ đoán. Nếu bạn cần kiểm tra AI, hãy dùng endpoint kiểm tra spam đơn với tùy chọn AI được bật, mỗi lần một văn bản.
- Endpoint: POST /api/public/v1/spam/check-batch.
- Chấm điểm tối đa 20 văn bản mỗi yêu cầu, các phán quyết trả về theo thứ tự đầu vào.
- Chỉ dùng quy tắc: lớp AI không được chạy trong chế độ hàng loạt.
2Định dạng yêu cầu
Thân yêu cầu là một đối tượng JSON với một mảng items. Mỗi mục có một trường text bắt buộc và một đối tượng context tùy chọn phản chiếu những gì công cụ đang hoạt động nhìn thấy — group_id, user_telegram_id của người gửi, việc người gửi có phải là người dùng mới hay không, username, và các cờ như allow_sales và crypto_community.
Khi một mục bao gồm một group_id trong context của nó, lần kiểm tra áp dụng các quy tắc tùy chỉnh và cài đặt của nhóm đó, nên tài khoản của bạn phải là quản trị viên của nhóm đó hoặc cả yêu cầu bị từ chối. Bỏ context nhóm để chấm điểm dựa trên bộ quy tắc toàn cục thay vào đó.
- Trường cấp cao nhất: items — một mảng từ một đến hai mươi phần tử.
- Mỗi mục: text (bắt buộc) và một đối tượng context tùy chọn.
- Context có thể mang group_id, user_telegram_id, is_new_user, username, allow_sales, crypto_community.
- Một context nhóm yêu cầu rằng bạn quản trị nhóm đó.
3Định dạng phản hồi
Phản hồi là một đối tượng JSON với một mảng results — một phán quyết cho mỗi mục đầu vào, theo cùng thứ tự — và một đối tượng quota hiển thị số đã dùng, giới hạn hằng ngày, và thời điểm đặt lại của bạn.
Mỗi phán quyết cho bạn biết phân loại và lý do. Trường verdict là một trong spam, suspicious hoặc clean. Bên cạnh đó bạn nhận được một score và confidence dạng số, một recommended_action (một trong none, review, warn, mute, kick, ban hoặc delete), một danh sách categories, các reasons người-đọc-được, tên của các matched_rules, và một bản đồ signals với các đóng góp chấm điểm riêng lẻ.
- results — một phán quyết cho mỗi mục, theo thứ tự đầu vào.
- verdict — spam, suspicious hoặc clean.
- Mỗi phán quyết cũng có score, confidence, recommended_action, categories, reasons, matched_rules và signals.
- quota — used, limit và reset_at, được lặp lại trong thân.
4Giới hạn và chi phí hạn mức
Một lô bị giới hạn ở 20 mục mỗi yêu cầu, và mỗi văn bản bị giới hạn ở 10.000 ký tự. Cả thân yêu cầu cũng có một trần kích thước, nên các payload rất lớn bị từ chối trước khi xử lý. Nếu bạn có hơn 20 văn bản, hãy chia chúng ra thành nhiều yêu cầu.
Hạn mức được tính theo từng mục, không phải theo yêu cầu: một lô mười văn bản tiêu tốn mười lệnh gọi từ hạn mức hằng ngày của bạn. Đây là cùng ngân sách được mô tả trong giới hạn tốc độ và hạn mức API, và phản hồi mang theo các header X-Quota-Limit, X-Quota-Used và X-Quota-Reset thông thường.
- Tối đa 20 mục mỗi yêu cầu; tối đa 10.000 ký tự mỗi văn bản.
- Chi phí hạn mức bằng số lượng mục trong lô.
- Các header X-Quota-* tiêu chuẩn áp dụng, cộng với một đối tượng quota trong thân.
5Lỗi và hết thời gian chờ
Các yêu cầu sai trả về 400 kèm một mã cụ thể: một mảng items rỗng, một lô vượt giới hạn số mục, một text thiếu, hoặc một text vượt giới hạn độ dài. Một context nhóm mà bạn không quản trị trả về 404 cho mục đó. Một gói dưới Pro trả về 403 kèm một mã plan_required.
Nếu việc xử lý một lô vượt ngân sách thời gian của nó, API trả về 504 và hoàn lại hạn mức cho các mục nó chưa hoàn thành, nên bạn chỉ bị tính cho phần việc đã hoàn tất. Nếu bạn thấy hết thời gian chờ, hãy gửi các lô nhỏ hơn.
- 400 — empty_batch, batch_too_large, missing_text hoặc text_too_long.
- 404 — một nhóm trong context của một mục không phải là nhóm bạn quản trị.
- 403 plan_required — endpoint hàng loạt cần Pro trở lên.
- 504 timeout — lô chạy quá lâu; các mục chưa hoàn thành được hoàn lại. Hãy gửi ít văn bản hơn.