Telegram kurulumunu nasıl sıfıra indirdik

Vyneron'un ilk yılı boyunca Telegram'ı bağlamak isteyen herkesin önünde beş adım vardı. Çoğu insan ikincisini geçemiyordu.

Sorun: kişisel bot kurulumu kayıtları kesip atıyordu

Eskiden işin Telegram tarafı şöyle çalışıyordu:

Telegram'ı aç. @BotFather'a yaz. Yeni bir bot oluştur. Çöp gibi görünen 46 karakterlik jetonu kopyala. Vyneron ayarlarını aç. Jetonu "Kendi Botunu Getir" alanına yapıştır. Webhook'un kaydolmasını bekle. Sonunda görev listene mesaj atabil.

Telegram isteyen her kayıt, bu beşinin tamamını yapmak zorundaydı. Çoğu, ikinci adımı hiç bitirmiyordu.

Bunun sebebi kaydolan insanların isteksiz olması değildi. Sebep, her adımın yalnızca bir geliştiricinin keyif alacağı türden bir iş olmasıydı: bot türetmek, ona isim koymak, daha önce alınmamış bir kullanıcı adı bulmak, iki uygulama arasında bir jeton kopyalayıp yapıştırmak, yapıştırmanın gerçekten kaydolduğuna güvenmek. Akşam yemeğini ayarladığı sohbetten yarın süt al yazmak isteyen biri için bu kurulum töreni, kazandırdığı değerle taban tabana orantısızdı.

Onlar da gidiyordu. Ve Vyneron'un en ayırt edici yanı olan Telegram yüzeyi, ürünün geri kalanında olmayan bir sürtünme duvarının ardında öylece duruyordu.

Bu yazı, o duvarı kaldırmanın hikâyesi. Yaptığımız şey bir paylaşımlı Telegram botu: her Vyneron hesabı aynı @VyneronAIBot ile konuşuyor, mesajın hangi çalışma alanına ait olduğunu bot kendisi çözüyor. Kişisel jeton yok. Kopyala-yapıştır yok. @BotFather ziyareti yok.

Özetle

Özetle: Vyneron, her hesabın kendi bot jetonunu kurduğu modeli, herhangi bir hesabın on saniyenin altında bağlayabileceği tek bir paylaşımlı @VyneronAIBot ile değiştirdi. Hesap eşleşmesi, web uygulamasında üretilen kısa ömürlü altı karakterlik bir kodu bot sohbetine yapıştırarak oluyor. Web uygulaması ana yüzey olmaya devam ediyor; Telegram, zaten sohbet uygulamasının içinde yaşayanlar için isteğe bağlı bir yan katman. Tüm geçiş yaklaşık 24 saatte tamamlandı: otuz üç commit, tek seferlik bir veritabanı taşıması ve halihazırda bağlı olan iki kullanıcıyı bozmayan keskin bir geçiş.

Paylaşımlı bota geçmek neden bir yıl aldı

Dürüst cevap: kişisel jetonları önce göndermek daha kolaydı.

Vyneron çıktığında "her hesap kendi botunu getirir" temiz bir izolasyon hikâyesiydi. Her çalışma alanının Telegram trafiği kendi webhook'undan akıyordu, bot jetonları şirket bazında şifreli saklanıyordu ve üzerinde düşünülmesi gereken paylaşımlı bir kimlik yoktu. Bir müşterinin botunda bir şey ters giderse, o onun botuydu. Hata ayıklama yerel kalıyordu ve yanlışlıkla çökertebileceğiniz küresel bir şey yoktu.

