Teams’e İş Uygulaması Eklemek: Sekme, Bot ve Mesaj Uzantısı

Kullanıcı gününü Teams’te geçiriyorsa izin talebi, satın alma onayı veya servis kaydı gibi iş uygulamalarını ayrı bir tarayıcı sekmesinde açtırmak, o uygulamanın kullanılmaması için yeterli sebeptir. Ama “Teams’e eklemek” tek bir işlem değil. Sekme, bot, mesaj uzantısı ve bildirim mekanizmaları farklı sorunları çözer, farklı geliştirme ve yönetim yükü getirir. Yanlış yüzey seçilince ya gereksiz bot altyapısı kurulur ya da kullanıcı onay için yine uygulamaya gitmek zorunda kalır. Aşağıda mevcut bir web uygulamasını veya Power App’i Teams’e entegre ederken hangi yüzeyi seçeceğinizi, sahada en sık patlayan noktaları ve dağıtımı nasıl yöneteceğinizi anlatıyoruz.

Teams’te uygulama yüzeyleri

Bir Teams uygulaması aslında bir uygulama paketidir: manifest.json dosyası ile iki simgeden (renkli ve dış hat) oluşan bir ZIP. Manifest uygulamanın hangi yüzeyleri kullandığını tanımlar; aynı paket birden fazla yüzeyi birlikte taşıyabilir, örneğin hem kişisel sekme hem bot.

• Kişisel sekme (static tab): Sol uygulama çubuğundan açılan, kullanıcıya özel web sayfası. “Taleplerim”, “Onay bekleyenler” gibi görünümler için.
• Kanal/grup sekmesi (configurable tab): Kanala, sohbete veya toplantıya eklenen, yapılandırma sayfasıyla bağlamı seçilen sekme. Ekibin ortak panosu veya proje görünümü için.
• Bot: Sohbet üzerinden mesaj alıp gönderen servis. Proaktif bildirim ve Adaptive Card ile yerinde işlem yaptırmak burada güçlüdür.
• Mesaj uzantısı (message extension): Mesaj yazma kutusundan veya bir mesajın menüsünden çağrılır. Arama tabanlı olanı uygulamadaki bir kaydı karta çevirip sohbete ekler; eylem tabanlı olanı bir mesajdan kayıt oluşturur. Bağlantı açma (link unfurling) da bu yüzeyin parçasıdır.
• Webhook ve iş akışı bildirimleri: Uygulama paketi olmadan kanala mesaj gönderme. Klasik Office 365 bağlayıcıları (gelen webhook dahil) için Microsoft kullanımdan kaldırma süreci duyurmuştur; yeni işlerde Teams’teki Workflows uygulamasıyla (Power Automate tabanlı) oluşturulan webhook’ları tercih edin ve güncel takvimi Microsoft dokümantasyonundan doğrulayın. Eski bağlayıcıya bağlı bildirimler bir gün sessizce durur.

Sekme, bot ve mesaj uzantısı karşılaştırması

Yüzey	En uygun senaryo	Geliştirme yükü	Dikkat noktası
Kişisel sekme	Mevcut web uygulamasını Teams’te açmak	Düşük	Çerçeve (iframe) izinleri, SSO
Kanal sekmesi	Ekip bağlamında ortak görünüm	Düşük–orta	Yapılandırma sayfası, bağlama göre veri
Bot	Bildirim + kart üzerinden onay	Orta–yüksek	Bot kaydı, mesajlaşma uç noktası, durum yönetimi
Mesaj uzantısı	Kaydı sohbete paylaşmak, mesajdan kayıt açmak	Orta	Bot altyapısı gerektirir
Workflows webhook	Kanala tek yönlü bildirim	Çok düşük	Geri dönüş etkileşimi sınırlı

Karar sırası basittir. Kullanıcı uygulamada iş mi yapacak, yoksa uygulama kullanıcıyı bir olaydan mı haberdar edecek? İlki sekme ister, ikincisi bildirim kanalı. Bildirim kullanıcıdan bir karar bekliyorsa (onayla/reddet), bot ve Adaptive Card birlikte en az tıklamalı deneyimi verir. Bir ekibe yalnız “yeni kayıt açıldı” demek yetiyorsa webhook yeter; bot kurmaya gerek yok. Mesaj uzantısı ise sohbet içinde kayıt numaralarının sürekli dolaştığı ekiplerde (destek, satış) gerçek iş görür. Diğer ekiplerde çoğu zaman kullanılmaz.

Mevcut web uygulamasını sekme olarak eklemek

Sekme, Teams istemcisinde bir iframe içinde yüklenen sıradan bir web sayfasıdır. Sahada en sık gelen şikâyet “sekme boş açılıyor”dur ve sebebi neredeyse hep aynıdır: uygulama çerçeve içinde açılmayı reddediyor. X-Frame-Options: DENY veya SAMEORIGIN başlığı gönderen uygulama Teams’te beyaz ekran verir. Bunun yerine Content-Security-Policy başlığında frame-ancestors yönergesiyle Teams ve Microsoft 365 istemci alan adlarına izin verilir. Alan adı listesini ezberden değil Teams geliştirici dokümantasyonundan alın; Microsoft 365 uygulamaları arasında genişliyor. Ters proxy veya WAF arkasındaki uygulamalarda başlığın uygulamadan değil ara katmandan geldiğini de kontrol edin.

