REST API — Telm'i kendi kodunuzdan otomatikleştirin

1API ile neler yapabilirsiniz

Telm REST API, kendi kodunuza kontrol paneliyle aynı erişimi verir: herhangi bir metni anti-spam işlem hattından geçirin, bir Telegram kullanıcısını içeri almadan önce sorgulayın, bir grubun koruma ayarlarını okuyun ve değiştirin, özel kuralları ve beyaz listeleri yönetin, moderasyon günlüğünü ve analitiği çekin, gerçek zamanlı olaylar için webhook kaydedin.

Böylece Telm, gruplarınızın içinde yaşayan bir bottan her yere bağlayabileceğiniz bir altyapıya dönüşür — bir web sitesi kayıt formu, bir CRM botu, kendi Telegram botlarınız veya yüz grubu aynı anda yapılandıran bir betik.

• Temel URL: api.telm.com/api/public/v1 — kararlı, sürümlenmiş bir yol (v1, sözleşme sürümüdür).
• Her istek ve yanıt HTTPS üzerinden JSON biçimindedir.
• Etkileşimli belgeler ve makine tarafından okunabilir OpenAPI 3.1 spesifikasyonu geliştiriciler sayfasındadır — bir entegrasyonun iskeletini dakikalar içinde çıkarmak için spesifikasyonu Postman'e, bir kod üretecine veya bir AI ajanına yükleyin.
• Ölçülen çağrılar her yanıtta X-Quota-Limit, X-Quota-Used ve X-Quota-Reset başlıklarını döndürür.

2Bir istek Telm içinde nasıl ilerler

Herkese açık API, kontrol panelinden ayrı olarak kendi yol önekinde, /api/public/ altında çalışır. Her çağrı bir tarayıcı oturumuyla değil, bir API anahtarıyla kimlik doğrulanır, planınıza ve kotanıza göre kontrol edilir, gruplarınızı denetleyen aynı canlı motorda çalıştırılır ve JSON olarak döndürülür.

API, botla aynı motora ve verilere ulaştığı için kontrol panelinde görebildiğiniz veya değiştirebildiğiniz her şeyi kodla da yapabilirsiniz — ve kodla yaptığınız her değişiklik kontrol panelinde hemen görünür.

• İstekler durumsuzdur: her biri kendi anahtarını taşır ve kendi başına geçerlidir.
• Bir anahtar hesabınız adına hareket eder ve yalnızca hesabınızın yönetici olduğu gruplara dokunabilir.
• Spam kontrol uç noktası üretimdeki kural hattının ta kendisine ulaşır, dolayısıyla bir API kararı botun grupta yapacağıyla eşleşir.

3API anahtarlarıyla kimlik doğrulama

Her istek, kontrol paneli girişinizle değil, tk_live_ ve ardından gelen rastgele karakterlerden oluşan bir API anahtarıyla kimlik doğrulanır. Anahtarları hesabınızda oluşturur ve anahtarı Authorization başlığında Bearer token olarak ya da bir X-API-Key başlığında gönderirsiniz.

Tam gizli değer yalnızca bir kez, oluşturma anında gösterilir. Sonrasında kontrol paneli bir anahtarı yalnızca kısa önekiyle listeler; böylece tam değeri hiç saklamadan onu tanıyabilirsiniz. Bir anahtar sızarsa onu iptal edin ve yenisini oluşturun — iptal hemen yürürlüğe girer.

• Anahtarı Authorization: Bearer tk_live_your_key_here olarak gönderin (bir X-API-Key başlığı da çalışır).
• Anahtarlar okuma veya yazma kapsamı taşır — GET istekleri için okuma, veriyi değiştiren her şey için yazma. Salt okunur bir anahtar oluşturma veya düzenleme yapamaz.
• Aynı anda en fazla on etkin anahtar tutabilirsiniz; böylece her betik veya hizmet için ayrı bir anahtar kullanabilirsiniz.
• Eksik veya geçersiz bir anahtar 401 döndürür; gerekli kapsama sahip olmayan bir anahtar 403 insufficient_scope döndürür.

4Kullanılabilir uç noktalar

API; spam ve kullanıcı kontrolleri, grup yönetimi ve hesap işlemleri etrafında düzenlenmiştir. Tekli spam kontrol uç noktası her plana açıktır; geri kalanı Pro ve Business planlarına dahildir.

• POST /spam/check — tek bir metni canlı trafiği denetleyen aynı kural motorundan geçirin (her plan). Pro ve üzerinde isteğe bağlı bir AI kontrolü etkinleştirilebilir.
• POST /spam/check-batch — tek çağrıda 20 metne kadar kontrol edin, yalnızca kurallarla (Pro+).
• POST /users/check — bir Telegram kullanıcısını sorgulayın: CAS durumu, Telm spam kararı sinyalleri ve gruplarınızdaki itibarı (Pro+).
• GET /groups ve GET /groups/{id} — gruplarınızı listeleyin ve okuyun (Pro+).
• GET ve PATCH /groups/{id}/settings — bir grubun koruma ayarlarını okuyun ve değiştirin (Pro+).
• GET/POST/PUT/DELETE /groups/{id}/rules — özel moderasyon kurallarını yönetin (Pro+).
• GET/POST/DELETE /groups/{id}/whitelist — grubun beyaz listesini yönetin (Pro+).
• GET /groups/{id}/journal ve GET /groups/{id}/analytics — moderasyon günlüğünü ve analitiği okuyun (Pro+).
• GET/POST/PATCH/DELETE /webhooks — gerçek zamanlı olay webhook'larını yönetin (Pro+).
• GET /usage ve GET /me — kotanızı ve anahtar bilgilerinizi kontrol edin; bunlar asla kota harcamaz (her plan).

