REST API — otomatiskan Telm dari kode Anda sendiri

1Apa yang bisa Anda lakukan dengan API

REST API Telm memberi kode Anda jangkauan yang sama dengan dashboard: jalankan teks apa pun melalui pipeline anti-spam, periksa pengguna Telegram sebelum Anda mengizinkannya masuk, baca dan ubah pengaturan perlindungan grup, kelola aturan kustom dan whitelist, tarik jurnal moderasi dan analitik, serta daftarkan webhook untuk peristiwa waktu nyata.

Dengan begitu, Telm bukan lagi sekadar bot yang tinggal di dalam grup Anda, melainkan infrastruktur yang bisa Anda sambungkan di mana saja — formulir pendaftaran situs web, bot CRM, bot Telegram Anda sendiri, atau skrip yang mengonfigurasi seratus grup sekaligus.

• URL dasar: api.telm.com/api/public/v1 — jalur berversi yang stabil (v1 adalah versi kontraknya).
• Setiap permintaan dan respons berformat JSON melalui HTTPS.
• Dokumentasi interaktif dan spesifikasi OpenAPI 3.1 yang dapat dibaca mesin tersedia di halaman developer — muat spesifikasi ke Postman, generator kode, atau agen AI untuk menyusun kerangka integrasi dalam hitungan menit.
• Panggilan terukur mengembalikan header X-Quota-Limit, X-Quota-Used, dan X-Quota-Reset di setiap respons.

2Bagaimana permintaan mengalir melalui Telm

API publik berada di prefiks jalurnya sendiri, /api/public/, terpisah dari dashboard. Setiap panggilan diautentikasi dengan kunci API, bukan sesi browser, diperiksa terhadap paket dan kuota Anda, dijalankan pada mesin langsung yang sama yang memoderasi grup Anda, lalu dikembalikan sebagai JSON.

Karena API menjangkau mesin dan data yang sama dengan bot, apa pun yang dapat Anda lihat atau ubah di dashboard juga dapat Anda lakukan lewat kode — dan setiap perubahan yang Anda buat lewat kode langsung muncul di dashboard.

• Permintaan tidak menyimpan status: setiap permintaan membawa kuncinya sendiri dan berdiri sendiri.
• Sebuah kunci bertindak atas nama akun Anda dan hanya dapat menyentuh grup tempat akun Anda menjadi admin.
• Endpoint pemeriksaan spam menjangkau pipeline aturan produksi yang persis sama, sehingga vonis API sesuai dengan apa yang akan dilakukan bot di grup.

3Autentikasi dengan kunci API

Setiap permintaan diautentikasi dengan kunci API berbentuk tk_live_ diikuti karakter acak — bukan dengan login dashboard Anda. Anda membuat kunci di akun Anda dan mengirimkannya di header Authorization sebagai token Bearer, atau di header X-API-Key.

Rahasia lengkapnya ditampilkan sekali, saat pembuatan. Setelah itu dashboard hanya menampilkan kunci berdasarkan prefiks pendeknya, sehingga Anda dapat mengenalinya tanpa pernah menyimpan nilai lengkapnya. Jika sebuah kunci bocor, cabut kunci tersebut dan terbitkan yang baru — pencabutan langsung berlaku.

• Kirim kunci sebagai Authorization: Bearer tk_live_your_key_here (header X-API-Key juga bisa digunakan).
• Kunci memiliki cakupan baca atau tulis — baca untuk permintaan GET, tulis untuk apa pun yang mengubah data. Kunci khusus baca tidak dapat membuat atau mengedit.
• Anda dapat memiliki hingga sepuluh kunci aktif sekaligus, sehingga bisa memakai kunci terpisah untuk setiap skrip atau layanan.
• Kunci yang tidak ada atau tidak valid mengembalikan 401; kunci tanpa cakupan yang diperlukan mengembalikan 403 insufficient_scope.

4Endpoint yang tersedia

API disusun di sekitar pemeriksaan spam dan pengguna, pengelolaan grup, serta layanan mandiri akun. Endpoint pemeriksaan spam tunggal terbuka untuk setiap paket; bagian API lainnya merupakan bagian dari Pro dan Business.

• POST /spam/check — jalankan satu teks melalui mesin aturan yang sama yang memoderasi lalu lintas langsung (setiap paket). Pemeriksaan AI opsional dapat diaktifkan di Pro ke atas.
• POST /spam/check-batch — periksa hingga 20 teks dalam satu panggilan, hanya berbasis aturan (Pro+).
• POST /users/check — periksa pengguna Telegram: status CAS, sinyal keputusan spam Telm, dan reputasi di grup Anda (Pro+).
• GET /groups dan GET /groups/{id} — tampilkan daftar dan baca grup Anda (Pro+).
• GET dan PATCH /groups/{id}/settings — baca dan ubah pengaturan perlindungan grup (Pro+).
• GET/POST/PUT/DELETE /groups/{id}/rules — kelola aturan moderasi kustom (Pro+).
• GET/POST/DELETE /groups/{id}/whitelist — kelola whitelist grup (Pro+).
• GET /groups/{id}/journal dan GET /groups/{id}/analytics — baca jurnal moderasi dan analitik (Pro+).
• GET/POST/PATCH/DELETE /webhooks — kelola webhook untuk peristiwa waktu nyata (Pro+).
• GET /usage dan GET /me — periksa kuota dan informasi kunci Anda; keduanya tidak pernah memakai kuota (setiap paket).

