Teams Hedefli Mesajlar: Ajanlar ve Botlar için Grup İçi Özel Mesajlaşma

Neden Önemli?

Microsoft Teams platformunda ajan ve bot geliştiren ekipler, uzun süredir kritik bir sorunla karşı karşıyaydı: grup sohbetlerinde veya kanallarda bir bota gönderilen yanıtlar, kimlik doğrulama istemleri veya kişisel bildirimler tüm katılımcılara görünüyordu. Bu durum, sohbet akışını kirletiyor ve kullanıcı deneyimini olumsuz etkiliyordu.

Microsoft, Teams platformu için en çok talep edilen özelliklerden biri olan Hedefli Mesajlar (Targeted Messages) özelliğini geliştirici ön izleme (developer preview) kapsamında kullanıma sundu. Bu özellik sayesinde ajanlar ve botlar, grup sohbetleri ve kanallarda yalnızca belirli bir kullanıcının görebildiği geçici, özel mesajlar gönderebilir.

Hedefli Mesajlar Nedir?

Hedefli mesajlar, bir ajanın veya botun grup sohbeti, kanal veya toplantı sohbetinde belirli bir kullanıcıya özel olarak gönderdiği geçici mesajlardır. Alıcı, bu mesajları normal satır içi sohbet mesajları gibi görür; ancak mesajın üzerinde "Bu mesajı yalnızca siz görebilirsiniz" (Only you can see this message) etiketi bulunur.

Temel Özellikler

Özellik	Açıklama
Görünürlük	Yalnızca hedeflenen kullanıcı görebilir
Otomatik temizleme	24 saat sonra istemcilerden otomatik olarak kaldırılır
Kullanıcı aksiyonları	Reaksiyon, yanıt ve iletme desteklenmez
Saklama	Organizasyon politikasına göre güvenli depolamada tutulabilir
İçerik desteği	Metin, butonlar, görseller, Adaptive Cards ve dosyalar
Gönderici	Yalnızca ajan veya bot gönderebilir; kullanıcılar gönderemez

Desteklenen İşlemler

Hedefli mesajlar üzerinde üç temel işlem gerçekleştirilebilir:

• Gönderme (Send): Belirli bir kullanıcıya hedefli mesaj gönderme
• Güncelleme (Update): Gönderilmiş bir hedefli mesajın içeriğini düzenleme
• Silme (Delete): 24 saat içinde gönderilmiş bir hedefli mesajı kaldırma

Kullanım Senaryoları

Hedefli mesajlar, bağlamsal bilgi veya kişisel yardım gerektiren çeşitli senaryolarda ideal bir çözüm sunar.

AI ve Copilot Özetleri

Uzun süren bir grup sohbetine yeni katılan bir kullanıcıya, ajanın o ana kadarki tartışma özetini hedefli mesaj olarak göndermesi mümkündür. Bu sayede mevcut tartışma akışı bozulmaz ve yeni katılımcı bağlamı hızlıca yakalar.

Destek Mesajları

Kullanıcıya özel destek mesajları, işe alım hatırlatmaları, kişisel kontrol mesajları ve hızlı bilgilendirmeler, grubu rahatsız etmeden hedefli mesaj olarak gönderilebilir. Herkese açık bir bildirim yapmak yerine, yalnızca ilgili kişiye ulaşılır.

Onay İş Akışları (Human-in-the-Loop)

Bir onay süreci içinde, ajanın belirli bir kullanıcıdan onay istemesi veya bilgilendirici bir mesaj göndermesi gerektiğinde hedefli mesajlar kullanılabilir. Kullanıcı, bağlam değiştirmeden veya başka bir yere yönlendirilmeden sohbet içinde iş akışını ilerletebilir.

Kimlik Doğrulama İstemleri

Botların grup sohbetlerinde kullanıcıdan kimlik doğrulama istemesi gereken senaryolarda, auth prompt'ları yalnızca ilgili kullanıcıya gösterilebilir. Bu sayede diğer katılımcılar gereksiz kimlik doğrulama mesajlarıyla karşılaşmaz ve sohbet akışı temiz kalır.

Kişiselleştirilmiş Öneriler

Bir toplantı sohbetinde veya proje kanalında, ajanın belirli bir kullanıcıya kişiselleştirilmiş bir öneri, içgörü veya takip mesajı göndermesi gerektiğinde hedefli mesajlar kullanılır. Diğer katılımcılarla ilgisi olmayan bilgiler paylaşılmaz.

