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. There are two ways to connect:
  • Serval’s Teams app (the default): 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. With this option there is nothing for you to register or configure on the Microsoft side - Serval manages its own application.
  • Custom Application: the bot runs as your organization’s own Microsoft application instead of Serval’s. You register an application in Microsoft Entra ID, create an Azure Bot that routes Teams messages to Serval, author and install your own Teams app package, and give Serval the application’s credentials.
This integration is separate from the Microsoft Graph integration; if your team also needs mail, calendar, SharePoint, or Entra user lookups, connect both. Authentication: Serval’s Teams app (default): one-time Microsoft admin consent against Serval’s managed application, plus a Teams bot app package uploaded by a Teams administrator - no client ID, secret, or app registration for you to create. Custom Application: your own Entra app registration’s Directory (tenant) ID, Application (client) ID, and client secret (OAuth 2.0 client credentials), entered in Serval’s connect form and verified at connect time. 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.
The automatic bot installation mentioned in the send actions above applies to Serval’s Teams app only. Serval never installs a custom application: with a Custom Application connection, your organization uploads and installs its own app package, and any send to a place the app is not installed fails with an “is not installed” error naming your app ID (see Custom application errors).

​
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

In Serval, go to Integrations → All integrations → Microsoft Teams and click Connect Microsoft Teams. The connect dialog offers two options: Connect Serval’s Teams app (recommended) - “Grant admin consent for Serval’s managed Teams bot.” - and Custom Application - “Advanced setup using an app registration created by your organization”.
1

Start the connection

In the connect dialog, choose Connect Serval’s Teams app. There is no form to fill in for this option.
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 the connection’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. On a Custom Application connection this check is informational: Serval doesn’t know your app package’s identity, so it reports success without querying the catalog - “This connection uses a customer-provided Teams app, so Serval does not check the organization’s app catalog for it. Manage the app package in Teams Admin Center.”
  • 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”. What that means depends on the connection type. With Serval’s Teams app there is no app registration in your tenant to edit - the Serval app appears under Enterprise applications instead, and you grant or repair 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. With a Custom Application the guidance is literal: the app registration is yours, so add the missing permission under App registrations → API permissions and click Grant admin consent.
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 the credentials work - it says nothing about whether the bot app package was uploaded to your Teams app catalog. (On a Custom Application connection that check is informational, so verify the app package upload and installation directly in Teams Admin Center.)

​
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).
On a Custom Application connection, “connected” proves only that the credentials can mint tokens - message delivery depends entirely on Microsoft-side wiring that Serval cannot check for you. Work through these in order:
  1. Messaging endpoint. On the Azure Bot → Settings → Configuration, the endpoint must be exactly the one for your deployment (see Point the messaging endpoint at Serval) - re-check for typos.
  2. Teams channel. On the Azure Bot → Settings → Channels, Microsoft Teams must show Running.
  3. Tenant-mode match. The Azure Bot’s Type of App must match the Entra app’s Supported account types (both Single Tenant, or both Multi Tenant), and its App ID and App tenant ID must equal the Entra app’s client and tenant IDs. A mismatch makes Teams reject delivery with a 401 before anything reaches Serval.
  4. App package installed. The manifest’s bots[0].botId must be the same client ID you entered in Serval, and the package must be uploaded and added where you expect the bot to respond.
Serval never installs a custom application - if a workflow sends to a place your app package hasn’t been installed, Microsoft’s Bot Framework rejects the send and Serval reports which scope is missing, naming your app ID:
Your Teams app (app ID [your app ID]) is not installed in the user’s personal scope. Install your app package in Teams Admin Center (org-wide or via an app setup policy), then retry.
Your Teams app (app ID [your app ID]) is not installed in the target team. Install your app package in Teams Admin Center (org-wide or to the team), then retry.
Your Teams app (app ID [your app ID]) is not installed in the group chat. Install your app package in Teams Admin Center and add it to the chat, then retry.
Each message ends with the underlying send error from Microsoft. The fix is always on your side: install the app package in the named scope, then retry the send.
You can switch an existing connection between the two options in either direction without disconnecting, as long as you stay on the same Microsoft tenant - connecting the other option with the same Directory (tenant) ID swaps the stored credentials on the existing connection, and your connected channels and their modes survive the switch.The Teams side does not switch itself: the two options are different Microsoft applications, so you must also swap the app package in Teams. Moving to a custom application, upload and install your own package (Serval stops offering the Serval-Teams-Bot.zip download for a custom connection - requesting it answers “No app package exists for a custom app install”). Moving back to Serval’s app, re-run the admin consent flow, then download and upload Serval-Teams-Bot.zip again. Until the matching package is installed, sends fail with the errors above.Serval never reveals its own application’s secret: opening the credentials form on a connection that currently uses Serval’s Teams app shows only the connection’s name and tenant ID, and switching to a custom application always requires entering your own client ID and secret.
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’. (Both behaviors belong to Serval’s Teams app - on a Custom Application connection the catalog check is informational and sends never query the catalog.)
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 application (Serval’s managed app or your custom one), its own connect 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.
With Serval’s Teams app 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, and the Teams Bot Setup / Download Teams Bot App section appears once the integration is connected. With a Custom Application it’s the mirror image: the settings page shows an editable credentials form, and there is no package download - the app package is yours to manage in Teams Admin Center.
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.

