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

CapabilityDescription
Help desk in Teams channelsThe 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 messagesWorkflows 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 messagesWorkflows 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 messagesWorkflows 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 commandsUsers 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 requestsAdvanced workflows can call the Bot Framework Connector API directly for activities, adaptive cards, reactions, and conversation operations.
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.

​
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 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.
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.
5

Activate 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

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.