Teknik Uygulama Rehberi

Hedefli mesajlar, Teams SDK (C#, TypeScript, Python) ve REST API aracılığıyla etkinleştirilebilir. Aşağıda her platform için uygulama detayları yer almaktadır.

Ön Koşullar

• Teams geliştirici ön izleme (developer preview) programına kayıt
• Teams SDK'nın güncel sürümü (C#, TypeScript veya Python)
• Botun ilgili sohbet veya kanala yüklenmiş olması
• Hedef kullanıcının ilgili sohbet veya kanalın üyesi olması

Mesaj Gönderme

Hedefli mesaj göndermek, normal mesaj göndermeye benzer. Ajan, mesajın belirli bir kullanıcıya yönelik olduğunu belirtir ve platform mesajı yalnızca o kullanıcıya iletir. Ajan ayrı bir sohbet başlatmaz veya yeni bir kanal oluşturmaz.

C# ile gönderim:

Mesajı WithRecipient metodu ve isTargeted: true parametresi ile hedefli olarak işaretleyin. context.Activity.From özelliği, mesajı tetikleyen kullanıcıyı hedef olarak belirler.

TypeScript ile gönderim: MessageActivity sınıfını kullanarak mesaj oluşturun ve withRecipient(activity.from, true) çağrısı ile hedefi belirleyin. Python ile gönderim: MessageActivityInput sınıfını kullanarak mesaj oluşturun ve with_recipient(ctx.activity.from_, is_targeted=True) metodu ile hedef kullanıcıyı belirleyin. REST API ile gönderim:

POST isteğinde isTargetedActivity=true sorgu parametresini ekleyin. İstek gövdesinde recipient alanında hedef kullanıcının Teams ID'sini (MRI) belirtin.

Endpoint: POST {cloud}/v3/conversations/{conversationId}/activities?isTargetedActivity=true

İstek gövdesinde type, from, conversation, recipient ve text alanlarını standart mesaj etkinliği formatında gönderin.

Mesaj Güncelleme

Ajan, gönderdiği hedefli mesajı gerektiğinde düzenleyebilir. Güncellenen mesaj yalnızca hedeflenen kullanıcının görünümünde değişir.

Güncelleme işlemi için önce orijinal mesajın activityId değerini saklamanız gerekir. Ardından SDK'daki UpdateTargeted (C#), updateTargeted (TypeScript) veya update_targeted (Python) metotlarını kullanarak mesajı güncelleyebilirsiniz.

REST API kullanımında: PUT {cloud}/v3/conversations/{conversationId}/activities/{activityId}?isTargetedActivity=true

Mesaj Silme

Ajanlar, 24 saat içinde gönderilmiş hedefli mesajları silebilir. Mesajlar zaten 24 saat sonra istemcilerden otomatik olarak temizlenir; ancak artık gerekli olmayan veya üzerinde aksiyon alınmış mesajları erken silmek, daha temiz bir deneyim sağlar.

SDK'daki DeleteTargeted (C#), deleteTargeted (TypeScript) veya delete_targeted (Python) metotlarını kullanın.

REST API kullanımında: DELETE {cloud}/v3/conversations/{conversationId}/activities/{activityId}?isTargetedActivity=true

Hata Yönetimi

Hedefli mesaj gönderimi sırasında karşılaşılabilecek hata kodları ve önerilen aksiyonlar:

Durum Kodu	Hata Kodu	Açıklama	Geliştirici Aksiyonu
400	Bad argument	Hedefli mesaj oluşturulurken alıcı bilgisi eksik	WithRecipient metodunun geçerli bir hesap nesnesi ile çağrıldığından emin olun
400	Bad argument	Güncelleme veya silme işleminde alıcı bilgisi gönderilmiş	Güncelleme ve silme işlemlerinde alıcı bilgisi göndermeyin
403	BotNotInConversationRoster	Bot, sohbetin üyesi değil	Hedefli mesaj göndermeden önce botun ilgili sohbete yüklendiğinden emin olun
404	ActivityNotFoundInConversation	Belirtilen mesaj ID'si bulunamadı; mesaj silinmiş veya 24 saat sonra otomatik kaldırılmış olabilir	İş mantığına göre yeni bir hedefli mesaj gönderin veya kullanıcı girdisini bekleyin

Hedefli mesaj gönderimi başarısız olursa, yedek mekanizma olarak kullanıcıya 1:1 sohbet mesajı göndermeyi değerlendirin.

Adaptive Cards ile Kullanim

Hedefli mesajlar, Adaptive Cards dahil tüm Teams mesaj içerik türlerini destekler. Bu sayede zengin, etkileşimli kartlar yalnızca belirli bir kullanıcıya gösterilebilir.

Dikkat Edilmesi Gerekenler

Hedefli mesajlarda Adaptive Cards kullanırken kritik bir nokta vardır: kart üzerindeki kullanıcı aksiyonları, istemeden herkese açık bir yanıt oluşturmamalıdır. Örneğin, bir onay kartındaki "Onayla" butonu tıklandığında, yanıt mesajının da hedefli olarak gönderildiğinden emin olun. Aksi takdirde, özel olarak gönderilen bir karttaki aksiyon sonucu herkesin görebileceği bir mesaj oluşabilir.

En İyi Uygulamalar

• Kart aksiyonlarının yanıtlarını da hedefli olarak yapılandırın
• Onay kartlarında, onay sonrası kartı güncelleyerek aksiyona geçilmiş durumu yansıtın
• Dosya paylaşımı içeren kartlarda, dosyanın erişim izinlerinin hedef kullanıcıyla uyumlu olduğundan emin olun

Sınırlamalar ve Dikkat Edilmesi Gerekenler

Hedefli mesajları kullanırken aşağıdaki sınırlamaları göz önünde bulundurun:

• Geliştirici ön izleme durumu: Bu özellik şu anda geliştirici ön izleme (developer preview) aşamasındadır ve üretim ortamları için henüz genel kullanıma açılmamıştır. API ve davranışlarda değişiklik olabilir.
• 24 saat otomatik temizleme: Hedefli mesajlar, istemcilerden 24 saat sonra otomatik olarak kaldırılır. Kalıcı bilgi gerektiren senaryolarda hedefli mesaj yerine standart mesaj kullanılmalıdır.
• Organizasyon politikasına göre saklama: Mesajlar istemcilerden kaldırılsa bile, organizasyonun uyumluluk ve saklama politikalarına göre güvenli depolamada tutulabilir.
• Geri uyumluluk: Teams'in geri uyumluluk mekanizması, hedefli mesajları desteklemeyen eski istemcilerde bu mesajların görüntülenmemesini sağlar.
• Yalnızca bot veya ajan gönderebilir: Kullanıcılar doğrudan hedefli mesaj gönderemez; bu işlev yalnızca ajan ve botlara ayrılmıştır.
• Kullanıcı sohbet veya kanalın üyesi olmalı: Hedef kullanıcının, mesajın gönderildiği sohbet veya kanalın üyesi olması gerekir.

Kurumsal Etki ve Gelecek

Hedefli mesajlar, Microsoft'un Teams platformundaki ajan ekosistemini güçlendiren önemli bir yapı taşıdır. Agent 365 kontrol düzlemi ve Copilot Studio ile birleştiğinde, kurumsal ajan deneyimini önemli ölçüde iyileştirir.

Agent 365 Ekosistemi ile Entegrasyon

Microsoft'un Agent 365 vizyonu, ajanların kurumsal iş süreçlerinde otonom olarak görev yürütmesini öngörüyor. Hedefli mesajlar, bu vizyonun kritik bir bileşenidir: ajanlar, grup ortamlarında bireysel kullanıcılara kişiselleştirilmiş bilgi ve talimatlar sunabilir, onay isteyebilir veya durum güncellemesi verebilir — tüm bunları sohbet akışını kirletmeden yapabilir.

Copilot Studio ile Kullanım

Copilot Studio ile oluşturulan ajanlar, hedefli mesajları kullanarak grup sohbetlerinde daha sofistike etkileşimler kurabilir. Bir IT destek ajanı, bir kanalda yardım isteyen kullanıcıya kişisel sorun giderme adımlarını hedefli mesaj olarak gönderebilirken, diğer kanal üyeleri bu detayları görmez.

Grup Sohbet Deneyiminin Geleceği

Hedefli mesajlar, Teams'teki ajan ve bot etkileşim modelini temelden değiştirme potansiyeline sahiptir. Grup sohbetlerinde net bir mesaj hiyerarşisi oluşturur: herkes için olan kalıcı içerikler ile yalnızca belirli kişiler için olan geçici, bağlamsal bilgiler ayrışır. Bu ayrışma, özellikle büyük ekiplerde ve çok katılımcılı kanallarda sohbet kalitesini ve kullanılabilirliğini önemli ölçüde artırır.