​
Custom application errors

Errors on a Custom Application connection name your app registration and are fixable on your side. The connect form (and every later credential edit) reports verification failures inline; the same authentication errors can also surface later on sends if consent is revoked or the secret expires.
Need help? Contact support@serval.com for assistance with your Microsoft Teams integration.

​
Forms in Teams

Teams form dialogs follow the personal help agent Teams rollout. They require Enable personal help desk in your organization settings. There isn’t a separate forms switch or required setup test.
When Serval asks you to complete a form in a ticket conversation or the personal help agent, select Open form to open it in a Teams dialog. Serval uses your Teams identity to verify that you’re the active, linked requester for that form. Other people who can see the card can’t fill it on your behalf. The dialog uses your Teams display language when Serval supports it, then your browser language, and English otherwise. On slower connections, the form may appear in English while your display language loads. You can start filling it out while translations load. With the updated Teams app package, Teams desktop and web keep the native loading indicator visible until the form or an error is ready. Mobile clients and older packages use Serval’s loading indicator while the form loads. Select View ticket on the card to open the ticket in Serval. If a Teams dialog isn’t available, Open form opens the form in your browser instead. After submission, the original card shows Form submitted and replaces Open form with View form. Select View form to review the submitted answers in a read-only dialog. If you leave a newly uploaded file unsaved for more than 24 hours, upload it again before saving or submitting. Files already saved with the form remain available. For forms created in the form builder, changes save automatically as you work. Select Submit when you finish to resume the ticket’s workflow. Closing the dialog with X keeps only changes already saved. If saving fails, the dialog shows an error and a Retry button. If another session changes the form, reload it before continuing. If the dialog can’t load the form, Open in Serval opens it in your browser. Form-builder forms containing repeaters or signed-document fields also offer a browser link. Use the browser experience if Teams sign-in is unavailable or you’re a guest or cross-tenant user. Sovereign Microsoft cloud deployments use the browser experience. Existing messages retain their original links.

​
Forms from older workflows

Conversations and the personal help agent can also open forms from older workflows in a Teams dialog. These dialogs use the same Open form, Form submitted, and View form states. They support conditional fields, entity selections, file uploads, and document signing. Select Submit to save your answers and continue the workflow. These workflow forms don’t save drafts automatically; closing the dialog discards unsent answers. If the submission response is interrupted, select Check submission before trying again. These dialogs use the same Teams SSO as form-builder forms. If you’ve already configured Teams form sign-in, you don’t need another Entra or Okta application. Otherwise, update your existing Teams connection as described below. If Teams sign-in is unavailable, select Open in Serval to continue through your usual browser sign-in. Existing ticket-channel forms keep their current inline-card or browser experience.

​
Update an existing Teams connection

You can keep your existing Serval connection, bot, credentials, and Teams app ID.
  1. In the connection’s setup, download the updated Teams Bot App package. Use version 1.1.1 or later with the current form hostname and native loading experience.
  2. Ask your Teams administrator to upload it as an update to the existing organization-catalog app and make the update available to users.
  3. Complete additional Microsoft administrator consent if your tenant requires it. Serval manages the Entra application configuration.
Teams form dialogs are available only to the ticket’s current requester. Team-private, deleted, and trashed tickets can’t be accessed through a Teams form dialog.

​
The form says “Sign in to continue”

The dialog shows one message for every sign-in failure, so the cause has to come from Microsoft rather than from the message. Open Entra → Monitoring → Sign-in logs, select the User sign-ins (non-interactive) tab, and filter by the affected person. The entry records Application as the Teams client and Resource as your app, so filtering on your app’s name in its enterprise-application blade returns nothing. Filter by user instead. The Failure reason on that row names the cause: A blank dialog with no message at all is a different failure: Teams refuses to load the page when the form hostname is missing from the manifest’s validDomains.

​
Okta and other Serval sign-in providers

Your existing Okta or other Serval SSO application continues to work and doesn’t need to change. Embedded forms authenticate through Microsoft Teams. Opening the form in a browser uses your normal Serval sign-in, including Require SSO and your identity provider’s policies. Those Serval browser sign-in checks don’t run inside the Teams dialog.

​
Configure existing helpdesk channels through the API

The connected-channel API and workflow pattern also supports Microsoft Teams. List the team’s channels, optionally filter by the Teams integration’s serviceInstanceId, and use the returned Serval connection id to set the mode. Teams supports DISABLED, FULL_ASSIST, ASSISTANT, TICKET_ONLY, and ON_DEMAND, each prefixed with CONNECTED_SERVICE_MODE_. Team only, team inbox, and redirect-to-DM modes are not supported and return a validation error. Disabled channels are included in listing, so setting CONNECTED_SERVICE_MODE_FULL_ASSIST activates an existing channel as Help desk (Always respond). The API does not install the bot or create channel connections.