REST API — automasikan Telm daripada kod anda sendiri

1Apa yang boleh anda lakukan dengan API

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

Itu mengubah Telm daripada bot yang hidup di dalam kumpulan anda menjadi infrastruktur yang boleh anda pasang di mana-mana — borang pendaftaran laman web, bot CRM, bot Telegram anda sendiri, atau skrip yang mengkonfigurasi seratus kumpulan sekaligus.

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

2Bagaimana permintaan mengalir melalui Telm

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

Kerana API menjangkau enjin dan data yang sama seperti bot, apa sahaja yang boleh anda lihat atau tukar dalam papan pemuka boleh juga anda lakukan 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 menjangkau saluran peraturan pengeluaran yang tepat, jadi keputusan API sepadan dengan apa yang bot akan lakukan 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 menghantar kunci dalam pengepala Authorization sebagai token Bearer, atau dalam pengepala X-API-Key.

Rahsia penuh ditunjukkan sekali sahaja, pada masa penciptaan. Selepas itu papan pemuka menyenaraikan kunci hanya mengikut awalan pendeknya, jadi anda boleh mengenalinya tanpa pernah menyimpan nilai penuh. Jika kunci bocor, batalkan ia dan keluarkan yang baharu — pembatalan berkuat kuasa dalam masa kira-kira seminit.

• 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 menyunting.
• Anda boleh memegang sehingga sepuluh kunci aktif sekaligus, 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 sekitar semakan spam dan pengguna, pengurusan kumpulan, dan layan diri akaun. Titik akhir semakan spam tunggal terbuka kepada setiap pelan; 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 diaktifkan pada Pro dan ke atas.
• POST /spam/check-batch — semak sehingga 20 teks dalam satu panggilan, peraturan sahaja (Pro+).
• POST /users/check — cari 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 tukar tetapan perlindungan kumpulan (Pro+).
• GET/POST/PUT/DELETE /groups/{id}/rules — uruskan peraturan moderasi tersuai (Pro+).
• GET/POST/DELETE /groups/{id}/whitelist — uruskan senarai putih kumpulan (Pro+).
• GET /groups/{id}/journal dan GET /groups/{id}/analytics — baca log moderasi dan analitik (Pro+).
• GET/POST/PATCH/DELETE /webhooks — uruskan webhook peristiwa masa nyata (Pro+).
• GET /usage dan GET /me — semak kuota dan maklumat kunci anda; ini tidak pernah menggunakan kuota (setiap pelan).

5Titik akhir semakan spam secara terperinci

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

Satu teks boleh sehingga 10,000 aksara. Pada Pro dan ke atas anda boleh memilih semakan AI untuk kes yang lebih sukar, diambil daripada elaun 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 memutuskan apa yang produk anda sendiri lakukan — sekat penghantaran borang, tandai petunjuk, atau buang mesej secara automatik dalam bot anda sendiri.
• Titik akhir berkelompok adalah peraturan sahaja; tangga AI hanya tersedia pada titik akhir teks tunggal.
• Badan permintaan dihadkan (kira-kira 64 KB untuk semakan tunggal, 256 KB untuk kelompok); badan yang terlebih saiz memulangkan 413.

6Pelan, had kadar dan kuota harian

Akses dimeterkan dalam dua cara: had kadar setiap minit (siling ledakan) dan kuota panggilan harian yang ditetapkan semula pada tengah malam UTC. Kedua-duanya berkadar dengan pelan anda dan dikira bagi setiap akaun, dikongsi merentas semua kunci 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/hari, semakan spam sahaja.
• Basic — 1,000 panggilan/hari, semakan spam sahaja.
• Pro — 10,000 panggilan/hari, API penuh dan webhook, ditambah elaun semakan-AI harian.
• Business — 50,000 panggilan/hari, API penuh dan webhook, elaun AI yang lebih besar.
• Had kadar setiap minit turut berkadar — pelan yang lebih tinggi mendapat siling ledakan yang jauh lebih besar.

7Pengendalian ralat dan kod status

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

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

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

8Amalan terbaik untuk integrasi yang kukuh

Beberapa tabiat memastikan integrasi 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 merosakkan yang lain.
• Perhatikan 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, tunjukkan gesaan naik taraf dan bukannya mencuba semula.
• Untuk tindak balas masa nyata, utamakan webhook berbanding tinjauan — biarkan Telm menolak peristiwa kepada anda.
• Tukar kunci secara berkala, dan segera jika satu 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 diuruskan 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 menstrimkan peristiwa moderasi ke dalam gudang data, papan pemuka atau saluran amaran secara masa nyata.