REST API — automasikan Telm daripada kod anda sendiri

1Apa yang boleh anda lakukan dengan API

REST API Telm memberi kod anda sendiri jangkauan yang sama seperti papan pemuka: jalankan sebarang teks melalui saluran anti-spam, semak pengguna Telegram sebelum anda membenarkan mereka masuk, baca dan ubah tetapan perlindungan kumpulan, urus peraturan tersuai dan senarai putih, tarik jurnal moderasi dan analitik, serta daftar webhook untuk peristiwa masa nyata.

Ini menjadikan Telm bukan sekadar bot di dalam kumpulan anda, tetapi infrastruktur yang boleh anda sambungkan di mana-mana sahaja — borang pendaftaran laman web, bot CRM, bot Telegram anda sendiri, atau skrip yang mengkonfigurasi seratus kumpulan sekali gus.

• URL asas: api.telm.com/api/public/v1 — laluan yang stabil dan berversi (v1 ialah versi kontrak).
• Setiap permintaan dan respons ialah JSON melalui HTTPS.
• Dokumentasi interaktif dan spesifikasi OpenAPI 3.1 yang boleh dibaca mesin tersedia di halaman pembangun — muatkan spesifikasi itu ke dalam Postman, penjana kod atau ejen AI untuk membina rangka integrasi dalam beberapa minit.
• Panggilan bermeter memulangkan pengepala X-Quota-Limit, X-Quota-Used dan X-Quota-Reset pada setiap respons.

2Bagaimana permintaan bergerak melalui Telm

API awam berada pada awalan laluannya sendiri, /api/public/, berasingan daripada papan pemuka. Setiap panggilan disahkan dengan kunci API dan bukannya sesi pelayar, disemak terhadap pelan dan kuota anda, dijalankan pada enjin langsung yang sama yang memoderasi kumpulan anda, dan dipulangkan sebagai JSON.

Oleh sebab API mencapai enjin dan data yang sama seperti bot, apa sahaja yang boleh anda lihat atau ubah dalam papan pemuka juga boleh dilakukan dalam kod — dan sebarang perubahan yang anda buat dalam kod muncul dalam papan pemuka serta-merta.

• Permintaan adalah tanpa keadaan: setiap satu membawa kuncinya sendiri dan berdiri sendiri.
• Kunci bertindak bagi pihak akaun anda dan hanya boleh menyentuh kumpulan di mana akaun anda ialah pentadbir.
• Titik akhir semakan spam mencapai saluran peraturan produksi yang sama, jadi keputusan API sepadan dengan apa yang akan dilakukan bot dalam kumpulan.

3Pengesahan dengan kunci API

Setiap permintaan disahkan dengan kunci API dalam bentuk tk_live_ diikuti oleh aksara rawak — bukan log masuk papan pemuka anda. Anda mencipta kunci dalam akaun anda dan menghantarnya dalam pengepala Authorization sebagai token Bearer, atau dalam pengepala X-API-Key.

Rahsia penuh dipaparkan sekali sahaja, semasa kunci dicipta. Selepas itu papan pemuka menyenaraikan kunci hanya mengikut awalan pendeknya, supaya anda boleh mengenalinya tanpa perlu menyimpan nilai penuh. Jika kunci bocor, batalkannya dan keluarkan kunci baharu — pembatalan berkuat kuasa serta-merta.

• Hantar kunci sebagai Authorization: Bearer tk_live_your_key_here (pengepala X-API-Key juga berfungsi).
• Kunci membawa skop baca atau tulis — baca untuk permintaan GET, tulis untuk apa-apa yang mengubah data. Kunci baca sahaja tidak boleh mencipta atau mengedit.
• Anda boleh memegang sehingga sepuluh kunci aktif serentak, jadi anda boleh menggunakan kunci berasingan bagi setiap skrip atau perkhidmatan.
• Kunci yang hilang atau tidak sah memulangkan 401; kunci tanpa skop yang diperlukan memulangkan 403 insufficient_scope.

4Titik akhir yang tersedia

API disusun mengikut semakan spam dan pengguna, pengurusan kumpulan, serta layan diri akaun. Titik akhir semakan spam tunggal terbuka kepada setiap pelan; bahagian API selebihnya adalah sebahagian daripada Pro dan Business.

• POST /spam/check — jalankan satu teks melalui enjin peraturan yang sama yang memoderasi trafik langsung (setiap pelan). Semakan AI pilihan boleh didayakan pada Pro ke atas.
• POST /spam/check-batch — semak sehingga 20 teks dalam satu panggilan, berasaskan peraturan sahaja (Pro+).
• POST /users/check — semak pengguna Telegram: status CAS, isyarat keputusan spam Telm dan reputasi dalam kumpulan anda (Pro+).
• GET /groups dan GET /groups/{id} — senaraikan dan baca kumpulan anda (Pro+).
• GET dan PATCH /groups/{id}/settings — baca dan ubah tetapan perlindungan kumpulan (Pro+).
• GET/POST/PUT/DELETE /groups/{id}/rules — urus peraturan moderasi tersuai (Pro+).
• GET/POST/DELETE /groups/{id}/whitelist — urus senarai putih kumpulan (Pro+).
• GET /groups/{id}/journal dan GET /groups/{id}/analytics — baca log moderasi dan analitik (Pro+).
• GET/POST/PATCH/DELETE /webhooks — urus webhook peristiwa masa nyata (Pro+).
• GET /usage dan GET /me — semak kuota dan maklumat kunci anda; panggilan ini tidak pernah menggunakan kuota (setiap pelan).

