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. Group Privacy'yi etkin tutun. Multica gruplarda yalnızca komutlara, açık @ bahsetmelerine ve Bot'a verilen yanıtlara ihtiyaç duyar.

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; hitap edilmeyen grup sohbeti toplanmaz. 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'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.

Bu sürüm yalnızca metin kabul eder. Fotoğraflar, dosyalar, video, ses, çıkartmalar ve diğer metin dışı mesajlar özel sohbetlerde net, desteklenmeyen-mesaj yanıtı alır; hitap edilen grup medyası aynı yanıtı alır, hitap edilmeyen grup medyası ise sessiz kalır.

Bağlantıları yönetme

Bağlı Bot'ları görmek için Ayarlar → Entegrasyonlar → 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 kodlu 32 baytlık anahtar>

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ş.