Skip to main content

​
Microsoft Teams

Microsoft Teams is an enterprise channel integration that uses Azure Bot credentials, a Teams app package, and optional Microsoft Graph permissions. Status: text DMs are supported. Group/channel file features need SharePoint site configuration and Graph permissions.

​
Setup from Agent > Channels

Teams ships as a bundled channel extension. Open Agents, select the Agent, then use Agent > Channels > Microsoft Teams. You need:
  • Azure Bot app id
  • client secret
  • tenant id
  • public HTTPS messaging endpoint for /api/messages
  • Teams app package installed in the tenant/team
Minimal config: 
{
  channels: {
    msteams: {
      enabled: true,
      appId: "<APP_ID>",
      appPassword: "<APP_PASSWORD>",
      tenantId: "<TENANT_ID>",
      webhook: { port: 3978, path: "/api/messages" },
      dmPolicy: "pairing",
      groupPolicy: "allowlist",
    },
  },
}
Restart the gateway if the UI reports that the channel runtime still needs to load.

​
Access model

AreaRecommended start
DMsdmPolicy: "pairing"
Groups/channelsgroupPolicy: "allowlist"
Sender idsAAD object ids preferred
Name matchingkeep disabled unless you intentionally need it
Mentionsrequired in shared channels unless policy says otherwise
Use stable IDs when possible. Display names and UPNs can change.

​
Public endpoint

Teams requires a reachable HTTPS endpoint. Common local-development options:
  • Tailscale Funnel
  • trusted reverse proxy
  • Cloudflare Tunnel
  • ngrok or equivalent temporary tunnel
Set the Azure Bot messaging endpoint to: 
https://your-domain.example/api/messages

​
Graph and files

Basic text operation does not require broad Graph application permissions. Channel/group file sending and some lookup flows may need Graph permissions and SharePoint configuration. Keep Graph permissions narrow and document why each permission is enabled.

​
Runtime behavior

  • Teams conversations route into Agent sessions.
  • Replies return to the originating Teams conversation by default.
  • Task commands create Agent-owned Tasks; Teams is the transport.
  • Polls and richer UI use Adaptive Cards where supported.

​
Troubleshooting

SymptomCheck
Azure Bot receives nothingMessaging endpoint URL, public HTTPS, tenant/app id.
Auth failuresApp id, secret, tenant id, secret expiry.
Group replies blockedGroup policy, allowlist, mention requirement.
Files failGraph permissions, SharePoint site id, channel type.
App package upload failsManifest ids, bot endpoint, valid icon/assets.