Telegram Bot entegrasyonu

Multica, Telegram'ın resmi @BotFather'ıyla oluşturduğunuz bir Bot kullanır. Bir Bot bir Multica agent'ına eşlenir. Kendi Telegram kimliğine ihtiyaç duyan her agent için ayrı bir Bot oluşturun.

Telegram desteği topluluk tarafından sürdürülür: her sürümde gönderilir, ama resmi bir destek SLA'sı taşımaz. Sorunları GitHub issues'da bildirin.

Başlamadan önce

• Bot'u bir Multica çalışma alanı sahibi veya yöneticisi bağlamalıdır.
• API sunucusu https://api.telegram.org'a erişebilmelidir.
• @BotFather tarafından verilen Bot token'ına ihtiyacınız var. Onu bir parola gibi ele alın.

1. Bot'u oluşturun

1. @BotFather'ı açın ve /newbot gönderin.
2. Bir görünen ad ve bot ile biten bir kullanıcı adı seçin.
3. HTTP API token'ını kopyalayın.
4. Varsayılan, en az görünürlüklü kurulum için Group Privacy'yi etkin bırakın: Telegram bu durumda gruplarda yalnızca komutları, açık @ bahsetmelerini ve Bot'a verilen yanıtları iletir. Kapatmak isteğe bağlıdır. Bu, Bot'un çevredeki grup konuşmasını bağlam olarak eklemesini sağlar; bedeli ise Bot'un gruptaki her mesajı almasıdır — bkz. Gruplar ve forum konuları.

2. Bir agent'a bağlayın

1. Multica'da Agent'lar'ı açın, bir agent seçin ve Entegrasyonlar'ı açın.
2. Telegram'a Bağlan'a tıklayın.
3. Bot token'ını yapıştırın ve Bağlan'a tıklayın.

Multica, Bot'u doğrulamak için Telegram'ı çağırır, giden bir webhook'un long polling ile çakışmadığını kontrol eder, token'ı şifreler ve denetimli bir getUpdates bağlantısı başlatır. Başka bir agent'a veya çalışma alanına zaten bağlı bir Bot'un önce oradan bağlantısının kesilmesi gerekir.

İlk kullanım ve hesap bağlama

Bir üye Bot'a ilk kez mesaj attığında, tek kullanımlık bir Multica hesap-bağlama bağlantısı gönderir. Onu açın, aynı Multica çalışma alanına giriş yapın, sonra Telegram'a dönüp mesajı yeniden gönderin. Bağlantının süresi 15 dakika sonra dolar; taze bir tane almak için Bot'a yeniden mesaj atın.

Bir grupta, Bot taşıyıcı bağlantıyı asla herkese açık paylaşmaz. Gönderenden önce özel bir sohbet başlatmasını ister.

Yalnızca mevcut çalışma alanı üyeleri Bot'u kullanabilir. Üyelik her mesajda yeniden kontrol edilir.

Bot'u kullanma

Özel sohbetler

Bot'u açın ve doğrudan metin gönderin. @ ile bahsetmeye gerek yoktur.

Gruplar ve forum konuları

