1Moderasi yang Berbicara dengan Seluruh Stack Anda
Bot moderasi yang sepenuhnya hidup di dalam Telegram memang berguna, tetapi ia juga sebuah pulau. Keputusan yang dibuatnya — setiap pesan yang dihapusnya, setiap pengguna yang disaringnya, setiap serbuan yang dipukul mundurnya — tetap terkunci di jendela chat kecuali seseorang membuka Telegram untuk melihatnya. Untuk satu komunitas, itu tidak masalah. Untuk tim yang menjalankan moderasi sebagai bagian dari operasi yang lebih besar, itu berarti satu sistem yang paling banyak tahu tentang siapa yang menyalahgunakan ruang Anda justru adalah satu sistem yang tidak bisa berbicara dengan apa pun yang lain yang Anda jalankan.
REST API publik dan webhook menutup celah itu. Keduanya mengubah Telm dari bot yang berdiri sendiri menjadi komponen yang bisa Anda sambungkan ke perkakas yang sudah Anda miliki: sistem pemantauan dan on-call Anda, arsip kepatuhan Anda, produk Anda sendiri, dasbor internal Anda. Engine yang sama yang melindungi grup Anda menjadi sesuatu yang bisa dikueri, didengarkan, dan dikendalikan oleh sistem-sistem Anda yang lain.
Panduan ini membahas apa yang sebenarnya dipaparkan oleh API dan webhook — endpoint-nya, peristiwanya, model keamanannya — serta hal-hal konkret yang dibangun tim dengan keduanya. Semua yang di bawah ini adalah kapabilitas nyata yang tersedia hari ini; tidak ada SDK yang harus ditunggu dan tidak ada yang dijelaskan di sini yang baru sekadar rencana produk.
2REST API dan Kunci Anda
API berada di `https://api.telm.com/api/public/v1`. Ini adalah antarmuka REST biasa — Anda memanggilnya dengan permintaan HTTPS dan JSON biasa, dari bahasa apa pun, tanpa perlu pustaka klien khusus. Jika kode Anda bisa membuat permintaan HTTP, ia bisa berbicara dengan Telm.
Autentikasi memakai kunci API. Anda membuat kunci di dasbor pada Settings → API & Webhooks, dan masing-masing ditampilkan kepada Anda tepat satu kali saat dibuat — salin ke penyimpanan secret Anda saat itu juga, karena kunci itu tidak bisa diambil lagi setelahnya. Kunci berawalan `tk_live_` sehingga mudah dikenali di log dan konfigurasi. Setiap kunci membawa scope — read atau write — sehingga layanan yang hanya perlu menarik log keputusan bisa memegang kunci read-only, sementara otomatisasi yang mengubah pengaturan mendapat kunci write. Buat satu kunci per sistem, dan mencabut kunci yang bocor atau pensiun tidak pernah mengganggu yang lain.
Penggunaan diatur oleh kuota permintaan harian yang terikat pada paket Anda, sehingga throughput dapat diprediksi dan satu skrip yang lepas kendali tidak bisa menghabiskan segalanya. Pemeriksaan paling ringan — pemindaian spam teks — tersedia di semua paket dalam batas kuota itu; permukaan yang lebih lengkap, mulai dari jurnal keputusan hingga manajemen pengaturan hingga webhook, adalah bagian dari paket Pro dan Business. Angka pastinya dijabarkan di bagian akhir.
3Menyaring Teks dan Pengguna Sesuai Permintaan
Dua endpoint memungkinkan Anda menjalankan penilaian Telm sesuai permintaan, dari kode Anda sendiri, tanpa sebuah pesan pun perlu melewati grup Telegram.
`POST /spam/check` mengirim sepotong teks melalui engine produksi persis yang menjaga komunitas Anda — sinyal spammer bersama, aturan pola, para pengklasifikasi — dan mengembalikan sebuah vonis. Inilah satu panggilan yang tersedia di semua paket, yang menjadikannya filter spam alami untuk produk Anda sendiri: saring komentar, bio pendaftaran, tiket dukungan, atau daftar marketplace dengan deteksi yang sama yang melindungi ruang Telegram Anda. Tambahkan `include_ai` untuk melipatkan vonis AI bagi kasus yang lebih sulit dan lebih ambigu (tersedia di Pro dan Business), dan pada paket tersebut Anda bisa mem-batch hingga dua puluh teks dalam satu permintaan alih-alih memanggil satu per satu.
`POST /users/check` menyaring seseorang, bukan sebuah pesan. Ia menggabungkan blocklist CAS global, dataset milik Telm sendiri yang dibangun dari moderasi di banyak komunitas, dan mengembalikan tingkat risiko (di Pro dan Business) sehingga Anda bisa memutuskan seberapa besar hambatan yang diterapkan — loloskan akun bersih langsung, tahan yang berisiko untuk ditinjau. Menyambungkannya ke proses onboarding Anda sendiri memungkinkan Anda menangkap pelaku jahat yang sudah dikenal di depan pintu situs web atau aplikasi Anda, bukan baru setelah mereka bergabung ke grup Telegram.
Kedua panggilan menjawab secara inline: Anda mengirim teks atau pengguna, Anda menerima penilaiannya kembali dalam respons. Tidak ada antrean untuk di-polling dan tidak ada callback untuk ditunggu — keputusan datang bersama balasannya.
4Didorong pada Saat Kejadiannya
Melakukan polling ke jurnal cocok untuk pengarsipan, tetapi ketika Anda ingin *bereaksi* terhadap sesuatu pada saat kejadiannya, Anda ingin didorong, bukan bertanya. Webhook (di Pro dan Business) melakukan tepat itu: Anda mendaftarkan sebuah endpoint, dan Telm mengirimkan permintaan HTTP ke sana pada saat peristiwa yang relevan terpicu. Peristiwanya mencakup momen-momen yang penting — `spam.detected` dan `message.suspicious` untuk konten, serta `user.banned`, `user.kicked`, `user.muted`, `user.joined`, dan `user.left` untuk keanggotaan.
Penggunaan yang paling jelas adalah mengubah gelombang spam menjadi sebuah peringatan. Arahkan `spam.detected` ke sistem pemantauan atau on-call Anda dan lonjakan mendadak menjadi panggilan ke siapa pun yang sedang bertugas, di tempat yang sama dengan insiden Anda yang lain — tak seorang pun harus mengawasi Telegram untuk menyadari serangan yang mulai terjadi. Aliran yang sama memberi makan dasbor real-time, menjaga sistem eksternal tetap sinkron dengan ban, atau memicu alur kerja apa pun yang Anda suka.
Karena permintaan ini datang dari dunia luar ke infrastruktur Anda, setiap pengiriman ditandatangani. Setiap permintaan membawa header `X-Telm-Signature` berbentuk `v1=hex(hmac_sha256(secret, "timestamp.body"))` — sebuah HMAC-SHA256 atas timestamp dan body mentah, dengan kunci secret yang hanya Anda dan Telm ketahui. Menghitung ulang tanda tangan itu di sisi Anda membuktikan bahwa permintaan benar-benar berasal dari Telm dan tidak dipalsukan atau dirusak dalam perjalanan; timestamp memungkinkan Anda menolak replay yang basi. Verifikasi tanda tangan sebelum Anda memercayai payload — itu hanya beberapa baris kode dan langkah tunggal yang paling penting dalam penerima webhook yang aman.
5Pengiriman yang Bisa Anda Andalkan
Model push hanya bisa dipercaya jika ia mampu mengatasi saat-saat endpoint Anda lambat, sedang restart, atau sebentar mati — dan milik Telm mampu. Pengiriman bersifat setidaknya-sekali: setiap peristiwa membawa `id` yang stabil, dan Telm terus mencoba hingga endpoint Anda mengonfirmasinya. Karena setidaknya-sekali berarti peristiwa yang sama bisa saja tiba dua kali secara sah, deduplikasikan berdasarkan `id` itu — catat yang sudah Anda proses dan abaikan pengulangan — sehingga penanganan Anda tetap benar berapa kali pun sebuah pengiriman dicoba ulang.
Percobaan ulang mengikuti jadwal yang kian melebar alih-alih menghantam endpoint yang sedang kesulitan: segera, lalu setelah satu menit, lima menit, tiga puluh menit, dua jam, dan enam jam — enam percobaan seluruhnya, tersebar untuk memberi ruang bagi layanan yang sedang pulih agar bisa kembali. Jika sebuah endpoint tetap rusak — dua puluh kegagalan berturut-turut dan tujuh puluh dua jam tanpa pengiriman berhasil — Telm berhenti mengirim ke sana secara otomatis dan memberi tahu Anda di Telegram, sehingga URL yang mati menjadi peringatan yang jelas untuk memperbaiki penerima Anda, bukan aliran deras kegagalan senyap yang menumpuk.
Untuk membuat integrasi baru berjalan benar, Anda tidak harus memancing peristiwa nyata untuk mengujinya. Sebuah test ping memungkinkan Anda menembakkan pengiriman contoh ke endpoint Anda sesuai permintaan dan memastikan pemeriksaan tanda tangan serta handler Anda bekerja, dan riwayat pengiriman menampilkan apa yang dikirim dan bagaimana setiap percobaan berjalan — sehingga Anda bisa men-debug penerima yang berperilaku salah dari catatan alih-alih menebak-nebak.
6Catatan yang Dapat Dikueri untuk Setiap Keputusan
Semua yang diputuskan engine dicatat, dan `GET journal` menyerahkan catatan itu ke kode Anda. Setiap entri adalah satu keputusan: vonis, skor di baliknya, aturan mana yang terpicu, dan tindakan yang menyusul. Karena menggunakan paginasi kursor, Anda bisa menyusuri seluruh riwayat dengan andal — halaman demi halaman, tanpa celah atau duplikat — dan menariknya ke mana pun Anda menyimpan catatan.
Itulah yang menjadikan jurnal sebagai tulang punggung arsip kepatuhan. Tim yang harus menunjukkan mengapa seorang anggota dikeluarkan — untuk kebijakan platform, kontrak klien, atau regulator — mengekspor log ke penyimpanan jangka panjang mereka sendiri secara terjadwal, memberi mereka catatan independen yang dapat dikueri atas setiap tindakan penegakan yang tidak bergantung pada menggulir kembali Telegram. Ini adalah bukti yang sama yang disajikan log audit dasbor kepada manusia, kini tersedia untuk sistem Anda.
Di sampingnya, sebuah endpoint analitik mengembalikan rangkaian hari demi hari — volume dan tren dari waktu ke waktu — sehingga Anda bisa memetakan beban moderasi di perkakas business-intelligence Anda sendiri berdampingan dengan segala hal lain yang Anda lacak, alih-alih membacanya dari layar. Baik jurnal maupun analitik adalah bagian dari paket Pro dan Business.
7Mengelola Banyak Grup dari Kode
API tidak hanya membaca dan mendengarkan — ia juga menulis. Di Pro dan Business Anda bisa mem-`PATCH` pengaturan sebuah grup dan menjalankan create/read/update/delete penuh pada aturan dan whitelist-nya, semuanya secara terprogram. Apa pun yang biasa Anda konfigurasikan secara manual di dasbor, bisa Anda konfigurasikan dari sebuah skrip.
Itulah yang membuat menjalankan moderasi dalam skala besar menjadi praktis. Sebuah agensi atau operator besar yang mengelola puluhan komunitas tidak ingin membuka satu per satu dan mengeklik perubahan yang sama; mereka ingin mendefinisikan kebijakan sekali dan menerapkannya di mana-mana. Dengan API Anda menggulirkan aturan baru, menyesuaikan ambang batas, atau menambahkan sebuah alamat ke setiap whitelist di seluruh armada dalam satu jalur otomatis, dan menjaga grup-grup tetap seragam saat standar Anda berkembang.
Ia juga memungkinkan kebijakan moderasi hidup di kontrol sumber Anda sendiri. Simpan konfigurasi yang diinginkan sebagai kode, terapkan melalui API, dan setiap perubahan pada cara grup Anda diatur ditinjau dan diberi versi seperti bagian lain dari infrastruktur Anda — jauh berbeda dari mengingat pengaturan mana yang Anda ubah di chat mana.
8Apa yang Termasuk di Setiap Paket
Garis pembatasnya sederhana. Pemeriksaan spam teks tersedia di semua paket, sehingga bahkan tingkat gratis pun bisa memakai deteksi Telm sebagai filter di produknya sendiri. Permukaan lengkap — penyaringan pengguna dengan tingkat risiko, jurnal keputusan dan analitik, manajemen pengaturan dan aturan, serta webhook — adalah bagian dari paket Pro dan Business.
Setiap paket mendapat kuota permintaan harian, yang diukur agar integrasi yang lebih berat berada di paket yang lebih tinggi:
- **Free** — 100 permintaan API per hari, hanya pemeriksaan spam.
- **Basic** — 1.000 permintaan API per hari, hanya pemeriksaan spam.
- **Pro** — 10.000 permintaan API per hari, plus permukaan API lengkap dan webhook.
- **Business** — 50.000 permintaan API per hari, plus permukaan API lengkap dan webhook.
- Buat kunci Anda pada Settings → API & Webhooks, simpan di penyimpanan secret Anda, verifikasi tanda tangan setiap webhook, dan engine yang sama yang menjaga grup Anda menjadi bagian dari stack Anda sendiri.