Merge pull request SciSharp#1366 from hchen2020/master

Add Microsoft Teams channel

Author: iceljc

BotSharp.sln

@@ -101,6 +101,8 @@
     <PackageVersion Include="Shouldly" Version="4.3.0" />
     <PackageVersion Include="ModelContextProtocol" Version="1.2.0" />
     <PackageVersion Include="ModelContextProtocol.AspNetCore" Version="1.2.0" />
+	<PackageVersion Include="Microsoft.Bot.Builder.Integration.AspNet.Core" Version="4.22.7" />
+    <PackageVersion Include="AdaptiveCards" Version="3.1.0" />
   </ItemGroup>
   <ItemGroup>
     <PackageVersion Include="BotSharp.Core" Version="$(BotSharpVersion)" />

Directory.Packages.props

@@ -7,6 +7,7 @@ public static class ConversationChannel
     public const string Phone = "phone";
     public const string SMS = "sms";
     public const string Messenger = "messenger";
+    public const string Teams = "teams";
     public const string Email = "email";
     public const string Crontab = "crontab";
     public const string Database = "database";

src/Infrastructure/BotSharp.Abstraction/Conversations/Enums/ConversationChannel.cs

@@ -0,0 +1,22 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>$(TargetFramework)</TargetFramework>
+    <LangVersion>$(LangVersion)</LangVersion>
+    <VersionPrefix>$(BotSharpVersion)</VersionPrefix>
+    <GeneratePackageOnBuild>$(GeneratePackageOnBuild)</GeneratePackageOnBuild>
+    <GenerateDocumentationFile>$(GenerateDocumentationFile)</GenerateDocumentationFile>
+    <Nullable>enable</Nullable>
+    <OutputPath>$(SolutionDir)packages</OutputPath>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\Infrastructure\BotSharp.Abstraction\BotSharp.Abstraction.csproj" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Bot.Builder.Integration.AspNet.Core" />
+    <PackageReference Include="AdaptiveCards" />
+  </ItemGroup>
+
+</Project>

src/Plugins/BotSharp.Plugin.MicrosoftTeams/BotSharp.Plugin.MicrosoftTeams.csproj

@@ -0,0 +1,78 @@
+using Microsoft.AspNetCore.Authorization;
+using Microsoft.AspNetCore.Mvc;
+using Microsoft.Bot.Builder;
+using Microsoft.Bot.Builder.Integration.AspNet.Core;
+
+namespace BotSharp.Plugin.MicrosoftTeams.Controllers;
+
+[ApiController]
+public class TeamsMessageController : ControllerBase
+{
+    private readonly IBotFrameworkHttpAdapter _adapter;
+    private readonly IBot _bot;
+    private readonly TeamsRequestState _requestState;
+    private readonly ITeamsNotificationService _notification;
+    private readonly MicrosoftTeamsSetting _setting;
+
+    public TeamsMessageController(
+        IBotFrameworkHttpAdapter adapter,
+        IBot bot,
+        TeamsRequestState requestState,
+        ITeamsNotificationService notification,
+        MicrosoftTeamsSetting setting)
+    {
+        _adapter = adapter;
+        _bot = bot;
+        _requestState = requestState;
+        _notification = notification;
+        _setting = setting;
+    }
+
+    /// <summary>
+    /// Inbound endpoint registered as the Azure Bot "messaging endpoint".
+    /// Authentication is performed by the Bot Framework JWT pipeline inside the adapter,
+    /// so the action itself is anonymous.
+    /// https://learn.microsoft.com/azure/bot-service/bot-builder-basics
+    /// </summary>
+    [AllowAnonymous]
+    [HttpPost("/teams/messages/{agentId}")]
+    public async Task PostAsync([FromRoute] string agentId)
+    {
+        _requestState.AgentId = agentId;
+        await _adapter.ProcessAsync(Request, Response, _bot);
+    }
+
+    /// <summary>
+    /// Outbound (proactive) push. Requires the platform's standard authorization.
+    /// </summary>
+    [Authorize]
+    [HttpPost("/teams/notify")]
+    public async Task<IActionResult> NotifyAsync([FromBody] TeamsNotifyRequest request, CancellationToken cancellationToken)
+    {
+        if (string.IsNullOrEmpty(request.UserId))
+        {
+            return BadRequest("userId is required.");
+        }
+
+        bool delivered;
+        if (!string.IsNullOrEmpty(request.Prompt))
+        {
+            var agentId = request.AgentId ?? _setting.AgentId;
+            if (string.IsNullOrEmpty(agentId))
+            {
+                return BadRequest("agentId is required when prompt is set (or configure MicrosoftTeams:AgentId).");
+            }
+            delivered = await _notification.NotifyAsync(request.UserId, agentId, request.Prompt, cancellationToken);
+        }
+        else if (!string.IsNullOrEmpty(request.Text))
+        {
+            delivered = await _notification.SendTextAsync(request.UserId, request.Text, cancellationToken);
+        }
+        else
+        {
+            return BadRequest("Either text or prompt must be provided.");
+        }
+
+        return delivered ? Ok(new { success = true }) : NotFound(new { success = false, reason = "No conversation reference for user." });
+    }
+}

