REST API — tự động hóa Telm từ mã của riêng bạn

1API cho phép bạn làm gì

REST API của Telm cho mã của riêng bạn cùng tầm với bảng điều khiển: chạy bất kỳ văn bản nào qua pipeline chống spam, tra cứu một người dùng Telegram trước khi bạn cho họ vào, đọc và thay đổi các cài đặt bảo vệ của một nhóm, quản lý các quy tắc tùy chỉnh và danh sách trắng, lấy nhật ký kiểm duyệt và phân tích, và đăng ký webhook cho các sự kiện thời gian thực.

Điều đó biến Telm từ một bot sống trong các nhóm của bạn thành hạ tầng bạn có thể kết nối vào bất cứ đâu — một biểu mẫu đăng ký trang web, một bot CRM, các bot Telegram của riêng bạn, hoặc một script cấu hình một trăm nhóm cùng lúc.

• Base URL: api.telm.com/api/public/v1 — một đường dẫn ổn định, có phiên bản (v1 là phiên bản của hợp đồng).
• Mọi yêu cầu và phản hồi đều là JSON qua HTTPS.
• Tài liệu tương tác và đặc tả OpenAPI 3.1 đọc được bằng máy nằm trên trang developers — nạp đặc tả vào Postman, một bộ sinh mã hoặc một tác nhân AI để dựng khung một tích hợp trong vài phút.
• Các lệnh gọi có tính hạn mức trả về các header X-Quota-Limit, X-Quota-Used và X-Quota-Reset trên mỗi phản hồi.

2Một yêu cầu đi qua Telm như thế nào

API công khai nằm trên tiền tố đường dẫn riêng của nó, /api/public/, tách biệt với bảng điều khiển. Mỗi lệnh gọi được xác thực bằng một API key thay vì một phiên trình duyệt, được kiểm tra so với gói và hạn mức của bạn, được chạy trên cùng công cụ trực tiếp kiểm duyệt các nhóm của bạn, và được trả về dưới dạng JSON.

Vì API tiếp cận cùng công cụ và dữ liệu như bot, bất cứ điều gì bạn có thể thấy hoặc thay đổi trong bảng điều khiển thì bạn cũng có thể làm bằng mã — và bất kỳ thay đổi nào bạn thực hiện bằng mã đều xuất hiện trong bảng điều khiển ngay lập tức.

• Các yêu cầu là stateless: mỗi yêu cầu mang key của riêng nó và tự đứng độc lập.
• Một key hành động thay mặt cho tài khoản của bạn và chỉ có thể động đến các nhóm nơi tài khoản của bạn là quản trị viên.
• Endpoint kiểm tra spam tiếp cận đúng pipeline quy tắc production, nên một phán quyết API khớp với những gì bot sẽ làm trong nhóm.

3Xác thực bằng API key

Mỗi yêu cầu được xác thực bằng một API key có dạng tk_live_ theo sau bởi các ký tự ngẫu nhiên — không phải thông tin đăng nhập bảng điều khiển của bạn. Bạn tạo các key trong tài khoản của mình và gửi key trong header Authorization dưới dạng một Bearer token, hoặc trong một header X-API-Key.

Bí mật đầy đủ chỉ được hiển thị một lần, tại thời điểm tạo. Sau đó bảng điều khiển chỉ liệt kê một key theo tiền tố ngắn của nó, nên bạn có thể nhận ra nó mà không bao giờ phải lưu giá trị đầy đủ. Nếu một key bị rò rỉ, hãy thu hồi nó và cấp một key mới — việc thu hồi có hiệu lực trong khoảng một phút.

• Gửi key dưới dạng Authorization: Bearer tk_live_your_key_here (một header X-API-Key cũng hoạt động).
• Các key mang phạm vi đọc hoặc ghi — đọc cho các yêu cầu GET, ghi cho bất cứ thứ gì thay đổi dữ liệu. Một key chỉ-đọc không thể tạo hoặc chỉnh sửa.
• Bạn có thể giữ tối đa mười key đang hoạt động cùng lúc, nên bạn có thể dùng một key riêng cho mỗi script hoặc dịch vụ.
• Một key thiếu hoặc không hợp lệ trả về 401; một key không có phạm vi cần thiết trả về 403 insufficient_scope.

