Microsoft Teams
Connect a Teams bot through the Azure Bot Framework so people can chat with a governed flow in personal chats, group chats and channels (by @mention).
What you need
- An Azure subscription and permission to create an Azure Bot resource and a Microsoft Entra app registration.
- Permission to upload/publish a Teams app in your Microsoft 365 tenant (Teams admin, or sideloading allowed).
- A public HTTPS URL for this gateway (the bot's messaging endpoint).
Official documentation
- Create a bot for Teams: https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/create-a-bot-for-teams
- Bot Connector authentication: https://learn.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-connector-authentication
- Send and receive messages (REST): https://learn.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-connector-send-and-receive-messages
- Register a bot (Azure Bot resource): https://learn.microsoft.com/en-us/azure/bot-service/bot-service-quickstart-registration
- Teams app manifest: https://learn.microsoft.com/en-us/microsoftteams/platform/resources/schema/manifest-schema
Set up on Azure / Teams
- Azure portal → Create a resource → Azure Bot. Pick Multi Tenant (recommended) or Single Tenant, let Azure create a new Microsoft App ID (or reuse an app registration).
- Bot → Configuration → copy the Microsoft App ID. Click Manage Password → Entra app → Certificates & secrets → New client secret → copy the Value (shown once).
- Connect in Tools Anatomy (below), then back in Configuration paste the
Messaging endpoint shown by the console
(
…/v1/public/channels/teams/<hook>/messages) and Apply. - Bot → Channels → add Microsoft Teams → accept the terms.
- Create the Teams app: Teams → Developer Portal (or a manifest) with a Bot whose id = the Microsoft App ID, scopes personal, team, groupChat. Upload it (Upload a custom app) or publish it to your org via the Teams admin center.
- Single-tenant bots only: also paste the Tenant ID in the console's advanced field.
Connect in Tools Anatomy
/channels → Messaging channels → Microsoft Teams → paste:
| Field | Where it comes from |
|---|---|
| Microsoft App ID | Azure Bot → Configuration |
| Client secret | Entra app registration → Certificates & secrets (value) |
| Tenant ID (advanced) | Entra → Overview (single-tenant bots only) |
On connect the gateway requests a Bot Framework token with the App ID +
secret (client_credentials, scope https://api.botframework.com/.default)
to prove the credentials. The secret is stored in the Secret Manager.
How a message flows
Teams posts an Activity to the messaging endpoint with a Bot Connector
JWT. The gateway validates it exactly as Microsoft prescribes: issuer
https://api.botframework.com, audience = your App ID, RS256 signature
against the keys from https://login.botframework.com/v1/.well-known/openidconfiguration
(cached ≤ 24 h), 5-minute clock skew, and the token's serviceurl claim
must equal the activity's serviceUrl. Only type: "message" activities
are processed (<at>…</at> mention markup is stripped); membership updates
are acknowledged. The reply is posted to
{serviceUrl}/v3/conversations/{conversationId}/activities/{activityId}
with an app token.
Identity we derive
| Canonical key | Value |
|---|---|
external_user_id |
from.aadObjectId (Entra object id) when present, else the channel user id |
channel |
teams |
display_name |
from.name — runtime_only |
email, phone_number |
not provided (Graph API would be needed) |
conversation_context.channel_account_id = the bot id (recipient.id).
Threads: one conversation per Teams conversation id (personal chat, group
chat, or channel thread).
Limits
- In channels the bot only receives messages that @mention it.
- Very long replies are split (~28 000 characters per Teams message).
- Bot Framework/Teams throttle bots that send many messages quickly.
- Attachments/cards are acknowledged but not processed in v1.
Test it
Open the app in Teams and send a personal message, or @mention the bot in a channel where the app is installed. Azure Bot → Test in Web Chat also works (it uses the same messaging endpoint).
Troubleshooting
- 401 from the endpoint: the App ID pasted in the console differs from the bot's (audience check), or the client secret expired.
- Bot never answers in Teams but works in Web Chat: the Teams channel is not enabled on the Azure Bot, or the app package was not installed.
- Single-tenant bot cannot get a token: set the Tenant ID field.