1Yığınınızın Geri Kalanıyla Konuşan Moderasyon
Tamamen Telegram içinde yaşayan bir moderasyon botu faydalıdır, ama aynı zamanda bir adadır. Verdiği kararlar — kaldırdığı her mesaj, taradığı her kullanıcı, geri püskürttüğü her baskın — birisi bakmak için Telegram'ı açmadıkça bir sohbet penceresinde kilitli kalır. Tek bir topluluk için bu sorun değil. Moderasyonu daha büyük bir operasyonun parçası olarak yürüten bir ekip için ise, alanlarınızı kimin kötüye kullandığı hakkında en çok bilgiye sahip olan tek sistemin, çalıştırdığınız başka hiçbir şeyle konuşamayan tek sistem olması demektir.
Herkese açık REST API ve webhook'lar bu boşluğu kapatır. Telm'i kendi içinde kapalı bir bottan, hâlihazırda sahip olduğunuz araçlara bağlayabileceğiniz bir bileşene dönüştürür: izleme ve nöbet kurulumunuz, uyumluluk arşiviniz, kendi ürününüz, dahili panolarınız. Gruplarınızı koruyan aynı motor, diğer sistemlerinizin sorgulayabileceği, dinleyebileceği ve yönlendirebileceği bir şeye dönüşür.
Bu rehber, API'nin ve webhook'ların gerçekte neleri sunduğunu — uç noktaları, olayları, güvenlik modelini — ve ekiplerin bunlarla inşa ettiği somut şeyleri anlatır. Aşağıdaki her şey bugün mevcut olan gerçek bir yetenektir; beklenecek bir SDK yok ve burada anlatılan, ürünün yalnızca yapmayı planladığı hiçbir şey yok.
2REST API ve Anahtarlarınız
API `https://api.telm.com/api/public/v1` adresinde bulunur. Düz bir REST arayüzüdür — onu sıradan HTTPS istekleri ve JSON ile, herhangi bir dilden, özel bir istemci kütüphanesi gerekmeden çağırırsınız. Kodunuz bir HTTP isteği yapabiliyorsa Telm ile konuşabilir.
Kimlik doğrulama API anahtarıyla yapılır. Anahtarları panoda Ayarlar → API ve Webhook'lar altında oluşturursunuz ve her biri oluşturulurken tam olarak bir kez size gösterilir — o anda gizli anahtar deponuza kopyalayın, çünkü sonradan tekrar alınamaz. Anahtarlar `tk_live_` önekini taşır, böylece loglarda ve yapılandırmada kolayca tanınırlar. Her anahtar bir kapsam taşır — okuma ya da yazma — böylece yalnızca karar günlüğünü çekmesi gereken bir hizmet salt okunur bir anahtar tutabilirken, ayarları değiştiren otomasyon bir yazma anahtarı alır. Her sistem için bir anahtar oluşturun; sızmış veya emekliye ayrılmış bir anahtarı iptal etmek diğerlerini asla rahatsız etmez.
Kullanım, planınıza bağlı günlük bir istek kotasıyla yönetilir; böylece verim öngörülebilir olur ve kontrolden çıkan tek bir betik her şeyi tüketemez. En hafif kontrol — metinde spam taraması — bu kota içinde her planda kullanılabilir; karar günlüğünden ayar yönetimine ve webhook'lara kadar daha geniş yüzey ise Pro ve Business planlarının bir parçasıdır. Tam sayılar sonda verilmiştir.
3Metin ve Kullanıcıları İstek Üzerine Tarama
İki uç nokta, bir mesaj hiçbir zaman bir Telegram grubundan geçmeden, kendi kodunuzdan istek üzerine Telm'in kararını çalıştırmanızı sağlar.
`POST /spam/check`, bir metni tam olarak topluluklarınızı koruyan üretim motorundan geçirir — paylaşılan spam gönderici sinyalleri, örüntü kuralları, sınıflandırıcılar — ve bir hüküm döndürür. Her planda kullanılabilen tek çağrı budur; bu da onu kendi ürününüz için doğal bir spam filtresine dönüştürür: yorumları, kayıt biyografilerini, destek taleplerini veya pazar yeri ilanlarını, Telegram alanlarınızı koruyan aynı algılamayla tarayın. Daha zor, daha belirsiz durumlar için bir AI hükmü katmak üzere `include_ai` ekleyin (Pro ve Business'ta mevcut); bu planlarda, öğe başına bir kez çağırmak yerine tek bir istekte yirmiye kadar metni toplu işleyebilirsiniz.
`POST /users/check`, bir mesaj yerine bir kişiyi tarar. Çağrı, küresel CAS engelleme listesini ve Telm'in birçok toplulukta yaptığı moderasyondan oluşturduğu kendi veri kümesini birleştirir ve bir risk düzeyi döndürür (Pro ve Business'ta), böylece ne kadar sürtünme uygulayacağınıza karar verebilirsiniz — temiz bir hesabı doğrudan geçirin, riskli olanı inceleme için bekletin. Bunu kendi katılım akışınıza bağlamak, bilinen kötü niyetli bir kişiyi yalnızca bir Telegram grubuna katıldıktan sonra değil, web sitenizin veya uygulamanızın kapısında yakalamanızı sağlar.
Her iki çağrı da satır içi yanıt verir: metni ya da kullanıcıyı gönderirsiniz, değerlendirmeyi yanıtta geri alırsınız. Yoklanacak bir kuyruk ve beklenilecek bir geri çağırma yoktur — karar yanıtla birlikte gelir.
4Olduğu Anda Push Almak
Günlüğü yoklamak arşivleme için gayet iyidir, ama bir şeye olduğu anda *tepki vermek* istediğinizde, sormak yerine size push yapılmasını istersiniz. Webhook'lar (Pro ve Business'ta) tam olarak bunu yapar: bir uç nokta kaydedersiniz, Telm de ilgili bir olay tetiklendiği anda ona bir HTTP isteği gönderir. Olaylar önemli anları kapsar — içerik için `spam.detected` ve `message.suspicious`, üyelik için `user.banned`, `user.kicked`, `user.muted`, `user.joined` ve `user.left`.
En bariz kullanım, bir spam dalgasını bir uyarıya dönüştürmektir. `spam.detected`'i izleme veya nöbet sisteminize yönlendirin; ani bir artış, diğer olaylarınızın (incident) düştüğü aynı yerde, nöbetteki kişiye giden bir çağrıya dönüşsün — bir saldırının başladığını fark etmek için kimsenin Telegram'ı izlemesi gerekmez. Aynı akış gerçek zamanlı panoları besler, harici bir sistemi yasaklamalarla senkron tutar veya istediğiniz herhangi bir iş akışını tetikler.
Bu istekler dış dünyadan altyapınıza geldiği için her teslimat imzalanır. Her istek, `v1=hex(hmac_sha256(secret, "timestamp.body"))` biçiminde bir `X-Telm-Signature` başlığı taşır — zaman damgası ve ham gövde üzerinde, yalnızca sizin ve Telm'in paylaştığı bir gizli anahtarla anahtarlanmış bir HMAC-SHA256. Bu imzayı kendi tarafınızda yeniden hesaplamak, isteğin gerçekten Telm'den geldiğini ve yolda taklit edilmediğini veya kurcalanmadığını kanıtlar; zaman damgası eski tekrar oynatmaları reddetmenizi sağlar. Payload'a güvenmeden önce imzayı doğrulayın — birkaç satır koddur ve güvenli bir webhook alıcısındaki tek en önemli adımdır.
5Güvenebileceğiniz Teslimat
Bir push modeli, ancak uç noktanızın yavaş olduğu, yeniden başladığı veya kısa süre kapalı kaldığı anlarla başa çıkabiliyorsa güvenilirdir — ve Telm'inki başa çıkar. Teslimat en az bir kezdir: her olay kararlı bir `id` taşır ve Telm, uç noktanız onaylayana kadar denemeye devam eder. En az bir kez, aynı olayın haklı olarak iki kez gelebileceği anlamına geldiği için, o `id` üzerinden yinelenenleri ayıklayın — işlediklerinizi kaydedin ve tekrarları yok sayın — böylece bir teslimat kaç kez yeniden denenirse denensin, işleyişiniz doğru kalır.
Yeniden denemeler, zorlanan bir uç noktayı dövmek yerine genişleyen bir çizelgeyi izler: hemen, sonra bir dakika, beş dakika, otuz dakika, iki saat ve altı saat sonra — toplam altı deneme, toparlanan bir hizmete geri dönmesi için alan tanıyacak şekilde yayılmış. Bir uç nokta bozuk kalırsa — arka arkaya yirmi başarısızlık ve başarılı teslimat olmadan yetmiş iki saat — Telm ona göndermeyi otomatik olarak durdurur ve sizi Telegram'da bilgilendirir; böylece ölü bir URL, üst üste yığılan sessiz bir başarısızlık seli yerine, alıcınızı onarmanız için net bir uyarıya dönüşür.
Yeni bir entegrasyonu doğru kurmak için onu test etmek üzere gerçek olaylar kışkırtmanıza gerek yok. Bir test ping'i, istek üzerine uç noktanıza örnek bir teslimat göndermenizi ve imza kontrolünüzün ve handler'ınızın çalıştığını doğrulamanızı sağlar; bir teslimat geçmişi ise neyin gönderildiğini ve her denemenin nasıl sonuçlandığını gösterir — böylece hatalı davranan bir alıcıyı tahmin etmek yerine kayıttan ayıklayabilirsiniz.
6Her Kararın Sorgulanabilir Kaydı
Motorun karara bağladığı her şey kaydedilir ve `GET journal` bu kaydı kodunuza teslim eder. Her giriş bir karardır: hüküm, arkasındaki puan, hangi kuralların tetiklendiği ve ardından gelen eylem. İmleç sayfalamalı olduğu için tüm geçmişi güvenilir biçimde — sayfa sayfa, boşluk veya kopya olmadan — dolaşabilir ve kayıtlarınızı tuttuğunuz yere çekebilirsiniz.
Bu, günlüğü bir uyumluluk arşivinin belkemiği yapar. Bir üyenin neden kaldırıldığını göstermek zorunda olan ekipler — bir platform politikası, bir müşteri sözleşmesi veya bir düzenleyici için — günlüğü bir çizelgeye göre kendi uzun vadeli depolarına aktarır; böylece Telegram'da geri kaydırmaya bağlı olmayan, her yaptırım eyleminin bağımsız ve sorgulanabilir bir dökümüne kavuşurlar. Bu, panonun denetim günlüğünün insanlara sunduğu aynı kanıttır, sistemlerinize erişilebilir kılınmış hâlidir.
Bunun yanında bir analiz uç noktası günden güne seriler döndürür — zaman içindeki hacimler ve eğilimler — böylece moderasyon yükünü, bir ekrandan okumak yerine, takip ettiğiniz her şeyin yanında kendi iş zekâsı araçlarınızda grafiğe dökebilirsiniz. Hem günlük hem analiz Pro ve Business planlarının bir parçasıdır.
7Birçok Grubu Koddan Yönetmek
API yalnızca okuyup dinlemez — yazar da. Pro ve Business'ta bir grubun ayarlarını `PATCH` edebilir ve kuralları ile beyaz listesi üzerinde tam oluşturma/okuma/güncelleme/silme işlemlerini, tamamı programlı olarak çalıştırabilirsiniz. Panoda elle yapılandıracağınız her şeyi bir betikten yapılandırabilirsiniz.
Moderasyonu büyük ölçekte yürütmeyi pratik kılan da budur. Onlarca topluluğu yöneten bir ajans ya da büyük bir operatör, her birini tek tek açıp aynı değişiklikleri tıklamak istemez; politikayı bir kez tanımlayıp her yerde uygulamak ister. API ile yeni bir kural yayar, bir eşiği ayarlar veya tek bir otomatik geçişte tüm filodaki her beyaz listeye bir adres eklersiniz; standartlarınız geliştikçe grupları aynı hizada tutarsınız.
Ayrıca moderasyon politikasının kendi sürüm kontrolünüzde yaşamasına da olanak tanır. İstenen yapılandırmayı kod olarak tutun, API üzerinden uygulayın; gruplarınızın nasıl yönetildiğine dair her değişiklik, altyapınızın geri kalanı gibi gözden geçirilir ve sürümlenir — hangi ayarı hangi sohbette değiştirdiğinizi hatırlamaktan çok uzak.
8Her Plan Neleri İçerir
Ayrım basittir. Metinde spam kontrolü her planda kullanılabilir; böylece ücretsiz katman bile Telm'in algılamasını kendi ürününde bir filtre olarak kullanabilir. Tam yüzey — risk düzeyleriyle kullanıcı taraması, karar günlüğü ve analiz, ayar ve kural yönetimi ve webhook'lar — Pro ve Business planlarının bir parçasıdır.
Her plan, daha ağır entegrasyonlar daha ağır planlarda yer alacak şekilde boyutlandırılmış günlük bir istek kotası alır:
- **Free** — günde 100 API isteği, yalnızca spam kontrolü.
- **Basic** — günde 1.000 API isteği, yalnızca spam kontrolü.
- **Pro** — günde 10.000 API isteği, ayrıca tam API yüzeyi ve webhook'lar.
- **Business** — günde 50.000 API isteği, ayrıca tam API yüzeyi ve webhook'lar.
- Anahtarlarınızı Ayarlar → API ve Webhook'lar altında oluşturun, gizli anahtar deponuzda saklayın, her webhook'un imzasını doğrulayın; böylece gruplarınızı koruyan aynı motor kendi yığınınızın bir parçası olur.