İkinci adım, sayfanın Teams JavaScript istemci kitaplığını (@microsoft/teams-js) yükleyip app.initialize() çağırmasıdır. Ardından app.getContext() ile tema, dil, bulunulan ekip ve kanal gibi bağlam bilgileri alınır. Uygulama bu bağlamla, örneğin kanal sekmesinde yalnız o projenin kayıtlarını gösterebilir. Initialize çağrılmazsa bağlam gelmez.

Manifestte kişisel sekme tanımı aşağıdakine benzer. Değerler örnektir; kısalık için developer, description, icons, accentColor gibi zorunlu alanlar çıkarılmıştır. manifestVersion için kullandığınız araç zincirinin desteklediği güncel şema sürümünü seçin ve paketi Developer Portal’daki doğrulamadan geçirin.

{
  "manifestVersion": "1.17",
  "id": "00000000-0000-0000-0000-000000000000",
  "version": "1.0.0",
  "name": { "short": "Talep Merkezi", "full": "Talep Merkezi" },
  "staticTabs": [
    {
      "entityId": "taleplerim",
      "name": "Taleplerim",
      "contentUrl": "https://talep.ornek.com.tr/teams/taleplerim",
      "scopes": [ "personal" ]
    }
  ],
  "validDomains": [ "talep.ornek.com.tr" ],
  "webApplicationInfo": {
    "id": "<entra-uygulama-istemci-id>",
    "resource": "api://talep.ornek.com.tr/<entra-uygulama-istemci-id>"
  }
}

Power Apps tarafında bu adımların çoğu otomatiktir: Power Apps portalında uygulama menüsündeki Teams’e ekle seçeneği uygulamayı doğrudan ekler veya yöneticinin yüklemesi için paket olarak indirir. SharePoint sayfaları ve listeleri Teams’in yerleşik SharePoint sekmesiyle kod yazmadan eklenir. Özel geliştirmede Microsoft’un araçları (Teams Toolkit, yeni adıyla Microsoft 365 Agents Toolkit) ve Teams Developer Portal manifest düzenleme ile doğrulamayı kolaylaştırır.

Teams içinde SSO ve kimlik

Sekmede kullanıcıdan ikinci kez oturum açmasını istemek iframe içinde açılır pencere sorunları ve kullanıcı şikâyeti demektir. Teams sekme SSO’su bunu çözer: sekme authentication.getAuthToken() çağırır, Teams istemcisi kullanıcının Entra ID oturumuyla uygulamanız için bir erişim belirteci üretir. Kurulumu beş adımdır ve hataların çoğu ilk üçünde çıkar.

1. Entra ID’de uygulama kaydı oluşturun ve Application ID URI değerini api://<alan-adı>/<istemci-id> biçiminde tanımlayın.
2. Bir kapsam (genellikle access_as_user) yayımlayın.
3. Teams masaüstü/mobil ve Teams web istemcilerinin istemci kimliklerini bu kapsam için önceden yetkilendirilmiş istemci olarak ekleyin; kimlik değerlerini Microsoft dokümantasyonundan kopyalayın, elle yazmayın.
4. Manifestteki webApplicationInfo alanına aynı istemci kimliğini ve URI’yi yazın. Tek karakter farkı SSO’yu bozar.
5. Sunucu tarafında belirteci doğrulayın. Microsoft Graph’a kullanıcı adına erişmeniz gerekiyorsa bu belirteci on-behalf-of akışıyla Graph belirtecine çevirin; istemcide gelen belirteci doğrudan Graph’a göndermeyin.

Graph izinlerini gereken en dar kapsamda tutmak onay sürecini de kısaltır; bu tasarımı Microsoft Graph API izinleri rehberinde ayrıntılandırdık. Uygulama Teams dışında da açılacaksa aynı uygulama kaydının OIDC ile nasıl kullanılacağı için Entra ID ile OIDC oturum açma yazısına bakın.

Uygulama yükleme, onay ve dağıtım ilkeleri

Kurum içi uygulamalar Teams’te “özel uygulama” (custom app) olarak yayımlanır ve Teams yönetim merkezinden yönetilir. Paketi hazırlamak işin yarısıdır; kimin göreceğini ilkeler belirler.

