> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serval.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Microsoft Teams
> Connect Serval to your Microsoft Teams tenant to run a help desk in Teams channels and send messages from Serval workflows.
## About Microsoft Teams
The Microsoft Teams integration connects Serval to your organization's Teams tenant so the Serval bot can power a help desk directly inside Teams - receiving channel messages, @mentions, thread replies, group chat messages, and DMs - and so workflows can send direct messages, channel threads, and group chat messages. Setup is two one-time admin actions: a Microsoft administrator grants tenant-wide admin consent to Serval's managed application, and a Teams administrator uploads a Serval-generated bot app package to your organization's Teams app catalog. There is nothing for you to register or configure on the Microsoft side - Serval manages its own application. This integration is separate from the [Microsoft Graph integration](/sections/integrations/microsoft-graph); if your team also needs mail, calendar, SharePoint, or Entra user lookups, connect both.
**Authentication:** One-time Microsoft admin consent against Serval's managed application, plus a Teams bot app package uploaded by a Teams administrator. No credentials form - there is no client ID, secret, or app registration for you to create.
**Data sync:** No background data sync. Inbound Teams messages are pushed to Serval in real time as they happen; outbound messages and API actions run on demand with short-lived tokens minted per request. API requests from Serval workflows can only reach Microsoft's `graph.microsoft.com` and `smba.trafficmanager.net` services.
## What the Microsoft Teams integration enables
| Capability | Description |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Help desk in Teams channels | The Serval bot receives channel messages, @mentions, thread replies, group chat messages, and DMs - powering ticket creation and in-thread AI responses. You activate a channel by @mentioning the bot in it; the channel then appears in Serval, where you assign it one of five modes: Disabled, Help desk (Always respond), Help desk (When relevant), Silent, or On demand. |
| Send direct messages | Workflows can send a 1:1 direct message to any user in your tenant. Serval automatically installs its bot for that user first if needed. |
| Send channel messages | Workflows can start a new thread in a channel. They accept a copied Teams link - a "Copy link to channel" link, a team link, or a channel message link - and auto-install the bot into the team if needed. Proactive bot messages work in standard and shared channels, not private channels. |
| Send group chat messages | Workflows can post into an existing group chat using a copied chat link or a raw group chat ID (it starts with `19:` and typically ends in `@unq.gbl.spaces`). |
| In-Teams bot commands | Users can run `/healthcheck` in any team, group chat, or DM to check that Serval's connection to Microsoft Teams is working, and `/create-ticket` in a personal chat to create a Serval support ticket from a short form. |
| Microsoft Graph requests (Teams-scoped) | Advanced workflows can make arbitrary Microsoft Graph calls - catalog, install, membership, and channel queries - using the integration's tenant credentials. |
| Bot Framework requests | Advanced workflows can call the Bot Framework Connector API directly for activities, adaptive cards, reactions, and conversation operations. |
Anything defined in the [Microsoft Teams API](https://learn.microsoft.com/en-us/graph/api/resources/teams-api-overview) can be accessed through Serval.
## Get your credentials
There are no credentials to create. You will not register an Entra application, and you will never see or enter a client ID or secret - Serval uses its own managed application. Instead, two people in your organization each perform a one-time approval. Microsoft's official documentation on the admin consent flow is [here](https://learn.microsoft.com/en-us/entra/identity-platform/v2-admin-consent).
Connecting requires a Microsoft administrator account that can grant tenant-wide admin consent. The consent screen lists every application permission Serval's app is configured with - this is expected.
After connecting, a Teams administrator must upload Serval's bot app package as a custom app in the [Teams Admin Center](https://admin.teams.microsoft.com/policies/manage-apps) under **Teams apps → Manage apps**.
To pre-install the Serval app for assigned users, add it to a [Teams Setup Policy](https://learn.microsoft.com/en-us/microsoftteams/teams-app-setup-policies) (**Teams Admin Center → Teams apps → Setup policies**) after the upload.
Both admin actions are mandatory. Admin consent grants Serval API access; the bot app package upload is what allows the Serval bot to actually appear and operate in Teams. Skipping the upload is the most common cause of a "connected but not working" integration.
## Connect in Serval
In Serval, go to **Apps** → **Available** → **Microsoft Teams** and click **Connect Microsoft Teams**. There is no form to fill in - the Connect button is the entire flow.
You are redirected to Microsoft's admin consent screen. Sign in with a Microsoft administrator account and click **Accept**. Microsoft returns you to Serval and the integration is connected. Serval records your tenant and looks up your organization's display name (if the lookup fails, the raw tenant ID is shown instead).
Back on the Microsoft Teams integration settings page, a **Teams Bot Setup** section appears - it is only visible once the integration is connected. Click **Download Teams Bot App** to download `Serval-Teams-Bot.zip`, generated specifically for your installation.
Have your Teams administrator upload the ZIP at the [Teams Admin Center](https://admin.teams.microsoft.com/policies/manage-apps) under **Teams apps → Manage apps** as a custom app. Uploading through the Teams client also works for basic use, but only Admin Center uploads are eligible for Setup Policies.
In Teams, @mention Serval in any channel you want to use as a help desk. The channel then appears (in Disabled mode) under **Connected Channels** on the integration's Help Desk page in Serval, where you choose its mode - Disabled, Help desk (Always respond), Help desk (When relevant), Silent, or On demand.
**Reconnect** re-runs the full Microsoft admin consent flow end-to-end and saves a fresh connection - there are no editable fields to update. The bot app package can be re-downloaded at any time; it is regenerated on every download.
## Verifying the connection
The Microsoft Teams integration runs three health checks.
**Microsoft Teams Connectivity** - lists a small sample of your teams through Microsoft Graph to verify Serval's application permissions work. Finding zero teams still counts as success.
* Success: "Connected to Microsoft Teams. Found \[number] team(s) including: \[team names]" - or, with zero teams: "Connected to Microsoft Teams, but no teams found in the organization. Create a team in Microsoft Teams and try again."
* Insufficient privileges: "Serval does not have the required permissions to access Microsoft Teams. Please ensure the Team.ReadBasic.All application permission is granted in your Azure AD app registration. After adding the permission, an administrator must click 'Grant admin consent'."
* Access denied: "Access denied when connecting to Microsoft Teams. The Team.ReadBasic.All application permission may not be granted. Go to Azure AD → App registrations → API permissions and verify that Team.ReadBasic.All is listed and has admin consent granted."
* Authentication failure: "Authentication failed when connecting to Microsoft Teams. Admin consent may have been revoked, or the app credentials are invalid. Try reconnecting the Microsoft Teams integration."
* Not found: "The Microsoft Teams API endpoint was not found. This may indicate that Microsoft Teams is not enabled for your tenant."
* Microsoft server error: "Microsoft Teams returned a server error. This is likely a temporary issue with Microsoft's API - please try again later."
* Consent never granted: "Admin consent has not been granted for the Microsoft Teams integration. Please reconnect the integration - a Microsoft administrator must approve the consent prompt."
* Anything else: "Unable to connect to Microsoft Teams. Please verify the integration is connected and the admin has approved the required permissions."
**Bot App Catalog Presence** - searches your organization's Teams app catalog for the Serval bot app, checking each known Serval app identity until one is found.
* Success: "Serval bot app is present in the organization's Teams app catalog (ID: \[app ID])."
* Not found: "The Serval bot app was not found in your organization's Teams app catalog. An administrator needs to upload the app package (downloadable from this page) in the Teams Admin Center under 'Manage apps'. Without this, the bot cannot be installed to teams or users."
* Insufficient privileges: "Serval does not have permission to query the Teams app catalog. Ensure the AppCatalog.Read.All application permission is granted in your Azure AD app registration and that an administrator has clicked 'Grant admin consent'."
* Access denied: "Access denied when querying the Teams app catalog. The AppCatalog.Read.All permission may not be granted. Check Azure AD → App registrations → API permissions."
* Authentication failure: "Authentication failed when querying the Teams app catalog. Admin consent may have been revoked, or the app credentials are invalid. Try reconnecting the Microsoft Teams integration."
* Anything else: "Unable to query the Teams app catalog. Please verify the integration is connected and the admin has approved the required permissions."
**Channel Resolution** - lists your teams, verifies the first team's internal ID is readable (required to work out which channel the bot was @mentioned in), then lists that team's channels. Zero teams is reported as success with a caveat.
* Success: "Channel resolution is working. Team "\[name]" has internalId and \[number] channel(s)." - or, with zero teams: "Connected to Microsoft Teams, but no teams found in the organization. Channel @mention support requires at least one team."
* Missing internal ID: "Serval can list teams but cannot read team internal IDs. This prevents Serval from resolving which channel the bot was @mentioned in. Please ensure the Team.ReadBasic.All application permission is granted with admin consent in Azure AD → Enterprise Applications → Serval → Permissions."
* Insufficient privileges: "Serval does not have the required permissions to resolve Teams channels. Please ensure Team.ReadBasic.All and Channel.ReadBasic.All application permissions are granted in your Azure AD app registration with admin consent."
* Access denied: "Access denied when resolving Teams channels. The required application permissions (Team.ReadBasic.All, Channel.ReadBasic.All) may not be granted. Check Azure AD → App registrations → API permissions."
* Authentication failure: "Authentication failed when resolving Teams channels. Admin consent may have been revoked, or the app credentials are invalid. Try reconnecting the Microsoft Teams integration."
* Anything else: "Unable to resolve Teams channels. This is required for channel @mention support. Please verify the integration is connected and the admin has approved the required permissions."
Several of the failure messages above say to fix permissions "in your Azure AD app registration". Because Serval uses its own managed multi-tenant application, there is no app registration in your tenant to edit - as one of the messages correctly notes, the Serval app appears under **Enterprise applications** instead. Grant or repair these permissions by re-granting tenant-wide admin consent: click **Reconnect** in Serval with a Microsoft administrator account, or review the Serval app in the Microsoft Entra admin center under **Enterprise applications**.
If Microsoft Teams Connectivity passes but the bot can't send messages or be @mentioned, run Bot App Catalog Presence next. A green connectivity check only proves admin consent - it says nothing about whether the bot app package was uploaded to your Teams app catalog.
## Gotchas and troubleshooting
Connecting (admin consent) only grants API access. Until a Teams admin uploads `Serval-Teams-Bot.zip` to the org app catalog (**Teams Admin Center → Manage apps**), the bot cannot install itself anywhere: the Bot App Catalog Presence health check fails, and every send-message action fails. Direct messages report:
> We couldn't find the Serval application in your Microsoft Teams app catalog. Please ask an administrator to upload it in Teams Admin Center before direct messages can be sent.
Channel and group chat messages report that the Serval bot app was not found in the Teams app catalog and that an administrator must upload the app package in Teams Admin Center, followed by diagnostic details of each app identity Serval tried. The bot's chat and channel read/send rights come from resource-specific consent declared in the uploaded package - not from admin consent.
Working out which channel the bot was @mentioned in requires reading each team's internal ID. The Channel Resolution health check detects this exact failure: "Serval can list teams but cannot read team internal IDs. This prevents Serval from resolving which channel the bot was @mentioned in..." If channel @mentions aren't creating tickets, run this health check first.
The Bot App Catalog Presence health check and the auto-install step in every send-message action query your Teams app catalog. A permissions denial here maps to the literal guidance: ensure AppCatalog.Read.All is granted and an administrator has clicked 'Grant admin consent'.
Token failures are translated into plain messages. The directory or tenant named in them is the organization name Serval recorded when you connected (or the raw tenant ID if the name lookup failed).
* AADSTS700016: "The Serval application was not found in the directory '\[organization name]'. This usually means admin consent has not been granted or has been revoked. Please reconnect the Microsoft Teams integration to grant admin consent again."
* AADSTS65001: "Admin consent has not been granted for the Microsoft Teams integration. Please reconnect the integration - an administrator must approve the consent prompt."
* unauthorized\_client: "The Serval application is not authorized for tenant '\[organization name]'. This typically means admin consent needs to be granted. Please reconnect the Microsoft Teams integration."
* AADSTS7000215: "The client secret for the Serval application is invalid. Please contact Serval support." - that one is a Serval-side issue, not something you can fix.
For all customer-side cases, the fix is the same: **Reconnect** the integration with a Microsoft administrator account.
Each downloaded `Serval-Teams-Bot.zip` is stamped with your specific installation's identity. If the catalog app doesn't match the connected integration, direct messages report:
> We found the Serval application in your Microsoft Teams app catalog, but couldn't install it with the current Microsoft Teams integration configuration. Please ask an administrator to verify the Microsoft Teams integration is configured for the correct Serval application.
Channel messages similarly report that Serval found the app but couldn't install it in the target team - which can also happen when the team hasn't granted the required resource-specific permissions or tenant policy blocks app-only installation. Re-download the package from the current integration settings page and re-upload it.
Teams Setup Policies (auto-install for users) only see apps uploaded through the Teams Admin Center, not apps uploaded via the Teams client's 'Upload a custom app'. If the app was client-uploaded, also upload it at the [Teams Admin Center](https://admin.teams.microsoft.com/policies/manage-apps) under **Teams apps → Manage apps** before it appears in Setup Policy app search.
The send-channel-message action only accepts a copied Teams link - a channel link, team link, or channel message link that includes the destination team. Anything else is rejected with: "Invalid Microsoft Teams channel identifier. Paste a copied Teams channel, team, or channel message link that includes the destination team." Private channels are also rejected - proactive bot messages require a standard or shared channel. (Group chats are more lenient: a raw chat ID starting with `19:` works there.)
If the Serval bot isn't already a member of a group chat containing external or cross-tenant participants, automatic install fails. A user native to the hosting tenant must add the Serval bot to the chat once; subsequent group chat messages then succeed.
Teams has its own Serval-managed application, its own admin-consent flow, and its own tenant-scoped connection - it does not use or require the [Microsoft Graph integration](/sections/integrations/microsoft-graph). Workflows that combine Microsoft 365 user lookups with Teams messaging need both integrations connected.
The connect UI is a single **Connect Microsoft Teams** button - there are no credential fields, so there is nothing to edit later. **Reconnect** re-runs the Microsoft admin consent flow end-to-end and saves a fresh connection. The **Teams Bot Setup** / **Download Teams Bot App** section appears only after the integration is connected.
Microsoft's roughly 28 KB cap on message and adaptive-card payloads is not checked before sending; oversized messages fail at Microsoft's API with an opaque error. Send actions already retry transient failures automatically (up to 5 attempts) - workflow authors should not add their own retry loops on top.
***
Need help? Contact **[support@serval.com](mailto:support@serval.com)** for assistance with your Microsoft Teams integration.