5Rincian endpoint pemeriksaan spam

POST /spam/check adalah inti API dan satu-satunya endpoint yang dapat Anda coba di paket apa pun. Kirim body JSON berisi teks yang akan diperiksa; respons mengembalikan vonis, skor numerik, nilai keyakinan, dan tindakan yang direkomendasikan yang dapat Anda terapkan di produk Anda sendiri.

Satu teks dapat berisi hingga 10.000 karakter. Di Pro ke atas, Anda dapat memilih pemeriksaan AI untuk kasus yang lebih sulit, yang diambil dari jatah pemeriksaan AI harian tersendiri. Untuk volume tinggi, endpoint batch memeriksa hingga 20 teks dalam satu panggilan dan menghitung kuota per item.

• Gunakan vonis dan skor untuk memutuskan apa yang dilakukan produk Anda — memblokir pengiriman formulir, menandai calon pelanggan, atau menghapus pesan secara otomatis di bot Anda sendiri.
• Endpoint batch hanya berbasis aturan; level AI hanya tersedia di endpoint teks tunggal.
• Ukuran body permintaan dibatasi (sekitar 64 KB untuk satu pemeriksaan, 256 KB untuk batch); body yang terlalu besar mengembalikan 413.

6Paket, batas laju, dan kuota harian

Akses diukur dengan dua cara: batas laju per menit (batas lonjakan) dan kuota panggilan harian yang diatur ulang pada tengah malam UTC. Keduanya dihitung per akun dan dibagi ke semua kunci API Anda. Anda dapat mencoba endpoint pemeriksaan spam tunggal di paket apa pun, tetapi integrasi nyata yang menyentuh aturan, pengaturan, pemeriksaan batch, dan webhook memerlukan Pro atau lebih tinggi.

• Free — 100 panggilan/hari, hanya pemeriksaan spam.
• Pro — 10.000 panggilan/hari, API lengkap dan webhook, plus 1.000 pemeriksaan AI per hari.
• Business — 50.000 panggilan/hari, API lengkap dan webhook, plus 10.000 pemeriksaan AI per hari.
• Batas laju per menit juga ikut naik — 60 permintaan per menit di Free, 600 di Pro, dan 1.800 di Business.
• GET /usage dan GET /me tidak pernah dihitung terhadap kuota Anda, sehingga Anda dapat memeriksa sisa anggaran kapan saja.

7Penanganan kesalahan dan kode status

API menggunakan kode status HTTP standar dengan kode kesalahan yang dapat dibaca mesin di body. Rancang klien Anda agar membaca kode-kode ini lalu mundur atau menampilkan ajakan untuk meningkatkan paket, alih-alih mencoba ulang secara membabi buta.

Saat Anda melampaui kuota harian, panggilan terukur mengembalikan 429 dengan kode daily_quota_exceeded, header Retry-After, dan body yang mencantumkan paket, batas, jumlah terpakai, waktu pengaturan ulang, serta petunjuk peningkatan paket. Endpoint yang memerlukan paket lebih tinggi mengembalikan 403 plan_required beserta paket yang dibutuhkan.

• 401 — kunci API tidak ada atau tidak valid.
• 403 plan_required — endpoint memerlukan Pro atau lebih tinggi.
• 403 insufficient_scope — kunci tidak memiliki cakupan tulis untuk panggilan yang mengubah data.
• 429 daily_quota_exceeded atau rate_limit_exceeded — tunggu hingga waktu pengaturan ulang atau tingkatkan paket; patuhi header Retry-After.
• Baca header respons X-Quota-* agar selalu selangkah di depan batas.

8Praktik terbaik untuk integrasi yang andal

Beberapa kebiasaan menjaga integrasi tetap andal dan aman seiring pertumbuhannya.

• Simpan kunci di pengelola rahasia, jangan pernah di kode sisi klien atau repositori git; gunakan kunci terpisah per layanan agar Anda dapat mencabut satu kunci tanpa merusak yang lain.
• Pantau header X-Quota-Used dan X-Quota-Limit (atau periksa GET /usage secara berkala) dan perlambat permintaan sebelum Anda menabrak batas, bukan sesudahnya.
• Pada 429, patuhi Retry-After dan mundur sejenak; pada 403 plan_required, tampilkan ajakan untuk meningkatkan paket alih-alih mencoba ulang.
• Untuk reaksi waktu nyata, utamakan webhook daripada polling — biarkan Telm yang mengirim peristiwa kepada Anda.
• Rotasi kunci secara berkala, dan segera jika ada kemungkinan sebuah kunci bocor.

9Skenario integrasi umum

API digunakan untuk jauh lebih banyak hal daripada sekadar memoderasi pesan Telegram.

• Pendaftaran di situs web dan aplikasi: jalankan teks atau nama pengguna yang dikirim melalui POST /spam/check sebelum Anda menerima pendaftaran atau komentar.
• Bot Telegram Anda sendiri: manfaatkan kecerdasan Telm di bot yang tidak dikelola Telm dengan memanggil endpoint pemeriksaan dari kode penangan bot Anda.
• Konfigurasi massal: terapkan aturan, whitelist, dan pengaturan yang sama ke puluhan grup lewat skrip dengan endpoint pengaturan dan aturan.
• Data dan peringatan: daftarkan webhook untuk mengalirkan peristiwa moderasi ke gudang data, dashboard, atau saluran peringatan secara waktu nyata.