feat(apps): add Socket Mode to TeamsBotApplication

[teddy arida-moody (teddyam)]

Wires the Socket Mode transport from #682, #683, and #685 into TeamsBotApplication, so a bot can receive activities over outbound WebSocket connections instead of an HTTP messaging endpoint. Brings .NET to parity with microsoft/teams.ts#716, microsoft/teams.ts#743, microsoft/teams.ts#875, and microsoft/teams.py#608.

Stacked on #685.

Usage

var builder = Host.CreateApplicationBuilder(args);
builder.Services.AddTeamsBotApplication(options => options.UseSocketMode());

var host = builder.Build();
var teams = host.UseTeamsBotApplication();
teams.OnMessage((context, ct) => context.ReplyAsync($"You said: {context.Activity.Text}", ct));
host.Run();

Socket Mode is experimental, so callers suppress ExperimentalTeamsSocketMode (for example, <NoWarn>$(NoWarn);ExperimentalTeamsSocketMode</NoWarn>).

Changes

Core

• New BotApplication.ProcessAsync(CoreActivity, ClaimsPrincipal?, string? correlationVector, CancellationToken) overload that runs the activity pipeline without an HttpContext. The HTTP path now delegates to it.

Apps

• Public SocketModeOptions (negotiate URL, geos, startup/readiness timeouts, reconnect delays, keep-alive, server timeout).
• TeamsBotApplicationOptions.UseSocketMode is the only transport switch, mirroring TS/Python's boolean | SocketModeOptions:
  • UseSocketMode() or UseSocketMode(true) enables it with defaults.
  • UseSocketMode(false) clears any earlier Socket Mode configuration, so the bot uses HTTP.
  • UseSocketMode(s => ...) enables it with custom settings.
• SocketModeOptions and UseSocketMode are marked [Experimental("ExperimentalTeamsSocketMode")], matching TS's @experimental and the repo's ExperimentalTeams<Feature> convention.
• UseTeamsBotApplication() is the same call for both transports and reads the choice from UseSocketMode. Socket Mode runs on a generic host with no web server:
  • New UseTeamsBotApplication(this IHost) overloads for a generic host.
  • New UseTeamsBotApplication(this WebApplication, string routePath) overloads with the same parameters as the existing IEndpointRouteBuilder overloads. They exist only because WebApplication is both an IHost and an IEndpointRouteBuilder, which would otherwise make existing HTTP calls ambiguous.
  • Socket Mode on a WebApplication throws, and a host that includes a web server fails to start. HTTP on a generic host throws.
• A hosted service starts every geo (amer, emea, apac by default) and blocks startup until all are ready.
• Activities are dispatched straight into the shared pipeline; invoke responses are returned over the socket.
• Options are validated when the host starts, as in Python.
• Only the public cloud is supported, and other clouds are rejected at registration.
• A negotiate 401/403 is not retried, matching fix(apps): stop retrying Socket Mode negotiate on 401/403 and parse envelope metadata teams.ts#875 and teams.py:
  • At startup, it fails immediately with an actionable message.
  • During a reconnect or token rotation, it stops that geo and reports it disconnected. Other geos keep running.
• Socket Mode registers routing services. Without them, Core's authorization services fail DI validation on a generic host in Development.

Samples and docs

• New samples/SocketModeBot: a quoted echo reply, with credentials supplied through launchSettings.TEMPLATE.json.
• Socket Mode section in the Apps README, and the sample listed in the root README.
• Socket Mode is currently available only on the canary ring, so the sample and README set NegotiateBaseUrl to https://canary.botapi.skype.com.

Validation

• Unit tests cover options (including UseSocketMode(false)), hosting (generic host, the web app rejection, Development DI validation), dispatch, 401/403 handling, and an end-to-end test from a message over the socket to the reply posted to the conversation API.
• Core 202, Apps 812, and M365Extensions 16 tests pass on net8.0 and net10.0; BotBuilder 56 pass on net10.0.
• Manually verified against Teams with SocketModeBot: all three geos connected and the bot replied.

