Connect Microsoft Teams
Create a Microsoft Teams bot for one Coworker in the Teams Developer Portal (or as an Azure Bot), upload the Teams app package, and choose whether Microsoft reaches Workforce Intelligence at a public address or over a connection your deployment opens (Socket mode).
A chat app lets people message one Coworker from Microsoft Teams. Each app is bound to exactly one Coworker, so the Coworker has its own bot name in Teams. You create the bot in your own Microsoft tenant, in the Teams Developer Portal, and Workforce Intelligence generates the Teams app package for you. No Azure subscription is needed. (If your organization manages its bots in Azure, you can use an Azure Bot instead.) The Coworker answers with the permissions of the person who messaged it, never with more. See Chat with a Coworker in Slack or Microsoft Teams for what people see.
Before you start#
- You need the
adminability, and the Coworkers product area must be on (see Features). Chat apps is on Settings, in the Coworkers & Apps group. - You need a Microsoft 365 account with Teams, and permission to upload an app in the Teams admin center (or the right to upload a custom app in Teams).
- Workforce Intelligence's public address (
WI_PUBLIC_BASE_URL) must start withhttps://, because the Teams app package links to it. If it does not, the page says so. - Decide how Microsoft will reach Workforce Intelligence (see Choose how Microsoft reaches Workforce Intelligence).
Create the bot in the Teams Developer Portal#
- Open the Teams Developer Portal and sign in with your work account. Select Tools in the left menu, then Bot management. On the Teams-managed bots tab, select New bot and give it a name.
- Open the bot and select Client secrets, then Create your first client secret. Copy the secret's value right away. Microsoft shows it only once.
- Go back to the Bot management list and copy the bot's Bot Id. This is the App ID that Workforce Intelligence asks for.
- Copy your tenant ID: it is shown on the Overview page of the Microsoft Entra admin center as Tenant ID.
Add the bot#
-
In Workforce Intelligence, open Settings > Chat apps and select Add chat app. (With no apps yet the page reads "No chat apps" and offers the same button.)
-
Under Chat app, choose Microsoft Teams.
-
Fill in the form:
Field What to enter Coworker The Coworker people will message. The app is listed here as, for example, "Ren - Teams", and appears in Teams under the Coworker's name ("Ren"). App ID The bot's Bot Id. It must be a GUID such as 11111111-2222-3333-4444-555555555555.Tenant ID The Microsoft Entra tenant the bot lives in, also a GUID. A name or domain is refused. Client secret The secret you created for the bot. Stored encrypted and never shown again. How Teams reaches this deployment Directly at a public address (the default) or over a Socket mode connection your deployment opens. See the choices below. Allow in channels Off by default. See Allow in channels. -
Select Add app.
The card opens with a guided setup of four steps: Add the bot, Connect the bot, Add the app to Teams and Check the connection. The card carries Setup incomplete until the details are saved. To correct them later, open Manage and use Bot details: change the App ID or Tenant ID, or replace the Client secret (a saved secret reads Saved with a Replace button), then select Save details. If you change the App ID, download and upload the Teams app package again.
Connect the bot#
Microsoft sends each Teams message to an address you give the bot. Workforce Intelligence makes that address (the Messaging endpoint) for this app, so copy it from the setup and put it in the bot.
- In the Teams app's setup on Settings > Chat apps, open Connect the bot and copy the Messaging endpoint with Copy.
- In the Teams Developer Portal, open your bot and select Configure. Keep HTTPS endpoint selected, paste the address into the endpoint box and save it. Reload the page afterwards to check that the portal kept it.
- Select Channels and make sure Microsoft Teams is checked (it is by default). Leave the other options off.
If the messaging endpoint does not appear, the panel says why. The usual cause is a public address
that does not start with https://.
Use an Azure Bot instead#
If your organization manages its bots in Azure, create the bot there. You need an Azure subscription that can hold an Azure Bot. A Microsoft 365 license with Teams does not include one: if the subscription list in the Azure portal is empty, sign up for an Azure subscription first (the Azure Bot's Free pricing tier costs nothing). You also need permission to register an app in Microsoft Entra ID.
- In the Microsoft Entra admin center, open App registrations in the left menu, then New registration. Name it, choose single tenant (accounts in this organizational directory only), leave the redirect URI empty and select Register.
- On the app's Overview page, copy the Application (client) ID and the Directory (tenant) ID.
- Under Certificates & secrets, select New client secret, give it a description and an expiry, and select Add. Copy the secret's Value (not the Secret ID) right away. Microsoft shows it only once.
- Add the bot in Workforce Intelligence as described in Add the bot, using the application ID, tenant ID and client secret from the Entra app.
- In the Azure portal, select Create a resource, search for Azure Bot and select Create. Enter a Bot handle, choose your Subscription and Resource group (create a resource group if you have none) and set the Pricing tier to Free.
- Set Type of app to Single Tenant and Creation type to Use existing app
registration. Enter the App ID and Tenant ID from the Entra app, then select **Review
- create** and Create, and wait for the deployment to finish.
- Open the new bot, go to Settings > Configuration, paste the Messaging endpoint from Workforce Intelligence and select Apply.
- In the bot's Channels, add Microsoft Teams, accept the terms and select Apply.
You can do steps 5 to 8 with the Azure CLI instead. The setup panel's Copy commands button copies the commands, with your App ID, tenant ID and messaging endpoint filled in and the client secret left out. Fill in the bot name and resource group, then run them:
botName="<bot name>"
resourceGroup="<resource group>"
az bot create --name "$botName" --resource-group "$resourceGroup" --app-type SingleTenant --appid "<your App ID>" --tenant-id "<your tenant ID>" --endpoint "<messaging endpoint>"
az bot msteams create --name "$botName" --resource-group "$resourceGroup"
# Already created the bot? Point it at this address instead:
# az bot update --name "$botName" --resource-group "$resourceGroup" --endpoint "<messaging endpoint>"
Add the app to Teams#
Teams needs an app package, a zip with the app manifest and icons, before people can find the bot. Workforce Intelligence builds it for you.
- In the setup, open Add the app to Teams and select Download Teams app package.
- In the Teams admin center, open Teams apps > Manage apps, select Upload new app and choose the zip. (Without admin access, upload it in Teams under Apps > Manage your apps > Upload a custom app, if your organization allows custom apps.)
- Install the app for the people who will use it, or let them add it from Teams.
The package describes the Coworker (its name, role and main responsibilities) and links to your
deployment's public address as the developer website, privacy and terms address. If your
organization has its own pages for those, edit manifest.json in the zip before you upload it.
Workforce Intelligence cannot see whether the package was uploaded.
A person must have the app installed before the Coworker can send them a message on its own, such as a notification. Teams refuses with a 403 until the app is installed for that person, and Workforce Intelligence records that the notification failed. Installing the app for people from the Teams admin center, or asking them to add it, avoids this.
Check the connection#
Once the bot exists and the app is uploaded, confirm the setup. In Check the connection, select Test connection. It confirms that Microsoft accepts the saved App ID, tenant ID and client secret. A pass reads "Microsoft accepted the saved credentials. Connected to Microsoft tenant <tenant ID>." and the step reads "Done. Open <app name> in Microsoft Teams and send it a message to try it." A failure reads "Microsoft did not accept this app id, tenant id and client secret. Check them against your bot in the Teams Developer Portal." The test checks only the saved credentials. It does not check that the bot's endpoint is right or that the package was uploaded, so finish by sending the bot a message in Teams. If the Coworker has been mentioned in a channel and Teams refused to let it read the messages around the mention, the result also reads "Update the Teams app to let the Coworker read the messages around a mention". The check still passes: only the surrounding messages are missing.
Choose how Microsoft reaches Workforce Intelligence#
Under How Teams reaches this deployment you choose between two ways:
| Choice | How it works | Pick it when |
|---|---|---|
| Microsoft Teams sends messages to us | Microsoft posts each message to your deployment's API address, /api/channels/msteams/<app>/messages. The address must start with https:// (WI_API_BASE_URL) and be reachable from the internet. |
Your deployment has a public address. |
| We connect to Microsoft directly (no public address needed) | Your deployment opens an outbound connection to Microsoft (Socket mode) and receives each message over it. No public address, tunnel or proxy is involved, and no message passes through a service of ours. Replies go straight from your deployment to Microsoft. | Your deployment is behind a firewall and has no public address, and the bot was created in the Teams Developer Portal. |
Use Socket mode#
Socket mode is Microsoft's Teams Developer Portal delivery method named Socket mode. Microsoft describes it as a preview feature, recommended only while you develop agents, available only for bots created in the Developer Portal, and without the features that need a web address Microsoft can call. Use it when your deployment cannot be reached from the internet and you accept those limits.
- In the Teams Developer Portal, open Tools, Bot management, and create the bot there (or open the bot you made for this app). Use the same App ID and client secret you entered in Workforce Intelligence.
- Set the bot's delivery method to Socket mode. There is no messaging endpoint to enter.
- Open Manage on the Teams app. Under How Teams reaches this deployment, choose We connect to Microsoft directly (no public address needed) and select Use Socket mode. A notice, Set the bot to Socket mode, repeats step 2. Select Dismiss. You can also choose it when you add the app.
- Choose Test connection, then upload the app package as usual.
The card shows Connection as "We connect to Microsoft Teams" and a Teams connection row, Connected or Not connected. It reads Connected only while every one of Microsoft's regional connections (Americas, Europe and Asia Pacific) is up. Your deployment holds one connection for each region, replaces each shortly before Microsoft's connection token expires, and reconnects by itself with growing waits after a drop. If Microsoft refuses the bot's credentials or Socket mode access, it waits several minutes between attempts, so fix the App ID, tenant ID or client secret (or the bot's delivery method) and the connection returns on its own.
Messages are received only over the connection your deployment opened, which Microsoft accepts only for this bot's own credentials. Replies and notifications still go through Microsoft's Bot Connector as for every other choice. Only one process of your deployment holds a given app's connection at a time. Select Use the direct address and confirm to go back; the Azure Bot's messaging endpoint must then point at this deployment again.
Your deployment needs outbound HTTPS to *.botapi.skype.com (the regional connection setup) and to
the connection address Microsoft returns. See
Deployment requirements.
Use the direct address#
- Under How Teams reaches this deployment, choose Directly. Microsoft sends messages to a public address of this deployment.
- Select Use the direct address and confirm Use the direct address? Microsoft Teams messages stop arriving until you change the Azure Bot's messaging endpoint back to this deployment's direct address. After you switch, the notice shows that address to paste into the Azure Bot.
Apps that were connected through the proxy#
An app whose connection was the central Workforce Intelligence proxy is no longer connected. Its card reads Not connected and shows a notice that the proxy connection is no longer available. Under How Teams reaches this deployment neither choice is selected. Choose Microsoft Teams sends messages to us or We connect to Microsoft directly (no public address needed) to reconnect it, then follow the steps for that choice above. Nothing is received for the app until you do.
Allow in channels#
By default the Coworker answers only in personal chats. Turn on Allow in channels (on the add form, or under Manage) so people can mention it in team channels and group chats. Think about this before you turn it on: everyone in the chat sees the reply, while the Coworker uses only the permissions of the person who asked. A person with access to private information can therefore, by asking in a channel, show it to everyone there. In channels and group chats the Coworker answers only when it is mentioned by name (an @mention). Each channel thread is its own conversation with that person (a group chat, which has no threads, is one conversation per person); a new thread continues from that person's most recent conversation in the same channel, and a conversation is never shared with another person. A message sent while the Coworker is still working on the same person's request is added to that request. A personal chat has no threads, so it is one continuous conversation per person. Files people attach are used only in personal chats.
Teams reads where a bot may be used from the app package. After you change this setting, download the package again and upload it in Teams.
What the Coworker reads around a mention#
When someone mentions the Coworker in a channel, a channel thread or a group chat, the Coworker reads what that person's conversation has not seen. The first time that person mentions it there, that is up to 10 of the messages just before the mention (at most 1,000 characters each): in a channel the latest posts above the mention, in a group chat the latest messages. A new thread of that person reads what was posted since they last talked to it in the channel: up to 30 messages (at most 8,000 characters in all, oldest dropped first). A person who is new to a thread (for instance someone mentioning the Coworker in a thread another person started) reads the thread from its first post, up to 30 messages with the first one always kept, including the Coworker's replies to the others; another person's conversation with the Coworker is never read. Returning to their own thread, a person reads that thread's replies since they last wrote there plus its first post. Replies inside other threads of the channel are not read, because Microsoft Graph's channel list returns only each thread's first post. The Coworker's own replies to that person are left out (the conversation already has them). It reads them through Microsoft Graph with the bot's own app registration, only in the team or chat where it was mentioned, and treats them as background from other people, never as instructions. They are saved with the person's conversation. It reads nothing in a personal chat.
For that, the app package of an app that allows channels asks for two permissions, which Teams calls resource-specific consent: ChannelMessage.Read.Group (read a team's channel messages) and ChatMessage.Read.Chat (read a group chat's messages). Whoever adds the app to a team or group chat approves them there, for that team or chat only, so no tenant-wide admin consent and no extra Graph permission on the bot's app is needed. Once approved, Teams also sends the app every message in that team or chat, not only mentions; Workforce Intelligence ignores any message that does not mention the Coworker. Say so in your own notice to the people in those teams if your organization needs to.
An app set up before this was available has a package without these permissions, and its Coworker answers in channels with no surrounding messages. To add them, turn on Allow in channels if it is off, select Download Teams app package, upload the new package in Teams as an update to the existing app (Teams admin center, Teams apps, Manage apps, select the app, Upload new version), and accept the permissions when the app is added to, or updated in, each team or group chat. If a read is refused for lack of the permissions, the mention still gets an answer, and Test connection adds "Update the Teams app to let the Coworker read the messages around a mention" to its result once that has happened.
What the Coworker can do on its own#
Besides answering, a Coworker can post in Teams when a person asks it to (or when a schedule that person set up runs): in a team channel or group chat it has already been used in, and in a personal chat with someone who has messaged it before. Teams only lets a bot write where it has a conversation, so the Coworker offers the places it has seen and never one it has not. A person who has never messaged the Coworker cannot be messaged first. A new channel thread is opened with the channel's own address. It can also react to a message, such as an eye, a thumbs up or a check mark, on the message that asked it or on a thread's first message; Teams accepts about two reactions a second across the bot. The same limits as in Slack apply: 20 messages in one run, 60 per Coworker per hour and 10 to one destination per hour, and the Coworker never sends mass mentions or messages another bot. A person who replies and has not linked their account gets the usual Link account prompt.
A trigger can also have a default destination: a channel or group chat the bot has already been used in, or a direct message to the person who created the trigger (who must have messaged the bot once). When a run finishes, its final message is posted there automatically, as that person, with no separate switch. The destination list comes from the places the bot has seen, because Teams cannot list where a bot may post. Choosing, changing or clearing it is recorded in the Audit tab as Changed where a trigger posts its results. Deleting the bot clears every destination that used it. See Triggers.
Manage the app#
Select Manage on an app's card (or Continue setup while setup is unfinished). Under Settings:
- Coworker, then Save changes. Changing the Coworker makes the app answer as that Coworker from then on and renames it to match (download the package again and upload it to change the name in Teams too).
- Turned on: when off, nobody can message the Coworker through this app.
- Allow in channels, described above.
- Delete app asks you to confirm. The app stops answering, its saved credentials are removed and its chat threads are removed from Workforce Intelligence. Conversations already in Workforce Intelligence stay, people's linked Teams accounts stay, and you can add the app again at any time. Delete the bot in the Teams Developer Portal (or in Azure) and the app in Teams as well if you no longer want them.
A card shows Provider, Coworker, App ID, Tenant ID, Connection, Status (On or Off) and Channels (Allowed or Direct messages only).
What people see#
- A person who has not linked their account gets a private message with a Link account button. See Chat with a Coworker in Slack or Microsoft Teams.
- A person must message the bot once before it can send them notifications (Teams requires that first conversation), and a notification is delivered only if the app is installed for them.
- Replies are split into several messages when they are long. A file the Coworker shares is sent as a link to the file in Workforce Intelligence. Files people send in personal chats can be of any type, up to 10 files per message and 10 MB each; each is saved in the conversation and placed in the Coworker's working folder so it can open and work with it.
- Teams shows a typing indicator while the Coworker works.
Who can do what#
Adding, changing, turning on and off, switching how Teams reaches the deployment and deleting a chat app needs the admin
ability, with the Coworkers product area on. The credentials are write-only. Every change is
recorded in the audit log as Added a chat app, Changed a chat app, Removed a chat app or
Replaced a chat app's credentials, with the app's name and the names of the fields that
changed, never a secret. Switching how Teams reaches the deployment is recorded as Changed a chat
app. See The Audit log.
Reaching Microsoft#
Your deployment calls Microsoft over HTTPS to sign in as the bot (login.microsoftonline.com), to
fetch the keys that verify incoming messages (login.botframework.com), to send replies and
notifications (Microsoft's Bot Connector, smba.trafficmanager.net), to read the messages around a
mention in channels and group chats (Microsoft Graph, graph.microsoft.com) and to download files
people attach. If a firewall limits outbound traffic, allow those on port 443. Under the direct choice
Microsoft must also be able to reach your API address from the internet.