5Spam kontrol uç noktası ayrıntılı olarak

POST /spam/check, API'nin kalbidir ve herhangi bir planda deneyebileceğiniz tek uç noktadır. Kontrol edilecek metni içeren bir JSON gövdesi gönderin; yanıt bir karar, sayısal bir puan, bir güven değeri ve kendi ürününüzde uygulayabileceğiniz önerilen bir eylem döndürür.

Tek bir metin en fazla 10.000 karakter olabilir. Pro ve üzerinde, daha zor durumlar için ayrı bir günlük AI kontrolü hakkından düşülen bir AI kontrolünü etkinleştirebilirsiniz. Yüksek hacim için toplu uç nokta tek çağrıda 20 metne kadar kontrol eder ve kotayı öğe başına sayar.

• Kendi ürününüzün ne yapacağına karar vermek için kararı ve puanı kullanın — bir form gönderimini engelleyin, bir potansiyel müşteriyi işaretleyin veya kendi botunuzda bir mesajı otomatik olarak kaldırın.
• Toplu uç nokta yalnızca kurallarla çalışır; AI düzeyi yalnızca tekli metin uç noktasında kullanılabilir.
• İstek gövdeleri sınırlıdır (tekli kontrol için yaklaşık 64 KB, toplu kontrol için 256 KB); fazla büyük gövdeler 413 döndürür.

6Planlar, oran limitleri ve günlük kotalar

Erişim iki şekilde ölçülür: dakika başına bir oran limiti (bir patlama tavanı) ve UTC gece yarısında sıfırlanan günlük bir çağrı kotası. İkisi de hesap başına sayılır ve tüm API anahtarlarınız arasında paylaşılır. Tekli spam kontrol uç noktasını herhangi bir planda deneyebilirsiniz, ancak kurallara, ayarlara, toplu kontrollere ve webhook'lara dokunan gerçek bir entegrasyon Pro veya üzerini gerektirir.

• Free — günde 100 çağrı, yalnızca spam kontrolü.
• Pro — günde 10.000 çağrı, tam API ve webhook'lar, ayrıca günde 1.000 AI kontrolü.
• Business — günde 50.000 çağrı, tam API ve webhook'lar, ayrıca günde 10.000 AI kontrolü.
• Dakika başına oran limitleri de plana göre artar — Free'de dakikada 60 istek, Pro'da 600, Business'ta 1.800.
• GET /usage ve GET /me asla kotanızdan düşülmez, böylece kalan bütçenizi istediğiniz zaman kontrol edebilirsiniz.

7Hata yönetimi ve durum kodları

API, gövdede makine tarafından okunabilir bir hata koduyla birlikte standart HTTP durum kodlarını kullanır. İstemcinizi körü körüne yeniden denemek yerine bu kodları okuyup geri çekilecek veya yükseltme önerecek şekilde kurun.

Günlük kotanızı aştığınızda ölçülen bir çağrı; daily_quota_exceeded kodu, bir Retry-After başlığı ve planınızı, limitinizi, kullanılan sayıyı, sıfırlama zamanını ve bir yükseltme ipucunu listeleyen bir gövdeyle 429 döndürür. Daha yüksek bir plan gerektiren uç noktalar, gereken planı belirterek 403 plan_required döndürür.

• 401 — eksik veya geçersiz API anahtarı.
• 403 plan_required — uç nokta Pro veya üzerini gerektirir.
• 403 insufficient_scope — anahtarın, veriyi değiştiren bir çağrı için yazma kapsamı yok.
• 429 daily_quota_exceeded veya rate_limit_exceeded — sıfırlama zamanını bekleyin veya planınızı yükseltin; Retry-After başlığına uyun.
• Limitin önünde kalmak için X-Quota-* yanıt başlıklarını okuyun.

8Sağlam bir entegrasyon için en iyi uygulamalar

Birkaç alışkanlık, bir entegrasyonu büyüdükçe güvenilir ve güvenli tutar.

• Anahtarları istemci tarafı kodda veya bir git deposunda değil, bir gizli bilgi yöneticisinde saklayın; diğerlerini bozmadan birini iptal edebilmek için her hizmete ayrı bir anahtar verin.
• X-Quota-Used ve X-Quota-Limit başlıklarını izleyin (veya GET /usage uç noktasını düzenli olarak sorgulayın) ve duvara çarptıktan sonra değil, çarpmadan önce yavaşlayın.
• 429 aldığınızda Retry-After'a uyun ve geri çekilin; 403 plan_required aldığınızda yeniden denemek yerine bir yükseltme önerisi gösterin.
• Gerçek zamanlı tepkiler için yoklama yerine webhook'ları tercih edin — olayları Telm size iletsin.
• Anahtarları düzenli olarak döndürün; birinin sızmış olabileceğinden şüpheleniyorsanız hemen döndürün.

9Yaygın entegrasyon senaryoları

API, Telegram mesajlarını denetlemekten çok daha fazlası için kullanılır.

• Web sitesi ve uygulama kaydı: bir kaydı veya yorumu kabul etmeden önce gönderilen metni ya da kullanıcı adlarını POST /spam/check uç noktasından geçirin.
• Kendi Telegram botlarınız: işleyicinizden kontrol uç noktasını çağırarak Telm'in zekâsını Telm'in yönetmediği bir botta yeniden kullanın.
• Toplu yapılandırma: ayarlar ve kurallar uç noktalarıyla aynı kuralları, beyaz listeleri ve ayarları bir betikle onlarca gruba uygulayın.
• Veri ve uyarılar: moderasyon olaylarını gerçek zamanlı olarak bir veri ambarına, bir panoya veya bir uyarı kanalına akıtmak için webhook kaydedin.