4Các endpoint có sẵn

API được tổ chức quanh các lượt kiểm tra spam và người dùng, quản lý nhóm, và tự phục vụ tài khoản. Endpoint kiểm tra spam đơn lẻ mở cho mọi gói; phần còn lại của bề mặt là một phần của Pro và Business.

• POST /spam/check — chạy một văn bản qua cùng công cụ quy tắc kiểm duyệt lưu lượng trực tiếp (mọi gói). Một lượt kiểm tra AI tùy chọn có thể được bật trên Pro trở lên.
• POST /spam/check-batch — kiểm tra tối đa 20 văn bản trong một lệnh gọi, chỉ dùng quy tắc (Pro+).
• POST /users/check — tra cứu một người dùng Telegram: trạng thái CAS, các tín hiệu quyết định spam của Telm và danh tiếng trong các nhóm của bạn (Pro+).
• GET /groups và GET /groups/{id} — liệt kê và đọc các nhóm của bạn (Pro+).
• GET và PATCH /groups/{id}/settings — đọc và thay đổi các cài đặt bảo vệ của một nhóm (Pro+).
• GET/POST/PUT/DELETE /groups/{id}/rules — quản lý các quy tắc kiểm duyệt tùy chỉnh (Pro+).
• GET/POST/DELETE /groups/{id}/whitelist — quản lý danh sách trắng của nhóm (Pro+).
• GET /groups/{id}/journal và GET /groups/{id}/analytics — đọc nhật ký kiểm duyệt và phân tích (Pro+).
• GET/POST/PATCH/DELETE /webhooks — quản lý các webhook sự kiện thời gian thực (Pro+).
• GET /usage và GET /me — kiểm tra hạn mức và thông tin key của bạn; những cái này không bao giờ tiêu tốn hạn mức (mọi gói).

5Endpoint kiểm tra spam chi tiết

POST /spam/check là trái tim của API và là endpoint duy nhất bạn có thể thử trên bất kỳ gói nào. Gửi một phần thân JSON với văn bản cần kiểm tra; phản hồi trả về một phán quyết, một điểm số bằng số, một giá trị độ tin cậy và một hành động được đề xuất mà bạn có thể áp dụng trong sản phẩm của riêng mình.

Một văn bản đơn lẻ có thể lên tới 10.000 ký tự. Trên Pro trở lên, bạn có thể chọn tham gia một lượt kiểm tra AI cho những trường hợp khó hơn, lấy từ một hạn mức kiểm tra AI hằng ngày riêng. Với khối lượng lớn, endpoint hàng loạt kiểm tra tối đa 20 văn bản trong một lệnh gọi và tính hạn mức theo từng mục.

• Dùng phán quyết và điểm số để quyết định sản phẩm của riêng bạn làm gì — chặn một lần gửi biểu mẫu, gắn cờ một khách hàng tiềm năng, hoặc tự động gỡ một tin nhắn trong bot của riêng bạn.
• Endpoint hàng loạt chỉ dùng quy tắc; lượt kiểm tra AI chỉ có sẵn trên endpoint văn bản đơn lẻ.
• Phần thân yêu cầu bị giới hạn (khoảng 64 KB cho một lượt kiểm tra đơn lẻ, 256 KB cho một lượt hàng loạt); phần thân quá cỡ trả về 413.

6Các gói, giới hạn tốc độ và hạn mức hằng ngày

Quyền truy cập được đo theo hai cách: một giới hạn tốc độ theo phút (một trần đột biến) và một hạn mức lệnh gọi hằng ngày được đặt lại lúc nửa đêm UTC. Cả hai đều mở rộng theo gói của bạn và được tính theo tài khoản, dùng chung trên tất cả các key của bạn. Bạn có thể thử endpoint kiểm tra spam đơn lẻ trên bất kỳ gói nào, nhưng một tích hợp thực sự chạm đến quy tắc, cài đặt, kiểm tra hàng loạt và webhook thì cần Pro trở lên.