src/Plugins/BotSharp.Plugin.MicrosoftTeams/Controllers/TeamsMessageController.cs

@@ -0,0 +1,53 @@
+using Microsoft.Bot.Builder;
+using Microsoft.Bot.Builder.Integration.AspNet.Core;
+using Microsoft.Bot.Connector.Authentication;
+
+namespace BotSharp.Plugin.MicrosoftTeams;
+
+/// <summary>
+/// Two-way Microsoft Teams integration built on Azure Bot Service / Bot Framework.
+/// Inbound: Teams activities are routed into the BotSharp conversation engine.
+/// Outbound: proactive messages are pushed back via stored conversation references.
+/// https://learn.microsoft.com/microsoftteams/platform/bots/what-are-bots
+/// </summary>
+public class MicrosoftTeamsPlugin : IBotSharpPlugin
+{
+    public string Id => "b6f8e1a2-2c4d-4e6f-8a91-7d3c5b9e0f12";
+    public string Name => "Microsoft Teams";
+    public string Description => "Two-way conversational integration with Microsoft Teams via Azure Bot Service.";
+    public string IconUrl => "https://upload.wikimedia.org/wikipedia/commons/c/c9/Microsoft_Office_Teams_%282018%E2%80%93present%29.svg";
+
+    public void RegisterDI(IServiceCollection services, IConfiguration config)
+    {
+        var settings = new MicrosoftTeamsSetting();
+        config.Bind("MicrosoftTeams", settings);
+        services.AddSingleton(settings);
+
+        // Bot Framework authentication. ConfigurationBotFrameworkAuthentication expects the
+        // canonical Microsoft* keys, so map our section onto them.
+        var authConfig = new ConfigurationBuilder()
+            .AddInMemoryCollection(new Dictionary<string, string?>
+            {
+                ["MicrosoftAppType"] = settings.AppType,
+                ["MicrosoftAppId"] = settings.AppId,
+                ["MicrosoftAppPassword"] = settings.AppPassword,
+                ["MicrosoftAppTenantId"] = settings.TenantId
+            })
+            .Build();
+        services.AddSingleton<BotFrameworkAuthentication>(sp =>
+            new ConfigurationBotFrameworkAuthentication(authConfig));
+
+        // Adapter (shared by inbound ProcessAsync and proactive ContinueConversationAsync).
+        services.AddSingleton<TeamsAdapter>();
+        services.AddSingleton<IBotFrameworkHttpAdapter>(sp => sp.GetRequiredService<TeamsAdapter>());
+
+        services.AddSingleton<AdaptiveCardConverter>();
+        services.AddSingleton<IConversationReferenceStore, InMemoryConversationReferenceStore>();
+        services.AddSingleton<ITeamsNotificationService, TeamsNotificationService>();
+
+        // Per-request / per-turn services.
+        services.AddScoped<TeamsRequestState>();
+        services.AddScoped<TeamsMessageHandler>();
+        services.AddTransient<IBot, TeamsActivityBot>();
+    }
+}

