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 bạn khả năng ngang với bảng điều khiển: chạy bất kỳ văn bản nào qua quy trình chống spam, tra cứu một người dùng Telegram trước khi cho họ vào, đọc và thay đổi cài đặt bảo vệ của nhóm, quản lý quy tắc tùy chỉnh và danh sách trắng, lấy nhật ký kiểm duyệt và dữ liệu phân tích, cũng như đăng ký webhook để nhận sự kiện theo thời gian thực.

Nhờ đó Telm không chỉ là một bot sống trong các nhóm của bạn mà trở thành hạ tầng bạn có thể nối vào bất cứ đâu — biểu mẫu đăng ký trên website, bot CRM, các bot Telegram của riêng bạn, hay một script cấu hình cả trăm nhóm cùng lúc.

• URL cơ sở: api.telm.com/api/public/v1 — một đường dẫn ổn định, có phiên bản (v1 là phiên bản 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 dạng máy đọc được có trên trang dành cho nhà phát triển — nạp đặc tả vào Postman, một trình sinh mã hoặc một AI agent để dựng khung tích hợp chỉ trong vài phút.
• Các lệnh gọi được đo lường 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, /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 khóa API thay vì phiên trình duyệt, được đối chiếu với gói và hạn mức của bạn, chạy trên chính công cụ đang kiểm duyệt các nhóm của bạn, rồi trả kết quả về dưới dạng JSON.

Vì API dùng cùng công cụ và dữ liệu với bot, mọi thứ bạn xem hoặc thay đổi được trong bảng điều khiển thì bạn cũng làm được bằng mã — và mọi thay đổi bạn thực hiện bằng mã sẽ hiển thị ngay trong bảng điều khiển.

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

3Xác thực bằng khóa API

Mọi yêu cầu được xác thực bằng một khóa API có dạng tk_live_ theo sau là 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 khóa trong tài khoản của mình và gửi khóa trong header Authorization dưới dạng token Bearer, hoặc trong header X-API-Key.

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

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

4Các endpoint khả dụng

API được tổ chức xoay quanh 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 API thuộc Pro và Business.

• POST /spam/check — chạy một văn bản qua cùng công cụ quy tắc đang kiểm duyệt lưu lượng thực (mọi gói). Trên Pro trở lên có thể bật thêm kiểm tra AI tùy chọ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 thông tin các nhóm của bạn (Pro+).
• GET và PATCH /groups/{id}/settings — đọc và thay đổi cài đặt bảo vệ của nhóm (Pro+).
• GET/POST/PUT/DELETE /groups/{id}/rules — quản lý 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à dữ liệu phân tích (Pro+).
• GET/POST/PATCH/DELETE /webhooks — quản lý webhook cho các 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 khóa của bạn; các lệnh gọi này không bao giờ tiêu tốn hạn mức (mọi gói).

5Chi tiết endpoint kiểm tra spam

POST /spam/check là trái tim của API và là endpoint duy nhất bạn có thể dùng thử trên mọi gói. Gửi một phần thân JSON chứa 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ố, một giá trị độ tin cậy và một hành động đề xuất mà bạn có thể áp dụng trong sản phẩm của mình.

Một văn bản có thể dài tối đa 10.000 ký tự. Trên Pro trở lên, bạn có thể chọn bật kiểm tra AI cho các trường hợp khó hơn, trừ vào 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 bạn sẽ làm gì — chặn một lượt gửi biểu mẫu, gắn cờ một khách hàng tiềm năng, hoặc tự động xóa tin nhắn trong bot của riêng bạn.
• Endpoint hàng loạt chỉ dùng quy tắc; các bậc kiểm tra AI chỉ khả dụng trên endpoint văn bản đơn lẻ.
• Kích thước phần thân yêu cầu bị giới hạn (khoảng 64 KB cho một lần kiểm tra đơn lẻ, 256 KB cho một lô); phần thân quá lớn sẽ trả về 413.

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

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

• Free — 100 lệnh gọi/ngày, chỉ kiểm tra spam.
• Pro — 10.000 lệnh gọi/ngày, API đầy đủ và webhook, cùng 1.000 lần kiểm tra AI mỗi ngày.
• Business — 50.000 lệnh gọi/ngày, API đầy đủ và webhook, cùng 10.000 lần kiểm tra AI mỗi ngày.
• Giới hạn tốc độ mỗi phút cũng tăng theo gói — 60 yêu cầu mỗi phút trên Free, 600 trên Pro và 1.800 trên Business.
• GET /usage và GET /me không bao giờ bị tính vào hạn mức, nên bạn có thể kiểm tra ngân sách còn lại bất cứ lúc nào.

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 kèm một mã lỗi máy đọc được trong phần thân. Hãy xây dựng client đọc các mã này rồi lùi lại hoặc gợi ý 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 đo lường trả về 429 với mã daily_quota_exceeded, một header Retry-After và phần thân liệt kê gói, giới hạn, số đã dùng, thời điểm đặt lại cùng một gợi ý nâng cấp. Các endpoint cần gói cao hơn trả về 403 plan_required kèm gói được yêu cầu.

• 401 — khóa API bị thiếu hoặc không hợp lệ.
• 403 plan_required — endpoint cần gói Pro trở lên.
• 403 insufficient_scope — khóa thiếu phạm vi ghi cho một lệnh gọi làm thay đổi dữ liệu.
• 429 daily_quota_exceeded hoặc rate_limit_exceeded — hãy chờ đến thời điểm đặ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-* để luôn đ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úp tích hợp luôn ổn định và an toàn khi nó lớn dần.

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

9Các kịch bản tích hợp phổ biến

API được dùng cho nhiều việc hơn hẳn việc kiểm duyệt tin nhắn Telegram.

• Đăng ký trên website và ứng dụng: chạy văn bản hoặc tên người dùng được gửi lên qua POST /spam/check trước khi chấp nhận một lượt đăng ký hay một bình luận.
• Các bot Telegram của riêng bạn: tận 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ừ trình xử lý của bạn.
• Cấu hình hàng loạt: dùng script áp dụng cùng quy tắc, danh sách trắng và cài đặt cho hàng chục nhóm qua các endpoint cài đặt và quy tắc.
• Dữ liệu và cảnh báo: đăng ký webhook để truyền sự kiện kiểm duyệt vào 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.