Bedeli yukarıdaki sürtünmeydi: Telegram isteyen her aday, değere ulaşmadan önce geliştirici-aracı diyarında beş adım içeride olmak zorundaydı. Başlangıçta buna katlandık, çünkü kullanıcı tabanı insanları kuruluma tek tek götürecek kadar küçüktü. Sürtünme gerçek huni verisinde görünmeye başlayınca (kaydolan, Telegram'ı hiç bağlamayan ve sessizce uzaklaşan hesaplar) hesap değişti.

Böylece paylaşımlı bot, "olsa iyi olur"dan "asıl darboğaz bu"ya terfi etti. İş, kişisel jetonların bize verdiği her izolasyon güvencesini korumak, ama kurulumu sohbetteki tek bir mesaja indirmekti.

Mimari, sade anlatımla

Paylaşımlı modelde tüm ürün için tek bir Telegram botu var: @VyneronAIBot. Telegram'ın webhook'u gelen her mesajı arka uçtaki tek bir uca yönlendiriyor; o uç da işe yarar bir şey yapmadan önce bir soruyu yanıtlamak zorunda:

Bu Telegram kullanıcısı hangi Vyneron hesabı?

Kullanıcı henüz bağlanmadıysa cevap "tanımadığımız biri" oluyor. Mesajı, onu kayıt sayfasına yönlendiren nazik ve kısıtlı bir yanıt alıyor, o kadar. Görev oluşturma yok, yapay zekâ çağrısı yok, hesap sızıntısı yok. (Kısıtlama şundan: paylaşımlı tek botun /start akışı aynı zamanda gürültü için güzel bir hedef, o yüzden eşleşmemiş gönderenler dakikada en fazla bir kibar yanıt alıyor.)

Kullanıcı bağlandıktan sonra cevap, küçük bir tablodaki bir satır: telegram_user_id → user_id. O andan itibaren arka uç, gelen mesajları eski kişisel-jeton akışıyla birebir aynı işliyor. Aynı yapay zekâ hattı, aynı görev oluşturma, panoya aynı geri bildirim. Paylaşımlı bot bir yönlendiriciden ibaret; çalışma alanı mantığı hiç değişmedi.

Basitleştirilmiş bir resim:

Telegram → @VyneronAIBot webhook → arka uç
                                     │
                                     ├─ telegram_user_id biliniyor mu?
                                     │      ├─ evet → hesabı yükle → hattı çalıştır
                                     │      └─ hayır → kısıtlanmış kayıt çağrısı
                                     │
                                     └─ hat, web uygulamasının veritabanına yazar
                                              │
                                              └─ web uygulaması bunu alır

En çok özen isteyen kısım, yönlendirmenin üçüncü adımıydı: yabancı birinden gelen yepyeni bir Telegram mesajını, kullanıcıdan hiç jeton yapıştırmasını istemeden doğrulanmış bir eşleşmeye çevirmek.

Hesap bağlama gerçekte nasıl çalışıyor

Giriş yapmış bir Vyneron kullanıcısı Ayarlar → Entegrasyonlar'ı açıp Telegram'ı Bağla'ya tıkladığında, arka uç kısa bir bağlama kodu basıyor:

kod         = "8X4-K2Q"       # 6 karakter, alfabe 0/O/1/I içermez
user_id     = 42
expires_at  = now + 10 dakika
consumed    = false

Web uygulaması kodu ve t.me/VyneronAIBot?start=8X4-K2Q gibi tek dokunuşluk bir derin bağlantı gösteriyor. Buradan kullanıcının önünde aynı kısalıkta iki yol var:

• Derin bağlantıya dokunun. Telegram açılır, bot sizi karşılar ve start yükü ilk güncellemeyle gelir.
• Kodu bota elle yazın. Aynı sonuç, sadece biraz daha yavaş.

Her iki halde de arka uç, içinde bir kod ile bir from.id alanı (Telegram tarafındaki sayısal kullanıcı kimliği) bulunan tek bir Telegram güncellemesiyle kalıyor. Oradan:

1. Kodu ara. Yoksa, süresi dolmuşsa ya da zaten kullanılmışsa, net bir hatayla yanıt ver.
2. Atomik biçimde kullanıldı olarak işaretle. Aynı kod, aynı kullanıcı iki paralel dokunuşta bile olsa, iki kez sahiplenilemez.
3. Eşleşen Vyneron hesabına telegram_user_id = from.id yaz.
4. Sohbette yanıtla: "✅ Çalışma alanınıza bağlandınız."

Tüm akış, kullanıcı açısından tek bir HTTP isteği, arka uçta üç veritabanı işlemi. Jeton yok. Kopyala-yapıştır yok. @BotFather yok. Ve hesaba yabancı birinin, önce web uygulamasında giriş yapıp kodu üreten düğmeye basmadan kendi Telegram kimliğini bağlayabileceği bir senaryo da yok.

Göründüğünden daha çok önem taşıyan birkaç ayrıntı:

• Kod kısa. Dost bir alfabeyle altı karakter, mobil klavyede elle yazmayı gerçekçi kılıyor. On karakter teknik olarak daha güvenli olurdu; geçiş sırasında ölçtüğümüz yazım hatası oranlarına karşı altı, doğru dengeydi.
• On dakikada sona eriyor. Dizüstünüzden telefonunuza yürüyecek kadar uzun, sızan bir ekran görüntüsünün kimse fark edene dek işe yaramayacağı kadar kısa.
• Kodlar tek kullanımlık ve yeni bir kod üretilince geçersiz oluyor. "Telegram'ı Bağla"ya ikinci kez tıklamak öncekini yakıyor, böylece geçerli olan hep en son denemeniz. Bu da "iki kez tıkladım, şimdi hangi kodun canlı olduğundan emin değilim" tuzağını ortadan kaldırıyor.

24 saatlik geçiş

Tüm taşıma kabaca tek bir takvim gününde, iki aşamada çıktı.

1. aşama, arka uç. Paylaşımlı botu, bağlama-kodu tablosunu, kısıtlı kayıt çağrısını ve yönlendirmeyi ayağa kaldıran yirmi üç commit. Ardından, ancak mutlu yoldan şüphe etmeye başlayınca görünür olan uç durumları kapatan dokuz inceleme-sonrası düzeltme: beklenmesi gerekirken beklenmeyen yaşam-döngüsü arka plan görevi, iki istek yarışınca iki kez kullanılabilen bağlama kodu, eşleşmemiş gönderenlerde sessizce düşen yardım komutu, ilk commit'in kaçırdığı zamanlama-güvenli karşılaştırma, fazla hevesli bir hız sınırı ve birkaç tane daha.

2. aşama, sekiz testlik kanarya. Ön kapıyı açmadan önce açık bir senaryo koşturduk: eşleşmemiş mesaj çağrıyı alıyor mu, bağlama kodu mutlu yolda çalışıyor mu, aynı kod tekrar kullanılamıyor mu, kod yeniden üretilince önceki geçersiz oluyor mu, yardım komutu bağlı ve bağsız kullanıcılarda doğru davranıyor mu, mesaj işlenemese bile webhook 200 dönüyor mu (Telegram, 200 dışı yanıtta sonsuza dek yeniden deniyor) ve merkezi bot /api/health'te hâlâ sağlıklı görünüyor mu. Ön yüz geçmeden önce her kontrolün geçmesi şarttı.

3. aşama, ön yüz. Ayarlardaki "Kendi Botunu Getir" arayüzü kayboldu. Yerine üç durumlu tek bir Telegram bölümü geldi: Bağlı değil (düğme), Kod görünür (geri sayım, kopyala, derin bağlantı) ve Bağlı (Bağlantıyı Kes düğmeli hesap kartı). Altı dilde yirmi bir yeni çeviri anahtarı.

Keskin geçiş işe yaradı, çünkü bu noktada kullanıcı tabanı minicikti (kurucu ve bir arkadaş) ve ikisi de aynı akşam yeni akıştan tekrar bağlandı. Daha büyük bir kullanıcı tabanında aynı taşıma bir özellik bayrağı ve bir tolerans penceresi isterdi. O karmaşıklıktan bilerek kaçındık, çünkü tüm kullanıcı tabanından daha fazla zamana mal olurdu.

Değişmeyen şey: web uygulaması merkezde kalıyor

Açıkça söylemekte fayda var: bunların hiçbiri Telegram'ı zorunlu kılmıyor.

Web uygulaması Vyneron'un ana yüzeyi ve öyle kalıyor. Görevler, rutinler, notlar, dosyalar ve yapay zekâ araması, Telegram hiç açılmadan tarayıcıda çalışıyor. Yarın kaydolup botu hiç bağlamasanız da ürünün tamamına sahip olursunuz. Kayıttan 24 saat sonra gönderdiğimiz etkinleştirme e-postası tam olarak bunu söylüyor: web uygulaması hazır, Telegram ise zaten sohbet uygulamasının içinde yaşayanlar için isteğe bağlı bir ek yüzey.

Paylaşımlı bot işi, Telegram'ı isteyen kullanıcılar için sürtünmeyi kaldırmakla ilgiliydi; istemeyenlere yüzeyi dayatmakla değil. Telegram'ı bir zorunluluk değil bir süper güç gibi sunmak, sürekli geri döndüğümüz çizgi. Vyneron kullanıcılarının çoğu hiçbir zaman bir Telegram hesabı bağlamayacak, ve ürün onlar için de eksiksiz hissettirmeli.

Sırada ne var

Paylaşımlı bot, kişisel-jeton modelinin kapalı tuttuğu birkaç kapı açıyor.

• Telegram Mini Uygulamaları. Tek bir bot kimliği, t.me/VyneronAIBot/app Web App adresi ekleyip kullanıcıların tüm PWA'yı tek dokunuşla Telegram'ın içinden açmasını mümkün kılıyor; ayrıca belirli görev ve notlara paylaşılabilir derin bağlantılar üretmeyi. Bu lansman sonrası bir iş, çünkü kullanıcı tabanıyla ölçekleniyor ve getirisini sonra kazanıyor.
• Satır içi mod. Herhangi bir Telegram sohbetinden @VyneronAIBot fatura ara, sonuçlar satır içinde. Bunun zemini de aynı paylaşımlı kimliğin ardında.
• Akıllı karşılama akışı. Tek botla, ilk /start yanıtını tüm kullanıcılarda bir kerede deneyebiliyoruz: metin değişiklikleri, komut önerileri, from.language_code'dan dil algılama.

Ama bunların hiçbirinden önce, en faydalı devam adımı en küçüğü: sürtünmeyi sıfırda tutmak. Kazanç "paylaşımlı bot çıkardık" değildi. Kazanç, artık birinin kayıttan çalışan bir Telegram görev girişine bir dakikanın altında, tek bir geliştirici töreni olmadan ulaşabilmesiydi; üstelik botu hiç açıp açmadığını umursamayan bir ana web yüzeyine de sahip kalarak.

Bu, indiğinde görünmez olan türden bir iş. Amaç da tam olarak buydu.

Vyneron, 250+ ülkede yerleşik tatil farkındalığı, BYOK fiyatlandırması ve fotoğraflarla dosyalar için OCR'ı olan, Telegram'la iç içe bir yapay zekâ verimlilik çalışma alanı. Web uygulaması ana yüzey; Telegram isteğe bağlı. Vyneron'u ücretsiz deneyin ya da ekosistem bağlamı için Telegram görev botları incelemesine göz atın.