src/Plugins/BotSharp.Plugin.MicrosoftTeams/MicrosoftTeamsPlugin.cs

@@ -0,0 +1,19 @@
+namespace BotSharp.Plugin.MicrosoftTeams.Models;
+
+public class TeamsNotifyRequest
+{
+    /// <summary>
+    /// Target user id (AAD object id) the bot has previously interacted with.
+    /// </summary>
+    public string UserId { get; set; } = string.Empty;
+
+    /// <summary>
+    /// When set, the agent generates the reply from <see cref="Prompt"/>.
+    /// Otherwise <see cref="Text"/> is sent verbatim.
+    /// </summary>
+    public string? AgentId { get; set; }
+
+    public string? Prompt { get; set; }
+
+    public string? Text { get; set; }
+}

src/Plugins/BotSharp.Plugin.MicrosoftTeams/Models/TeamsNotifyRequest.cs

@@ -0,0 +1,10 @@
+namespace BotSharp.Plugin.MicrosoftTeams.Models;
+
+/// <summary>
+/// Per-request scoped holder that carries the routed agentId from the controller
+/// into the <c>IBot</c> turn (both are resolved within the same HTTP request scope).
+/// </summary>
+public class TeamsRequestState
+{
+    public string AgentId { get; set; } = string.Empty;
+}

src/Plugins/BotSharp.Plugin.MicrosoftTeams/Models/TeamsRequestState.cs

@@ -0,0 +1,63 @@
+# BotSharp.Plugin.MicrosoftTeams
+
+Two-way Microsoft Teams integration for BotSharp, built on **Azure Bot Service / Bot Framework SDK**.
+
+- **Inbound** (user → bot): Teams activities arrive at the messaging endpoint and are routed into the BotSharp conversation engine.
+- **Outbound / proactive** (bot → user): the bot pushes unsolicited messages back to users it has previously talked to, via stored conversation references.
+
+## Endpoints
+
+| Method | Route | Auth | Purpose |
+|--------|-------|------|---------|
+| POST | `/teams/messages/{agentId}` | Bot Framework JWT | Azure Bot "messaging endpoint" (inbound) |
+| POST | `/teams/notify` | Platform `[Authorize]` | Proactive push (outbound) |
+
+`/teams/notify` body:
+
+```jsonc
+// send literal text
+{ "userId": "<aadObjectId>", "text": "Your ticket #123 was resolved." }
+
+// or let an agent generate the reply
+{ "userId": "<aadObjectId>", "agentId": "<agentId>", "prompt": "Summarize ticket #123 status" }
+```
+
+## Configuration
+
+`appsettings.json`:
+
+```jsonc
+"MicrosoftTeams": {
+  "AppType": "MultiTenant",   // MultiTenant | SingleTenant | UserAssignedMSI
+  "AppId": "",                // Azure Bot app (client) id
+  "AppPassword": "",          // client secret — use env var / Key Vault, never commit
+  "TenantId": "",             // required for SingleTenant / UserAssignedMSI
+  "AgentId": ""               // default agent for /teams/notify when prompt is used
+}
+```
+
+> **Security:** `AppPassword` is a client secret — keep it out of source control (User Secrets / Key Vault / env var). For production prefer `UserAssignedMSI` (managed identity, no secret). The inbound action is `[AllowAnonymous]` only because request legitimacy is enforced by the Bot Framework JWT pipeline inside the adapter — that layer must stay enabled.
+
+## Setup
+
+1. **Azure Bot resource** — Azure Portal → create an *Azure Bot* → note the App ID and create a client secret. Under *Channels*, add **Microsoft Teams**. Set *Messaging endpoint* to `https://<host>/teams/messages/{agentId}` (substitute a real agent id).
+2. **Teams app package** — author `manifest.json` (see `manifest/` below), zip it with `color.png` (192×192) and `outline.png` (32×32), and side-load via the Teams *Developer Portal* or *Apps → Manage your apps → Upload a custom app*.
+3. **Register the plugin** — already added to `WebStarter/appsettings.json` `PluginLoader.Assemblies`. Fill in the `MicrosoftTeams` settings.
+4. **Test** — use the *Bot Framework Emulator* for local turn logic, then `devtunnel`/`ngrok` to expose the endpoint for real Teams side-loading.
+
+## Rich content mapping
+
+`AdaptiveCardConverter` maps BotSharp rich messages to Teams:
+
+| BotSharp | Teams |
+|----------|-------|
+| `TextMessage` / plain content | text activity |
+| `QuickReplyMessage` | Adaptive Card with `Action.Submit` buttons (payload preserved) |
+| `ButtonTemplateMessage` | Adaptive Card: `web_url` → `Action.OpenUrl`, else `Action.Submit` |
+
+Submit payloads come back in `Activity.Value.payload`, which the bot unwraps into the next user turn.
+
+## Notes
+
+- The conversation-reference store defaults to in-memory (single node). For multi-instance deployments, implement `IConversationReferenceStore` against a durable store (Mongo/Redis/BotSharp storage) and register it in place of `InMemoryConversationReferenceStore`.
+- The Bot Framework SDK is in long-term maintenance; the successor is the **Microsoft 365 Agents SDK**. The integration seam here (adapter + `IBot` + `ActivityHandler`) maps cleanly onto it if you migrate later.