5Titik akhir semakan spam secara terperinci

POST /spam/check ialah teras API dan satu-satunya titik akhir yang boleh anda cuba pada mana-mana pelan. Hantar badan JSON dengan teks yang hendak disemak; respons memulangkan keputusan, skor berangka, nilai keyakinan dan tindakan yang disyorkan yang boleh anda gunakan dalam produk anda sendiri.

Satu teks boleh mencapai sehingga 10,000 aksara. Pada Pro ke atas anda boleh memilih semakan AI untuk kes yang lebih sukar, yang diambil daripada peruntukan semakan AI harian yang berasingan. Untuk volum tinggi, titik akhir berkelompok menyemak sehingga 20 teks dalam satu panggilan dan mengira kuota bagi setiap item.

• Gunakan keputusan dan skor untuk menentukan apa yang dilakukan produk anda — sekat penghantaran borang, tandakan prospek, atau buang mesej secara automatik dalam bot anda sendiri.
• Titik akhir berkelompok berasaskan peraturan sahaja; tahap AI hanya tersedia pada titik akhir teks tunggal.
• Saiz badan permintaan dihadkan (kira-kira 64 KB untuk semakan tunggal, 256 KB untuk kelompok); badan yang terlalu besar memulangkan 413.

6Pelan, had kadar dan kuota harian

Akses dimeter dalam dua cara: had kadar setiap minit (siling pecutan) dan kuota panggilan harian yang ditetapkan semula pada tengah malam UTC. Kedua-duanya dikira setiap akaun dan dikongsi merentas semua kunci API anda. Anda boleh mencuba titik akhir semakan spam tunggal pada mana-mana pelan, tetapi integrasi sebenar yang menyentuh peraturan, tetapan, semakan berkelompok dan webhook memerlukan Pro atau lebih tinggi.

• Free — 100 panggilan sehari, semakan spam sahaja.
• Pro — 10,000 panggilan sehari, API penuh dan webhook, serta 1,000 semakan AI sehari.
• Business — 50,000 panggilan sehari, API penuh dan webhook, serta 10,000 semakan AI sehari.
• Had kadar setiap minit turut meningkat — 60 permintaan seminit pada Free, 600 pada Pro dan 1,800 pada Business.
• GET /usage dan GET /me tidak pernah dikira dalam kuota anda, jadi anda boleh menyemak baki bajet anda pada bila-bila masa.

7Pengendalian ralat dan kod status

API menggunakan kod status HTTP standard dengan kod ralat yang boleh dibaca mesin dalam badan respons. Bina klien anda supaya membaca kod ini dan berundur atau memaparkan gesaan naik taraf, dan bukannya mencuba semula secara membuta tuli.

Apabila anda melebihi kuota harian, panggilan bermeter memulangkan 429 dengan kod daily_quota_exceeded, pengepala Retry-After, dan badan yang menyenaraikan pelan, had, kiraan guna, masa penetapan semula dan petunjuk naik taraf anda. Titik akhir yang memerlukan pelan lebih tinggi memulangkan 403 plan_required bersama pelan yang diperlukan.

• 401 — kunci API hilang atau tidak sah.
• 403 plan_required — titik akhir memerlukan Pro atau lebih tinggi.
• 403 insufficient_scope — kunci tiada skop tulis untuk panggilan yang mengubah data.
• 429 daily_quota_exceeded atau rate_limit_exceeded — tunggu sehingga masa penetapan semula atau naik taraf; hormati pengepala Retry-After.
• Baca pengepala respons X-Quota-* supaya anda sentiasa mendahului had.

8Amalan terbaik untuk integrasi yang mantap

Beberapa tabiat memastikan integrasi kekal boleh dipercayai dan selamat apabila ia berkembang.

• Simpan kunci dalam pengurus rahsia, jangan sekali-kali dalam kod bahagian klien atau repositori git; gunakan kunci berasingan bagi setiap perkhidmatan supaya anda boleh membatalkan satu tanpa menjejaskan yang lain.
• Pantau pengepala X-Quota-Used dan X-Quota-Limit (atau tinjau GET /usage) dan perlahankan permintaan sebelum anda mencapai had, bukan selepasnya.
• Pada 429, hormati Retry-After dan berundur; pada 403 plan_required, paparkan gesaan naik taraf dan bukannya mencuba semula.
• Untuk tindak balas masa nyata, utamakan webhook berbanding tinjauan — biar Telm menolak peristiwa kepada anda.
• Putar kunci secara berkala, dan serta-merta jika ada kunci yang mungkin telah bocor.

9Senario integrasi biasa

API digunakan untuk lebih daripada sekadar memoderasi mesej Telegram.

• Pendaftaran laman web dan aplikasi: jalankan teks atau nama pengguna yang dihantar melalui POST /spam/check sebelum anda menerima pendaftaran atau komen.
• Bot Telegram anda sendiri: gunakan semula kecerdasan Telm dalam bot yang tidak diurus oleh Telm dengan memanggil titik akhir semakan daripada pengendali anda.
• Konfigurasi pukal: skripkan peraturan, senarai putih dan tetapan yang sama merentas berpuluh-puluh kumpulan dengan titik akhir tetapan dan peraturan.
• Data dan amaran: daftar webhook untuk menstrim peristiwa moderasi ke gudang data, papan pemuka atau saluran amaran secara masa nyata.