• Free — 100 lệnh gọi/ngày, chỉ kiểm tra spam.
• Basic — 1.000 lệnh gọi/ngày, chỉ kiểm tra spam.
• Pro — 10.000 lệnh gọi/ngày, toàn bộ API và webhook, cộng một hạn mức kiểm tra AI hằng ngày.
• Business — 50.000 lệnh gọi/ngày, toàn bộ API và webhook, hạn mức AI lớn hơn.
• Các giới hạn tốc độ theo phút cũng mở rộng — các gói cao hơn có một trần đột biến lớn hơn nhiều.

7Xử lý lỗi và mã trạng thái

API dùng các mã trạng thái HTTP tiêu chuẩn với một mã lỗi đọc được bằng máy trong phần thân. Hãy xây dựng client của bạn để đọc các mã này và lùi lại hoặc nhắc nâng cấp thay vì thử lại một cách mù quáng.

Khi bạn vượt hạn mức hằng ngày, một lệnh gọi có tính hạn mức trả về 429 với một mã daily_quota_exceeded, một header Retry-After, và một phần thân liệt kê gói, giới hạn, số đã dùng, thời gian đặt lại và một gợi ý nâng cấp của bạn. Các endpoint cần một gói cao hơn trả về 403 plan_required kèm gói cần thiết.

• 401 — API key thiếu hoặc không hợp lệ.
• 403 plan_required — endpoint cần Pro trở lên.
• 403 insufficient_scope — key thiếu phạm vi ghi cho một lệnh gọi thay đổi.
• 429 daily_quota_exceeded hoặc rate_limit_exceeded — chờ đến thời gian đặt lại hoặc nâng cấp; tôn trọng header Retry-After.
• Đọc các header phản hồi X-Quota-* để đi trước giới hạn.

8Thực hành tốt nhất cho một tích hợp vững chắc

Một vài thói quen giữ cho một tích hợp đáng tin cậy và an toàn khi nó phát triển.

• Lưu các key trong một trình quản lý bí mật, không bao giờ trong mã phía client hoặc một kho git; dùng một key riêng cho mỗi dịch vụ để bạn có thể thu hồi một key mà không làm hỏng các key khác.
• Theo dõi các header X-Quota-Used và X-Quota-Limit (hoặc thăm dò GET /usage) và điều tiết trước khi bạn chạm giới hạn, không phải sau.
• Với 429, tôn trọng Retry-After và lùi lại; với 403 plan_required, hiển thị một lời nhắc nâng cấp thay vì thử lại.
• Với các phản ứng thời gian thực, ưu tiên webhook hơn thăm dò — để Telm đẩy các sự kiện đến bạn.
• Xoay vòng các key định kỳ, và ngay lập tức nếu một key có thể đã bị rò rỉ.

9Các kịch bản tích hợp thường gặp

API được dùng cho nhiều thứ hơn nhiều so với chỉ kiểm duyệt tin nhắn Telegram.

• Đăng ký trang web và ứng dụng: chạy văn bản hoặc tên người dùng được gửi qua POST /spam/check trước khi bạn chấp nhận một đăng ký hoặc một bình luận.
• Các bot Telegram của riêng bạn: tái sử dụng trí tuệ của Telm trong một bot mà Telm không quản lý bằng cách gọi endpoint kiểm tra từ handler của bạn.
• Cấu hình hàng loạt: dùng script cho cùng các quy tắc, danh sách trắng và cài đặt trên hàng chục nhóm với các endpoint cài đặt và quy tắc.
• Dữ liệu và cảnh báo: đăng ký webhook để truyền các sự kiện kiểm duyệt vào một kho dữ liệu, một bảng điều khiển hoặc một kênh cảnh báo theo thời gian thực.