src/Plugins/BotSharp.Plugin.MicrosoftTeams/README.md

@@ -0,0 +1,74 @@
+using AdaptiveCards;
+using Microsoft.Bot.Builder;
+using Microsoft.Bot.Schema;
+
+namespace BotSharp.Plugin.MicrosoftTeams.Services;
+
+/// <summary>
+/// Maps a BotSharp <see cref="RoleDialogModel"/> reply to a Teams-renderable activity.
+/// Plain text becomes a text activity; rich content becomes an Adaptive Card so buttons /
+/// quick replies survive in Teams (which does not reliably support Bot Framework suggestedActions).
+/// </summary>
+public class AdaptiveCardConverter
+{
+    private static readonly AdaptiveSchemaVersion Schema = new(1, 4);
+
+    public IActivity Convert(RoleDialogModel message)
+    {
+        var rich = message.RichContent?.Message;
+
+        switch (rich)
+        {
+            case QuickReplyMessage quickReply:
+                return BuildCard(quickReply.Text, quickReply.QuickReplies.Select(q =>
+                    (AdaptiveAction)new AdaptiveSubmitAction
+                    {
+                        Title = q.Title,
+                        Data = new { payload = q.Payload ?? q.Title }
+                    }));
+
+            case ButtonTemplateMessage buttonTemplate:
+                return BuildCard(buttonTemplate.Text, buttonTemplate.Buttons.Select(ToAction));
+
+            case TextMessage textMessage:
+                return MessageFactory.Text(textMessage.Text);
+
+            case not null when !string.IsNullOrEmpty(rich.Text):
+                return MessageFactory.Text(rich.Text);
+
+            default:
+                return MessageFactory.Text(message.Content ?? string.Empty);
+        }
+    }
+
+    private static AdaptiveAction ToAction(ElementButton button)
+    {
+        if (string.Equals(button.Type, "web_url", StringComparison.OrdinalIgnoreCase)
+            && !string.IsNullOrEmpty(button.Url))
+        {
+            return new AdaptiveOpenUrlAction { Title = button.Title, Url = new Uri(button.Url) };
+        }
+
+        return new AdaptiveSubmitAction
+        {
+            Title = button.Title,
+            Data = new { payload = button.Payload ?? button.Title }
+        };
+    }
+
+    private static IActivity BuildCard(string text, IEnumerable<AdaptiveAction> actions)
+    {
+        var card = new AdaptiveCard(Schema);
+        if (!string.IsNullOrEmpty(text))
+        {
+            card.Body.Add(new AdaptiveTextBlock { Text = text, Wrap = true });
+        }
+        card.Actions.AddRange(actions);
+
+        return MessageFactory.Attachment(new Microsoft.Bot.Schema.Attachment
+        {
+            ContentType = AdaptiveCard.ContentType,
+            Content = card
+        });
+    }
+}