1Mỗi gói bao gồm những gì
Ranh giới phân chia rất đơn giản. Kiểm tra spam văn bản có trên mọi gói, nên ngay cả bậc miễn phí cũng có thể dùng khả năng phát hiện của Telm làm một bộ lọc trong sản phẩm của riêng mình. Bề mặt đầy đủ — sàng lọc người dùng kèm mức độ rủi ro, nhật ký quyết định và phân tích, quản lý thiết lập và quy tắc, và webhook — là một phần của các gói Pro và Business.
Mọi gói đều có một hạn mức yêu cầu hằng ngày, được định cỡ để các tích hợp nặng hơn nằm trên các gói nặng hơn:
- **Free** — 100 yêu cầu API mỗi ngày, chỉ kiểm tra spam.
- **Basic** — 1.000 yêu cầu API mỗi ngày, chỉ kiểm tra spam.
- **Pro** — 10.000 yêu cầu API mỗi ngày, cùng toàn bộ bề mặt API và webhook.
- **Business** — 50.000 yêu cầu API mỗi ngày, cùng toàn bộ bề mặt API và webhook.
- Tạo các khóa của bạn ở mục Cài đặt → API & Webhooks, giữ chúng trong kho bí mật, xác minh chữ ký của mọi webhook, và chính bộ máy canh giữ các nhóm của bạn trở thành một phần của stack của riêng bạn.
2Một bản ghi truy vấn được về mọi quyết định
Mọi điều bộ máy quyết định đều được ghi lại, và `GET journal` trao bản ghi đó cho mã của bạn. Mỗi mục là một quyết định: phán quyết, điểm số đằng sau nó, quy tắc nào đã kích hoạt, và hành động đi kèm. Vì nó phân trang bằng con trỏ (cursor), bạn có thể đi hết toàn bộ lịch sử một cách đáng tin cậy — trang này qua trang khác, không khoảng trống hay bản trùng — và kéo nó vào bất cứ nơi nào bạn lưu hồ sơ.
Điều đó khiến nhật ký trở thành xương sống của một kho lưu trữ tuân thủ. Các đội buộc phải chứng minh vì sao một thành viên bị loại — cho một chính sách nền tảng, một hợp đồng khách hàng, hay một cơ quan quản lý — xuất nhật ký vào kho dài hạn của riêng họ theo lịch, cho họ một bản ghi độc lập, truy vấn được về mọi hành động thực thi mà không phụ thuộc vào việc cuộn ngược qua Telegram. Đó chính là bằng chứng mà nhật ký kiểm toán trên bảng điều khiển trình cho con người, được đưa tới các hệ thống của bạn.
Cạnh nó, một endpoint phân tích trả về các chuỗi theo từng ngày — khối lượng và xu hướng theo thời gian — để bạn có thể vẽ tải kiểm duyệt trong các công cụ business-intelligence của riêng mình, cạnh mọi thứ khác bạn theo dõi, thay vì đọc nó trên một màn hình. Cả nhật ký lẫn phân tích đều là một phần của các gói Pro và Business.
3Việc gửi bạn có thể tin cậy
Một mô hình đẩy chỉ đáng tin nếu nó xoay xở được với những lúc endpoint của bạn chậm, đang khởi động lại, hay sập trong chốc lát — và mô hình của Telm làm được. Việc gửi là ít nhất một lần: mỗi sự kiện mang một `id` ổn định, và Telm cứ thử cho tới khi endpoint của bạn xác nhận nó. Vì ít nhất một lần nghĩa là cùng một sự kiện có thể chính đáng tới hai lần, hãy chống trùng dựa trên `id` đó — ghi lại những cái bạn đã xử lý và bỏ qua các bản lặp — và việc xử lý của bạn vẫn đúng dù một lượt gửi được thử lại bao nhiêu lần.
Các lần gửi lại theo một lịch giãn rộng dần thay vì nện dồn một endpoint đang chật vật: ngay lập tức, rồi sau một phút, năm phút, ba mươi phút, hai giờ, và sáu giờ — sáu lần thử tất cả, trải ra để cho một dịch vụ đang hồi phục có chỗ quay lại. Nếu một endpoint cứ hỏng — hai mươi lần thất bại liên tiếp và bảy mươi hai giờ không có lượt gửi thành công nào — Telm tự động ngừng gửi tới nó và báo cho bạn qua Telegram, để một URL chết trở thành một lời nhắc rõ ràng để sửa bên nhận của bạn thay vì một loạt thất bại âm thầm chồng chất.
Để làm đúng một tích hợp mới, bạn không phải tạo ra các sự kiện thật để kiểm thử nó. Một ping thử cho phép bạn bắn một lượt gửi mẫu tới endpoint của mình theo yêu cầu và xác nhận việc kiểm tra chữ ký cùng trình xử lý của bạn hoạt động, và một lịch sử gửi cho thấy đã gửi gì và mỗi lần thử ra sao — để bạn gỡ lỗi một bên nhận trục trặc từ bản ghi thay vì đoán mò.
4Kiểm duyệt trò chuyện được với phần còn lại của stack của bạn
Một bot kiểm duyệt sống hoàn toàn bên trong Telegram thì hữu ích, nhưng nó cũng là một ốc đảo. Những quyết định nó đưa ra — mỗi tin nhắn nó gỡ, mỗi người dùng nó sàng lọc, mỗi đợt tấn công nó đẩy lùi — bị khóa trong một cửa sổ chat trừ khi có ai đó mở Telegram lên xem. Với một cộng đồng đơn lẻ thì ổn. Với một đội vận hành kiểm duyệt như một phần của một hoạt động lớn hơn, điều đó nghĩa là hệ thống biết nhiều nhất về ai đang lạm dụng các không gian của bạn lại chính là hệ thống không thể trò chuyện với bất cứ thứ gì khác bạn đang chạy.
REST API công khai và webhook khép lại khoảng cách đó. Chúng biến Telm từ một bot khép kín thành một thành phần bạn có thể nối vào các công cụ bạn vốn đã có: hệ thống giám sát và trực on-call, kho lưu trữ tuân thủ, sản phẩm của riêng bạn, các bảng điều khiển nội bộ. Chính bộ máy bảo vệ các nhóm của bạn trở thành thứ mà các hệ thống khác của bạn có thể truy vấn, lắng nghe và điều khiển.
Hướng dẫn này trình bày những gì API và webhook thực sự cung cấp — các endpoint, các sự kiện, mô hình bảo mật — và những thứ cụ thể mà các đội xây dựng với chúng. Mọi điều bên dưới đều là một năng lực thật có sẵn hôm nay; không có SDK nào phải chờ và không có gì được mô tả ở đây mà sản phẩm chỉ mới dự định làm.
5Sàng lọc văn bản và người dùng theo yêu cầu
Hai endpoint cho phép bạn chạy phán đoán của Telm theo yêu cầu, từ chính mã của bạn, mà không cần một tin nhắn nào đi qua một nhóm Telegram.
`POST /spam/check` gửi một đoạn văn bản qua đúng bộ máy production đang canh giữ các cộng đồng của bạn — các tín hiệu spammer dùng chung, các quy tắc mẫu, các bộ phân loại — và trả về một phán quyết. Đây là lời gọi duy nhất có trên mọi gói, khiến nó trở thành một bộ lọc spam tự nhiên cho sản phẩm của riêng bạn: sàng lọc bình luận, tiểu sử đăng ký, phiếu hỗ trợ, hay tin rao trên chợ bằng chính khả năng phát hiện đang bảo vệ các không gian Telegram của bạn. Thêm `include_ai` để lồng vào một phán quyết AI cho các trường hợp khó và mơ hồ hơn (có trên Pro và Business), và trên các gói đó bạn có thể gộp tối đa hai mươi văn bản trong một yêu cầu duy nhất thay vì gọi một lần cho mỗi mục.
`POST /users/check` sàng lọc một con người thay vì một tin nhắn. Nó kết hợp danh sách chặn CAS toàn cầu, tập dữ liệu riêng của Telm dựng từ việc kiểm duyệt trên nhiều cộng đồng, và trả về một mức độ rủi ro (trên Pro và Business) để bạn quyết định đặt ra bao nhiêu rào cản — cho một tài khoản sạch đi thẳng qua, giữ một tài khoản rủi ro lại để xem xét. Nối nó vào quy trình đón người dùng của riêng bạn cho phép bạn bắt một kẻ xấu đã biết ngay tại cửa website hay ứng dụng của mình, chứ không chỉ sau khi họ đã vào một nhóm Telegram.
Cả hai lời gọi đều trả lời ngay trong luồng: bạn gửi văn bản hay người dùng, bạn nhận lại đánh giá trong phản hồi. Không có hàng đợi nào phải hỏi và không có callback nào phải chờ — quyết định tới cùng câu trả lời.
6Được đẩy ngay khoảnh khắc nó xảy ra
Hỏi (poll) nhật ký thì ổn cho việc lưu trữ, nhưng khi bạn muốn *phản ứng* với điều gì đó ngay khi nó xảy ra, bạn muốn được đẩy tới, chứ không phải đi hỏi. Webhook (trên Pro và Business) làm đúng điều đó: bạn đăng ký một endpoint, và Telm gửi tới nó một yêu cầu HTTP ngay khoảnh khắc một sự kiện liên quan phát ra. Các sự kiện bao trùm những khoảnh khắc quan trọng — `spam.detected` và `message.suspicious` cho nội dung, và `user.banned`, `user.kicked`, `user.muted`, `user.joined`, và `user.left` cho thành viên.
Cách dùng hiển nhiên là biến một đợt spam thành một cảnh báo. Trỏ `spam.detected` tới hệ thống giám sát hay trực on-call của bạn và một đợt tăng đột ngột trở thành một tiếng gọi tới người đang trực, ngay tại nơi các sự cố khác của bạn đổ về — không ai phải ngồi canh Telegram để nhận ra một cuộc tấn công đang bắt đầu. Cùng luồng đó nuôi các bảng điều khiển thời gian thực, giữ một hệ thống bên ngoài đồng bộ với các lượt cấm, hay kích hoạt bất kỳ quy trình nào bạn thích.
Vì các yêu cầu này đến từ thế giới bên ngoài vào hạ tầng của bạn, mọi lượt gửi đều có chữ ký. Mỗi yêu cầu mang một header `X-Telm-Signature` dạng `v1=hex(hmac_sha256(secret, "timestamp.body"))` — một HMAC-SHA256 trên dấu thời gian và thân tin thô, khóa bằng một bí mật chỉ bạn và Telm cùng biết. Tính lại chữ ký đó ở phía bạn chứng minh yêu cầu thật sự đến từ Telm và không bị giả mạo hay can thiệp trên đường truyền; dấu thời gian cho phép bạn từ chối các lần phát lại đã cũ. Hãy xác minh chữ ký trước khi bạn tin payload — đó là vài dòng mã và là bước quan trọng nhất trong một bên nhận webhook an toàn.
7REST API và các khóa của bạn
API nằm tại `https://api.telm.com/api/public/v1`. Đây là một giao diện REST thuần túy — bạn gọi nó bằng các yêu cầu HTTPS và JSON thông thường, từ bất kỳ ngôn ngữ nào, không cần thư viện client đặc biệt. Nếu mã của bạn tạo được một yêu cầu HTTP, nó nói chuyện được với Telm.
Xác thực bằng khóa API. Bạn tạo khóa trong bảng điều khiển ở mục Cài đặt → API & Webhooks, và mỗi khóa được hiển thị cho bạn đúng một lần khi tạo — hãy chép nó vào kho bí mật của bạn ngay lúc đó, vì sau này không thể lấy lại được. Khóa có tiền tố `tk_live_` để dễ nhận ra trong log và cấu hình. Mỗi khóa mang một phạm vi — đọc hoặc ghi — nên một dịch vụ chỉ cần kéo về nhật ký quyết định có thể giữ một khóa chỉ đọc, trong khi một tự động hóa thay đổi thiết lập thì được cấp một khóa ghi. Hãy phát một khóa cho mỗi hệ thống, và việc thu hồi một khóa bị lộ hay đã ngừng dùng không bao giờ làm phiền các khóa khác.
Mức sử dụng được điều tiết bởi một hạn mức yêu cầu hằng ngày gắn với gói của bạn, nên thông lượng có thể dự đoán và một script chạy loạn không thể vét cạn mọi thứ. Lượt kiểm tra nhẹ nhất — quét spam văn bản — có trên mọi gói trong phạm vi hạn mức đó; bề mặt đầy đủ hơn, từ nhật ký quyết định đến quản lý thiết lập đến webhook, là một phần của các gói Pro và Business. Các con số chính xác được trình bày ở cuối.
8Quản lý nhiều nhóm bằng mã
API không chỉ đọc và lắng nghe — nó còn ghi. Trên Pro và Business bạn có thể `PATCH` thiết lập của một nhóm và chạy đầy đủ tạo/đọc/cập nhật/xóa trên các quy tắc và danh sách trắng của nó, tất cả bằng lập trình. Bất cứ thứ gì bạn cấu hình bằng tay trong bảng điều khiển, bạn đều cấu hình được từ một script.
Đó là điều khiến việc vận hành kiểm duyệt ở quy mô lớn trở nên khả thi. Một agency hay một nhà vận hành lớn quản lý hàng chục cộng đồng không muốn mở từng cái và bấm qua cùng những thay đổi; họ muốn định nghĩa chính sách một lần và áp dụng nó ở khắp mọi nơi. Với API bạn triển khai một quy tắc mới, chỉnh một ngưỡng, hay thêm một địa chỉ vào mọi danh sách trắng trên toàn bộ đội nhóm trong một lượt tự động duy nhất, và giữ các nhóm bước đều khi tiêu chuẩn của bạn tiến hóa.
Nó cũng cho phép chính sách kiểm duyệt sống trong hệ thống quản lý mã nguồn của riêng bạn. Giữ cấu hình mong muốn dưới dạng mã, áp dụng nó qua API, và mọi thay đổi về cách các nhóm của bạn được quản trị đều được rà soát và gắn phiên bản như phần còn lại của hạ tầng — khác xa việc phải nhớ đã bật thiết lập nào trong chat nào.