Bot'u bir gruba ekleyin, sonra ya ondan @ ile bahsedin ya da doğrudan mesajlarından birine yanıt verin. Kabul edilen mesajlar devam eden Multica konuşmasında kalır. Bot'a hitap etmeyen bir grup mesajı kendi başına asla bir konuşma veya tur başlatmaz. Ancak kısa bir bellek içi tamponda tutulur: grup (veya forum konusu) başına Bot'un aldığı son 10 mesaj; sunucu her yeniden başladığında temizlenir. Ardından bir üye Bot'a hitap ettiğinde — @ ile bahsederek veya mesajlarından birine yanıt vererek — tampondaki bu mesajlar o turun başına salt okunur bağlam olarak eklenir ve tur ile birlikte konuşmanın parçası olarak kaydedilir. Tampondaki bir fotoğraf veya dosya orada yalnızca [Image] gibi bir işaret ve ardından başlığıyla görünür; dosyanın kendisi indirilmez. /new bu bağlam olmadan yeni bir sohbet başlatır. Tampona neyin ulaştığı Telegram'ın ne ilettiğine bağlıdır: Group Privacy etkinken bu yalnızca komutlar, açık @ bahsetmeleri ve Bot'a verilen yanıtlardır, dolayısıyla bağlam yalnızca daha önce hitap edilmiş mesajları içerir. Sıradan grup sohbetini de dahil etmek için @BotFather'da Group Privacy'yi kapatın, ardından Bot'u gruptan çıkarıp yeniden ekleyin; Bot o andan itibaren her grup mesajını alır. Grup yöneticisi olan bir Bot, gizlilik ayarından bağımsız olarak her mesajı alır; bu yüzden @BotFather'da hiçbir değişiklik yapmadan bağlamı sıradan sohbeti de içerir. Başka birinin mesajına yanıt verirken, Bot'tan açıkça @ ile bahsedin: yalnızca o zaman alıntılanan gönderen ve metin (veya başlık) talimatınızla birlikte dahil edilir. Bot'a hitap eden bir yanıt, fotoğraf veya dosya taşıyan bir mesajı alıntılıyorsa, kimin gönderdiğinden bağımsız olarak o dosya da eklenir. Bot'tan bahsetmeden bir insan mesajına yanıt vermek onu tetiklemez. Her sıradan grubun kendi devam eden Multica sohbeti vardır; forum konuları ayrı sohbetlere izole edilir.

Komutlar

• /new yeni, boş bir Multica Sohbeti oluşturur ve Telegram konuşmasındaki sonraki mesajları ona yönlendirir. /new <mesaj> Sohbeti o mesajı ilk tur olarak kullanarak oluşturur. Başka birinin mesajına açıkça bahsedilen bir yanıtta, seçilen alıntı o ilk tura bağlı kalır.
• /clear mevcut Multica Sohbetini korur ve sonraki boş olmayan mesaja taze, agent'a görünür bir bağlam uygular. /clear <mesaj> bağlam sınırından sonraki ilk tur olarak o mesajı kullanır; açıkça seçilmiş bir yanıt alıntısı bağlı kalır.
• /issue <başlık> bir Multica işi oluşturur; sonraki satırlar isteğe bağlı açıklaması olarak kullanılır. Başlıksız /issue kullanım rehberliği döndürür.
• /issue@your_bot gibi Telegram komut sonekleri gruplarda desteklenir.

Yanıtlar ve desteklenen içerik

Bot, bir Telegram mesajı gönderip düzenleyerek metni akıtır, tetikleyen mesajı alıntılar, forum konularını korur ve uzun yanıtları Telegram'ın mesaj sınırının altında böler. Nihai yanıtlar, işlem içi bir kuyruk tarafından asenkron olarak teslim edilir. Normalde, bir sohbetin backoff'u bir işçiyi işgal etmez; önbellek baskısı tam backoff durumunu sıkıştırırsa, aynı Bot kurulumu altındaki diğer sohbetler tedbirli biçimde gecikebilir. Terminal kuyruğunun sabit bir kapasitesi vardır: taşma reddedilir ve günlüğe yazılır, kuyruğa alınmış yanıtlar bir servis yeniden başlatmasından sonra kurtarılmaz.