[azure-pipelines]

Azure Pipelines:
There may be pipelines that require an authorized user to comment /azp run to run.

[Copilot]

Copilot review overview

🟡 Changes recommended

The promised hosting API is absent, and Socket Mode currently discards envelope correlation vectors.

Review effort: Balanced
Findings: 2

Open (2)

• Preserve Socket Mode correlation vectors during dispatch · New
• Add the documented UseTeamsSocketApplication extension · New

What changed in this PR

Adds Socket Mode integration for receiving Teams activities through outbound WebSocket connections on a headless generic host.

Changes:

• Adds Socket Mode options, hosting, dispatch, and lifecycle handling.
• Adds transport-neutral activity processing and invoke-response capture.
• Adds extensive tests, documentation, and a sample bot.

File	Description
.gitignore	Ignores correctly cased launch settings.
Microsoft.Teams.slnx	Adds the Socket Mode sample.
README.md	Lists the new sample.
samples/​SocketModeBot/​Program.cs	Implements the echo bot.
samples/​SocketModeBot/​README.md	Documents sample setup and use.
samples/​SocketModeBot/​SocketModeBot.csproj	Defines the sample project.
samples/​SocketModeBot/​appsettings.json	Configures sample logging.
samples/​SocketModeBot/​Properties/​launchSettings.TEMPLATE.json	Provides credential placeholders.
src/​Microsoft.Teams.Apps/​README.md	Documents Socket Mode.
src/​Microsoft.Teams.Apps/​TeamsBotApplication.cs	Captures invoke responses for non-HTTP transports.
src/​Microsoft.Teams.Apps/​TeamsBotApplication.HostingExtensions.cs	Registers and selects hosting transports.
src/​Microsoft.Teams.Apps/​TeamsBotApplicationOptions.cs	Adds Socket Mode configuration.
src/​Microsoft.Teams.Apps/​SocketMode/​GeoSocket.cs	Handles terminal authorization failures.
src/​Microsoft.Teams.Apps/​SocketMode/​SocketModeHostedService.cs	Manages transport lifetime.
src/​Microsoft.Teams.Apps/​SocketMode/​SocketModeNegotiator.cs	Classifies authorization failures.
src/​Microsoft.Teams.Apps/​SocketMode/​SocketModeOptions.cs	Defines public options.
src/​Microsoft.Teams.Apps/​SocketMode/​SocketModeProtocol.cs	Uses the canary endpoint.
src/​Microsoft.Teams.Apps/​SocketMode/​SocketModeServiceRegistration.cs	Wires Socket Mode into DI.
src/​Microsoft.Teams.Apps/​SocketMode/​SocketModeTransport.cs	Integrates dispatch error handling.
src/​Microsoft.Teams.Core/​BotApplication.cs	Adds transport-neutral processing.
test/​Microsoft.Teams.Core.UnitTests/​BotApplicationTests.cs	Tests the new processing overload.
test/​Microsoft.Teams.Apps.UnitTests/​TeamsBotApplicationTests.cs	Tests invoke-response capture.
test/​Microsoft.Teams.Apps.UnitTests/​SocketMode/​GeoSocketTests.cs	Tests terminal authorization failures.
test/​Microsoft.Teams.Apps.UnitTests/​SocketMode/​SocketModeEndToEndTests.cs	Updates endpoint expectations.
test/​Microsoft.Teams.Apps.UnitTests/​SocketMode/​SocketModeHostingTests.cs	Tests hosting and end-to-end dispatch.
test/​Microsoft.Teams.Apps.UnitTests/​SocketMode/​SocketModeNegotiatorTests.cs	Tests authorization classification.
test/​Microsoft.Teams.Apps.UnitTests/​SocketMode/​SocketModeOptionsTests.cs	Tests public options.
test/​Microsoft.Teams.Apps.UnitTests/​SocketMode/​SocketModeTransportTests.cs	Tests dispatch logging and defaults.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.