What the Teams path does not support, the failures operators hit most often, and where to read more.

Known limitations

Webhook timeouts

Teams delivers messages through the Gateway HTTP webhook route. The bounded Express parser keeps the 1 MiB decoded JSON limit, including gzip, deflate, and Brotli callbacks. Gateway HTTP lifecycle limits apply on the main listener; the compatibility listener preserves the previous Teams limits: 30s inactivity, 30s total request, and 15s to receive headers. During channel stop, new callbacks receive retryable HTTP 503 while active responses settle, for up to 30 seconds, before the route is released. Inbound attachment downloads get up to 120 seconds, because authenticated Teams image views can take tens of seconds; an attachment that misses that budget reaches the agent as unavailable. Optional context enrichment (team identity, quoted messages, thread history) then gets its own 10-second budget. The SDK returns after the raw activity is durably appended; the agent turn drains independently and replies proactively. If request handling or durable admission misses the transport window, Teams may retry the activity, and the ingress tombstone rejects a repeated event ID.

If Teams went silent after removing the legacyWebhook pin or setting it to false, check whether Azure Bot or your reverse proxy still points to port 3978. Follow the endpoint migration instructions to use the Gateway port or finish migrating an explicit legacy listener.

Teams cloud and service URL support

This SDK-backed Teams path is live-validated for Microsoft Teams public cloud.

Inbound replies use the incoming Teams SDK turn context. Out-of-context proactive operations - sends, edits, deletes, cards, polls, file-consent messages, and queued long-running replies - use the stored conversation reference serviceUrl. Public cloud defaults to the Teams SDK public cloud environment and allows stored references on the public Teams Connector host: https://smba.trafficmanager.net/.

Public cloud is the default. You do not need to set channels.msteams.cloud or channels.msteams.serviceUrl for normal public-cloud bots.

For non-public Teams clouds, set cloud and the matching proactive boundary when Microsoft publishes one:

Microsoft publishes the global proactive Bot Connector endpoints in the Create the conversation section of the Teams proactive messaging docs. Use the incoming activity's serviceUrl when available; otherwise use Microsoft's table below.

Teams environment Apus config Proactive serviceUrl
Public no cloud/serviceUrl config needed https://smba.trafficmanager.net/teams
GCC set serviceUrl; no separate Teams SDK cloud preset exists https://smba.infra.gcc.teams.microsoft.com/teams
GCC High cloud: "USGov" + serviceUrl https://smba.infra.gov.teams.microsoft.us/teams
DoD cloud: "USGovDoD" + serviceUrl https://smba.infra.dod.teams.microsoft.us/teams
China/21Vianet cloud: "China" use the incoming activity's serviceUrl

Example for GCC, where Microsoft documents a separate proactive service URL but the Teams SDK exposes no separate GCC cloud preset:

{
  "channels": {
    "msteams": {
      "serviceUrl": "https://smba.infra.gcc.teams.microsoft.com/teams"
    }
  }
}

Example for GCC High:

{
  "channels": {
    "msteams": {
      "cloud": "USGov",
      "serviceUrl": "https://smba.infra.gov.teams.microsoft.us/teams"
    }
  }
}

channels.msteams.serviceUrl is restricted to supported Microsoft Teams Bot Connector hosts. When a service URL is configured, Apus checks that the stored conversation serviceUrl uses the same host before proactive sends, edits, deletes, cards, polls, or queued long-running replies run. With the default public-cloud config, Apus fails closed if a stored conversation points outside the public Teams Connector host. Receive a fresh message from the conversation after changing cloud/service URL settings so the stored conversation reference is current.

China/21Vianet has no separate global proactive smba URL in Microsoft's Teams proactive endpoint table. Configure cloud: "China" so the Teams SDK uses Azure China auth, token, and JWT endpoints. Proactive sends then require a stored conversation reference from an incoming China Teams activity, or an explicitly configured service URL, on the Azure China Bot Framework channel boundary (*.botframework.azure.cn). Graph-backed Teams helpers are disabled for cloud: "China" until Apus routes Graph requests through the Azure China Graph endpoint.

Formatting

Teams markdown is more limited than Slack or Discord:

Troubleshooting

Common issues

Manifest upload errors

RSC permissions not working

  1. Verify webApplicationInfo.id matches your bot's App ID exactly.
  2. Re-upload the app and reinstall in the team/chat.
  3. Check if your org admin has blocked RSC permissions.
  4. Confirm you are using the right scope: ChannelMessage.Read.Group for teams, ChatMessage.Read.Chat for group chats.

References

Related