• Yükleme: Paket, Teams yönetim merkezinde Teams uygulamaları > Uygulamaları yönet altından kuruluş kataloğuna yüklenir. Geliştiricinin Teams istemcisinden gönderdiği paket ise yönetici onayı bekleyen bir yayın talebi oluşturur.
• Erişim: Uygulamayı kimin kullanabileceğini uygulama izin ilkeleri veya kiracınızda etkinse uygulama merkezli yönetim ayarları belirler. Pilot grupla başlayın; sorunu sınırlı kitlede yakalarsınız.
• Sabitleme: Uygulama kurulum ilkeleri (setup policies) uygulamayı belirli kullanıcıların uygulama çubuğuna sabitler ve önceden yükler. Bot kullanan uygulamada önceden yükleme ayrıca gereklidir; kullanıcı uygulamayı hiç açmadıysa proaktif bildirim gitmez.
• Özel uygulama yükleme yetkisi: Geliştiricinin test için paket yükleyebilmesi kurulum ilkesindeki özel uygulama yükleme ayarına bağlıdır. Bu yetkiyi tüm kullanıcılara değil, geliştirici grubuna verin.
• Sürüm güncelleme: Manifestteki version değeri artırılmadan yüklenen paket güncelleme olarak algılanmaz. Kapsam veya izin değişikliği içeren güncelleme kullanıcıdan yeniden onay isteyebilir.

Bildirim senaryoları ve sınırlamalar

İş uygulamasının Teams’teki değerinin büyük kısmı bildirimden gelir. Üç ana yol var, her biri başka bir ihtiyaca cevap verir:

Yöntem	Hedef	Gereksinim
Workflows webhook	Kanal veya sohbet	Power Automate akışı, webhook URL’si
Bot proaktif mesajı	Kişi, sohbet, kanal	Bot kaydı, uygulamanın hedefte yüklü olması
Etkinlik akışı bildirimi	Kullanıcının Teams etkinlik akışı	Graph sendActivityNotification, uygulamanın kullanıcıda yüklü olması

Webhook URL’si bir sırdır: URL’yi bilen herkes kanala mesaj gönderebilir. Kaynak kodda veya yapılandırma dosyasında açık metin tutmayın, bir gizli anahtar kasasında saklayın. Bot ile gönderilen Adaptive Card’da kullanıcı “Onayla” dediğinde işlem bot servisinizde gerçekleşir. Kartın eylemini yapan kişinin yetkisini sunucuda yeniden kontrol edin; kartı alan herkesin onaylayabileceğini varsaymayın. Kart iletilebilir.

Bilinen sınırlamaları tasarıma baştan koyun:

• Teams mobil istemcisinde sekme alanı dardır; sekme sayfasının mobil görünümünü ayrıca test edin.
• İframe içindeki uygulama dosya indirme, yeni pencere açma ve kimlik doğrulama açılır pencereleri için Teams JS SDK’nın sunduğu yöntemleri kullanmalıdır; tarayıcıdaki gibi davranmaz.
• Misafir ve dış kullanıcılar uygulamayı ancak kendi kiracı ilkeleri ve sizin uygulama ilkeleriniz izin verirse görür.
• Bot ve webhook mesajlarına Microsoft’un hız sınırları uygulanır; toplu bildirimde kuyruk ve yeniden deneme mantığı şarttır.

Uygulanmış bir model görmek isterseniz, talep yönetiminin Teams ile birleştirildiği Microsoft 365 ile helpdesk kurulumu yazısına bakın. Kurum içi uygulamaların Teams’e taşınması ve bildirim mimarisi için Teams ve kurumsal entegrasyonlar hizmetimizi inceleyebilirsiniz. Manifest şeması ve yüzeylerin güncel yetenekleri için başvuru kaynağı Microsoft Teams geliştirici dokümantasyonudur.

Sık sorulan sorular

Power App’i Teams’e eklemek için geliştirme gerekir mi?

Genellikle gerekmez. Power Apps portalındaki Teams’e ekle seçeneği uygulamayı kişisel uygulama olarak ekler veya yöneticinin kuruluş kataloğuna yüklemesi için paket üretir. Özel bildirim, bot veya mesaj uzantısı istendiğinde ek geliştirme gerekir.

Sekmem Teams’te boş görünüyor, ilk neye bakmalıyım?

Önce uygulamanın X-Frame-Options başlığı gönderip göndermediğine ve Content-Security-Policy frame-ancestors yönergesinin Teams alan adlarına izin verip vermediğine bakın. Ardından sayfanın Teams JS kitaplığını yükleyip app.initialize() çağırdığını ve alan adının manifestteki validDomains listesinde olduğunu doğrulayın.

Bildirim için bot mu, webhook mu kullanmalıyım?

Tek yönlü kanal bildirimi yetiyorsa Workflows tabanlı webhook en hızlı çözümdür. Kişiye özel bildirim, kart üzerinden onay veya sohbet içinde etkileşim gerekiyorsa bot gerekir. Bot daha fazla altyapı ister ama kullanıcı işlemi Teams’ten çıkmadan tamamlar.

Teams sekmesinde SSO çalışmazsa kullanıcı ne görür?

getAuthToken çağrısı hata döndürür. Uygulama bu durumda kullanıcıyı Teams’in kimlik doğrulama penceresi yöntemiyle etkileşimli oturum açmaya yönlendirmelidir. En sık nedenler Application ID URI ile manifestteki resource değerinin uyuşmaması ve Teams istemcilerinin önceden yetkilendirilmemesidir.