Skip to main content

​
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; 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

Anything defined in the Microsoft Teams API 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.
1

Line up a Microsoft administrator

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.
2

Line up a Teams administrator

After connecting, a Teams administrator must upload Serval’s bot app package as a custom app in the Teams Admin Center under Teams apps → Manage apps.
3

Plan for auto-install (optional)

To pre-install the Serval app for assigned users, add it to a Teams Setup Policy (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. Note that the upload alone does not install the app for anyone - after it, the Serval app still has to be added from the Teams app store before it can be @mentioned (covered in Connect in Serval below).

​
Connect in Serval

1

Start the connection

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.
2

Accept Microsoft's admin consent prompt

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).
3

Download the Teams bot app package

Back on the Microsoft Teams integration page in Serval, open the API Integration tab - a Teams Bot Setup section appears there once the integration is connected. Click Download Teams Bot App to download Serval-Teams-Bot.zip, generated specifically for your installation.
4

Upload the package in the Teams Admin Center

Have your Teams administrator upload the ZIP at the Teams Admin Center 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.After the upload, Microsoft takes anywhere from a few minutes to an hour to propagate the app to your organization’s catalog. Until propagation completes, searching for Serval in the Teams client returns nothing - this delay is on Microsoft’s side and cannot be skipped.
5

Add the Serval app in Teams

The upload only publishes the app to your organization’s catalog - it does not install it for anyone, and @mentioning Serval in a channel finds nothing until the app is added. In the Teams client, go to Apps in the left sidebar and search for Serval. The app appears under Built for your org - this is your organization’s own uploaded package, not a public marketplace listing. Select it and click Add. To use Serval in a team’s channels, also add it to that team: use the Add to a team option and pick the team whose channels you want to connect.
6

Connect channels

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

Two separate causes look identical here, and they often stack:
  1. Propagation delay. After the Admin Center upload, Microsoft takes anywhere from a few minutes to an hour to propagate the app to your tenant’s catalog. Until then the app doesn’t exist as far as the Teams client is concerned - searching “Serval” under Apps returns nothing. Wait and search again; a passing Bot App Catalog Presence health check confirms the upload itself worked.
  2. The app was never added. Uploading publishes the app to your org’s catalog but installs it for no one. Someone must add it in the Teams client: Apps in the left sidebar → search Serval (it appears under Built for your org - your organization’s own uploaded package, not a public marketplace listing) → Add, and use Add to a team for the team whose channels you want to connect. Only then does the @mention picker find the bot.
To skip the per-user add entirely, an admin can pre-install the app through a Teams Setup Policy (see below).
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’.
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 under Teams apps → Manage apps before it appears in Setup Policy app search.
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. Workflows that combine Microsoft 365 user lookups with Teams messaging need both integrations 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 for assistance with your Microsoft Teams integration.