Fotoğraf, dosya, video, sesli mesaj ve ses mesajları, başlık mesaj metni olarak, aynı konuşmada agent'a ek olarak ulaşır. Bunlardan birini taşıyan bir mesaja yanıt vermek — özel sohbette ya da Bot'a hitap ederken bir grupta, kimin gönderdiğinden bağımsız olarak — o mesajı talimatınızın önüne alıntılar ve dosyasını ekler; böylece agent'ı daha önceki bir fotoğrafa veya videoya yönlendirebilirsiniz. Telegram bir Bot'un 20 MB'a kadar dosya indirmesine izin verir; bir dosya alınamadığında (çok büyük olduğunda veya indirme başarısız olduğunda) Bot bunu size bildirir ve agent yalnızca bir yer tutucu görür. Agent'ın ürettiği dosyalar, yanıtından sonra ayrı mesajlar olarak sohbete geri gönderilir: 10 MB'a kadar fotoğraflar satır içinde görünür, 50 MB'a kadar diğer her şey dosya olarak gelir; bir dosyanın teslim edildiği doğrulanamazsa Bot bunu söyler ve dosya Multica'daki yanıta ekli kalır. Her iki yön de sunucuda nesne depolama gerektirir (aşağıdaki kendi sunucunuzda barındırma bölümüne bakın); o olmadan Bot medyaya desteklenmeyen-mesaj bildirimiyle yanıt verir ve agent'a dosya gönderemeyeceği söylenir. Çıkartmalar, konumlar, anketler ve dosya olmayan diğer mesajlar özel sohbetlerde ve gruplarda hitap edildiğinde aynı bildirimi alır; bu türlerden hitap edilmeyen grup mesajları sessiz kalır.

Bağlantıları yönetme

Bağlı Bot'ları görmek için Ayarlar → Mesajlaşma → Telegram'ı açın. Sahipler ve yöneticiler birinin bağlantısını kesebilir. Bağlantıyı kesmek long polling'i ve giden yanıtları durdurur ama Multica konuşmalarını ve denetim kayıtlarını korur.

Kendi sunucunuzda barındırma kurulumu

API sunucusunu başlatmadan önce sabit, 32 baytlık bir şifreleme anahtarı ayarlayın:

MULTICA_TELEGRAM_SECRET_KEY=<base64-encoded 32-byte key>

openssl rand -base64 32 ile bir tane üretin. Uzun ömürlü tutun: kaybetmek veya döndürmek mevcut Bot token'larını okunamaz kılar ve her Bot'un yeniden bağlanmasını gerektirir.

Bağlama bağlantıları MULTICA_APP_URL'i kullanır, ayarlanmamışsa FRONTEND_ORIGIN'e döner. Ortaya çıkan adres üyeler tarafından erişilebilir olmalıdır. Sunucunun ağı veya proxy'si api.telegram.org'a HTTPS erişimine izin vermelidir; Go standart HTTPS_PROXY ve NO_PROXY ortam değişkenlerine uyar.

Sorun giderme

• Bot doğrulanamıyor: önce sunucu bağlantısını ve proxy ayarlarını kontrol edin. Yeni bir token'ı yalnızca Telegram mevcut olanı reddettiğinde üretin.
• Webhook çakışması: Bot'u bağlamadan önce mevcut webhook'unu kaldırın. Telegram, bir webhook etkinken getUpdates'e izin vermez.
• 409 polling çakışması: başka bir Multica örneği veya süreci aynı Bot için zaten polling yapıyor. Diğer tüketiciyi durdurun veya ortam başına ayrı bir Bot kullanın.
• Grup yanıtı yok: Bot'un grupta olduğunu ve mesajın ondan @ ile bahsettiğini veya mesajına yanıt verdiğini doğrulayın.
• Bağlama bağlantısının süresi doldu: Bot'a başka bir özel mesaj gönderin ve en yeni bağlantıyı kullanın.
• Bot çalışmıyor: agent'ın arşivlenip arşivlenmediğini ve runtime'ının çevrimiçi olup olmadığını kontrol edin.

Sırada

• Sohbet entegrasyonları — platformları karşılaştırın, oturum ve kimlik işlemeyi anlayın.
• Sohbet — Bot mesajları agent çalıştırmalarına nasıl dönüşür.
• İşler — /issue'nun oluşturduğu iş.