Microsoft Teams - Serval Documentation

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. For commercial Microsoft 365, API requests from Serval workflows can reach Microsoft’s graph.microsoft.com, smba.trafficmanager.net, and pilot1.botapi.skype.com 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 choose a mode from the supported Channel Types.
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	In a personal chat, select `create-ticket` from the command menu or type `/create-ticket` to create a 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 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

Serval's Teams app (default)
Custom Application

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.

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.

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.

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

Run the Serval bot as an application your organization registers and controls. This is an advanced setup involving three separate Microsoft resources in your tenant:

An Entra ID app registration that holds the client ID, client secret, and Microsoft Graph permissions Serval uses.
An Azure Bot resource that tells Microsoft where to deliver inbound Teams messages. The Teams app manifest does not contain a webhook URL - routing from Teams to Serval is configured here.
A Teams app package that you author and upload so the bot can be installed in Teams. Serval does not generate a package for a custom application - the app is yours, so the package is too.

Use Entra admin center for credentials, Azure portal for the bot, Teams Developer Portal to create the app package, and Teams Admin Center to distribute it.You’ll need access to Entra and an Azure subscription, plus administrators who can grant consent and upload Teams apps. Prepare your app name, icons, website, privacy policy, and terms-of-use URLs.

Go to Microsoft Entra ID → App registrations and click New registration. Configure: Name e.g. “Serval - Teams”; Supported account types: Accounts in this organizational directory only (Single tenant) - this must later match the Azure Bot’s Type of App. Leave the Redirect URI blank: Serval connects to a custom application with client credentials only, so there is no OAuth redirect.From the app’s Overview page, copy the Application (client) ID and Directory (tenant) ID - you’ll paste both into Serval’s connect form.

Add Microsoft Graph application permissions

From the app’s API permissions page, click Add a permission → Microsoft Graph → Application permissions, and add:

Channel.ReadBasic.All - resolve channel names and IDs when posting to channels
Organization.Read.All - read tenant metadata during setup and health checks
Team.ReadBasic.All - list teams and read team internal IDs for channel resolution
TeamsAppInstallation.ReadWriteAndConsentSelfForChat.All - let the Teams app install itself into chats and manage its own permission grants
TeamsAppInstallation.ReadWriteAndConsentSelfForTeam.All - let the Teams app install itself into teams and manage its own permission grants
TeamsAppInstallation.ReadWriteAndConsentSelfForUser.All - let the Teams app install itself for a user (personal scope) and manage its own permission grants
User.Read.All - resolve user directory info for mentions, DMs, and ticket assignment

Then click Grant admin consent for [Your Organization] and verify every permission shows Granted with a green check. Serval’s connect-time verification fails without admin consent.

Create a client secret

Navigate to Certificates & secrets, click New client secret, choose an expiration, and click Add. Immediately copy the secret Value - this is the “Client secret value” field in Serval.

Copy the secret Value, not the Secret ID. The value is only visible immediately after creation - if you navigate away, you’ll need to create a new secret.

Configure Microsoft Entra sign-in

Open App registrations → your app.

Open Manifest. In the existing api object, set "requestedAccessTokenVersion": 2 (add the property if missing), then click Save.
Open Expose an API → Application ID URI → Add (or Edit). For Serval cloud, enter api://msteams.serval.com/botid-<CLIENT_ID>, replacing <CLIENT_ID> with this registration’s Application (client) ID. Click Save. For self-hosted installations, use your configured Teams page hostname instead of msteams.serval.com; the Microsoft Entra Sign-In health check reports the expected URI.
Click Add a scope. Set Scope name to access_as_user, Who can consent to Admins only, and State to Enabled. Enter an admin consent display name such as Access the support app as the signed-in user and a description explaining that Teams uses it to sign the user into the app. Click Add scope.
Under Authorized client applications, click Add a client application. Add each Microsoft client ID below separately, select the access_as_user scope checkbox, and click Add application.
Open Token configuration → Add optional claim → Access. Select acct and click Add.

Microsoft client	Client ID to authorize
Teams desktop and mobile	`1fec8e78-bce4-4aaf-ab1b-5451cc387264`
Teams web	`5e3ce6c0-2b1f-4285-8d4b-75ee78787346`

These are Microsoft’s public Teams client IDs, shared across customers. Use them exactly as shown.

Edit token settings in Entra → Manifest. The Teams package’s manifest.json is a separate file.

Create the Azure Bot resource

In the Azure portal, go to Create a resource, search for Azure Bot, and click Create. Fill in:

Bot handle: any unique name, e.g. serval-teams-bot
Subscription / Resource group: any subscription where you have Contributor - the Azure Bot doesn’t need to live near anything else
Pricing tier: Free (F0) is sufficient
Type of App: Single Tenant - must match the Supported account types you chose for the Entra app. This field is fixed at creation time and can’t be changed later.
Creation type: Use existing app registration
App ID: the Application (client) ID from the Entra app’s Overview page
App tenant ID: the Directory (tenant) ID from the Entra app’s Overview page

Point the messaging endpoint at Serval

On the new Azure Bot → Settings → Configuration, set Messaging endpoint to the endpoint for the deployment that hosts your organization:

Deployment	Messaging endpoint
United States (US1)	`https://svwebhook.us1.serval.com/teams`
European Union (EU1)	`https://svwebhook.eu1.serval.com/teams`
Self-hosted	`https://svwebhook.<regional-domain>/teams`, with your deployment’s configured regional domain - see Redirect and webhook URL shapes

Use your Serval hosting region, regardless of employees’ locations. Enter one endpoint and click Apply.Open Settings → Channels, select Microsoft Teams, accept the terms, and click Apply.

Create the Teams app in Developer Portal

Developer Portal generates manifest.json, the Teams app’s configuration file. The downloaded ZIP contains this file and two icons.

Open Teams Developer Portal, select Apps → New app, enter your app name, and click Create.
Open Configure → Basic information and complete the fields below. Click Save.

Field	What to enter
Short name	The assistant name employees see.
Short description / Long description	What your support app does.
App ID	Keep the Teams app ID generated by the portal. It is separate from the Entra client ID.
Version	Start with `1.0.0`. Increase it when uploading an update.
Developer/company name	Your organization.
Website	Your company or app-information URL.
Privacy policy / Terms of use	Your organization’s policy URLs, accessible to your users.
Application (client) ID	Copy Entra → App registrations → your app → Overview → Application (client) ID.

Open Configure → Branding. Upload a 192 × 192 PNG color icon and a 32 × 32 PNG outline icon (white artwork, transparent background). See icon requirements.
Open Configure → App features → Bot. Choose Enter a bot ID and paste the same Entra client ID. Leave Only send notification unchecked so users can converse with the bot. Select Personal for DMs, Team for channels, and Group chat for group chats, then click Save.
Open Configure → Permissions. Add these Application permissions from the Team and Chat/Meeting categories:

Scope	Application permissions
Chat	`ChatMember.Read.Chat`, `ChatMessage.Read.Chat`, `TeamsActivity.Send.Chat`
Team	`ChannelMember.Read.Group`, `ChannelMessage.Read.Group`, `ChannelMessage.Send.Group`, `ChannelSettings.Read.Group`, `TeamMember.Read.Group`, `TeamsActivity.Send.Group`

See Microsoft’s Developer Portal guide for the portal’s configuration sections.

Check the Teams manifest and download the ZIP

Open Configure → App package editor → manifest.json. Use the file’s Actions (…) → Edit control if it opens read-only.
Find each field using the locations below. Keep the generated app ID; update the other values as needed.

Where to look	Field	Value
Near the start of the file, beside `manifestVersion`	`id`	Keep the generated Teams app ID.
Inside `bots`	`botId`	Your Entra Application (client) ID.
Inside `bots`	`scopes`	`personal` for DMs, `team` for channels, and `groupChat` for group chats.
Inside `bots`	`isNotificationOnly`	`false`.
Inside `webApplicationInfo`	`id`	Your Entra Application (client) ID.
Inside `webApplicationInfo`	`resource`	Your Application ID URI from Entra → Expose an API.
Inside `authorization`, then `permissions`	`resourceSpecific`	The nine permissions listed above, each with `"type": "Application"`.

If manifestVersion is 1.25 or later and scopes includes team, add the following line immediately after the manifestVersion line, at the same indentation. If supportsChannelFeatures already exists, set its value to "tier1" instead. Keep a comma between settings.

"supportsChannelFeatures": "tier1",

Find webApplicationInfo and update its id and resource as shown below. If the section is missing, insert this block immediately after the manifestVersion line, at the same indentation, outside bots. Replace the placeholders with your Entra client ID and Application ID URI.

"webApplicationInfo": {
  "id": "<CLIENT_ID>",
  "resource": "<APPLICATION_ID_URI>"
},

Save the file and apply Update if prompted. Open Publish → App validation and resolve package errors.
Open Publish → Publish to store → Download app package. Download a new ZIP after each edit.

The ZIP must contain manifest.json and both PNGs at its root. For manual packaging, see Microsoft’s requirements.

Upload the app to your organization's catalog

Saving or downloading in Developer Portal doesn’t upload the app to Teams.

Open Teams Admin Center.
In the left navigation, expand Teams apps → Manage apps.
At the top of the page, select Actions → Upload new app → Upload. Some versions show Upload new app directly.
Select the exported ZIP and complete the upload.
Search for your app in the Manage apps table. Confirm its name, publisher, and published version.

If upload fails, fix the reported package error in Developer Portal, export a fresh ZIP, and upload that file. An error requiring supportsChannelFeatures is a manifest error; waiting for propagation won’t fix it.

Set availability and install for your pilot

Set both availability (who can use the app) and installation (where it’s added).

In Teams apps → Manage apps, select your app’s row and open Edit availability. Choose your pilot users or group and save. Confirm Available to includes your testers and App status is Unblocked.
For DMs, install the app for those users through Edit installs, a Teams Setup Policy, or have each tester open Teams → Apps → Built for your org → your app → Add.
For channels, select the app’s row in Admin Center, click Add to team, search for the target team, and complete the add. Alternatively, use Add to a team from the app’s details in Teams.
In the Teams client, find the target team, open … → Manage team → Apps, and confirm your app is listed. Get more apps opens the app catalog; it isn’t the installed-app list.
If using group chats, add the app to each intended chat as well.

If the app is already added, check availability and Manage team → Apps before retrying.Microsoft policy and availability changes aren’t immediate and can take up to 24 hours, or longer in some cases. Test in Teams web with the same account and organization while the desktop client catches up. Making the app available to everyone doesn’t bypass propagation.

Three things on the Azure Bot must match the Entra app exactly, or Teams rejects inbound message delivery with a 401: the App ID must equal the Entra Application (client) ID (the same value as the botId field inside bots in your manifest), the App tenant ID must equal the Entra Directory (tenant) ID, and the Type of App must match the Entra app’s Supported account types (both Single Tenant, or both Multi Tenant).

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

Serval's Teams app (default)
Custom Application

Start the connection

In the connect dialog, choose Connect Serval’s Teams app. There is no form to fill in for this option.

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

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.

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 → Actions → Upload new app 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.

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.

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. See Channel Types for the behavior and availability of each mode.

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.

Choose Custom Application in the connect dialog and fill in the form. All four fields are required.

Instance Name

A descriptive name for this connection. Free text; placeholder “e.g., My Microsoft Teams”. This name also identifies the directory in error messages.

Directory (tenant) ID

The ID of your Microsoft directory. In Microsoft Entra admin center → App registrations → your app → Overview, copy Directory (tenant) ID. Don’t use an Object ID or a domain name. A value that isn’t a GUID is rejected before anything is saved:

Directory (tenant) ID must be a GUID, like 00000000-0000-0000-0000-000000000000. Copy it from your app registration’s Overview page in the Azure portal.

Application (client) ID

In the same Overview page, copy Application (client) ID. This identifies your bot’s Entra application and matches the botId field inside bots in your Teams package; it isn’t the portal-generated Teams app ID. Non-GUID values are rejected:

Application (client) ID must be a GUID, like 00000000-0000-0000-0000-000000000000. Copy it from your app registration’s Overview page in the Azure portal.

Client secret value

A password field; placeholder “Value from App registration, Certificates and secrets”. Paste the secret Value, not the Secret ID. Leaving it empty is rejected:

Client secret is required. Create one under Certificates & secrets in your app registration in the Azure portal.

What connecting verifies - and what it can’t. Before saving anything, Serval verifies the credentials end-to-end: it uses your tenant ID, client ID, and secret to request an app-only token for the Bot Framework API and another for Microsoft Graph - the two audiences Serval mints at run time. A mistyped ID, a bad secret, or missing admin consent fails at connect time with one of the errors in Custom application errors, and nothing is saved.What the probe cannot see is the Microsoft-side bot wiring: the Azure Bot resource, its messaging endpoint, its Teams channel, and your app package upload and installation. “Connected” therefore means credentials verified - if you haven’t finished the Azure Bot and app package steps under Get your credentials, finish them now, then @mention the bot in a channel to connect it, exactly as in the last step of the default flow.

Editing later: a Custom Application connection shows its credentials form on the integration’s settings page (in place of the managed flow’s Reconnect + package download). The stored client secret is shown obfuscated when you reopen the form; on update, leaving any field blank keeps its existing value - only fill in what you want to change. Every save re-runs the connect-time verification against the merged values.

Verifying the connection

Open the connection’s API Integration tab, find Health Checks, and click Run (4). Expand each result to read its details. The Microsoft Teams integration runs four 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.”

Microsoft Entra Sign-In checks user sign-in is enabled on the enterprise application and that the delegated access_as_user scope is enabled. For a custom application, it also checks the Application ID URI, access token version 2, both authorized Teams clients, and the acct access-token claim. For disabled user sign-in, open Entra → Enterprise applications → your app → Properties and enable user sign-in. Correct the custom registration settings under App registrations → your app using the sign-in setup above, then run the check again. If the result says user assignment is required, also check the tester is assigned under the enterprise application’s Users and groups. After the checks pass, test messages and ticket creation using the steps below. Channel Resolution tests only one team; check the target team separately if its channels are missing.

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

Verify the custom app from installation to response

Use a pilot account included in the app’s availability settings.

Find the uploaded app. Open Teams Admin Center → Teams apps → Manage apps and search for your app. If absent, return to the upload step. If present, confirm Unblocked and that Available to includes the tester, then continue to step 2.
Check the team installation. In Teams, open the intended team’s … → Manage team → Apps. If the app is missing, use Add to team in Admin Center. If it is listed, skip to step 3. If Admin Center reports it is already added but the client disagrees, test Teams web using the same account and tenant, then refresh or restart the desktop client.
Check the Serval connection. Open Integrations → Microsoft Teams → your connection → API Integration → Health Checks and run all four checks. If one fails, follow its expanded error and rerun it. If they pass, continue to step 4.
Test a direct message. Enable Direct Messages on the connection’s Help Desk tab where that control is available. Then add the app for your own account in Teams, open its chat, and send a fresh, specific support request. If it replies, continue to step 5. If it doesn’t, follow Custom app: connected in Serval, but the bot never receives messages below.
Test a channel mention. Open a standard channel in the installed team: a channel accessible to all team members, rather than a private or shared channel. Start a post, type @ and your app’s name, select the bot from the suggestions, and send a support request. If the bot isn’t in the suggestions, return to steps 1–2.
Enable the channel in Serval. On the connection’s Help Desk tab, find the channel under Connected Channels and select the intended channel mode. A newly discovered channel starts disabled. Send a fresh test message after enabling it.
Verify the result. Check both the bot’s response and the resulting ticket in the intended Serval workspace. Personal chats display replies in the chat; channel replies belong to the channel conversation.

If the target channel never appears or channel discovery repeatedly fails, expand Channel Resolution to see which team it actually tested. Verify Team.ReadBasic.All and Channel.ReadBasic.All have admin consent on the same Entra application used by this connection. If they do, collect the target team/channel link, the failure time, and the exact error for Serval support.

Gotchas and troubleshooting

Where to view descriptions and update the custom package

In Teams, open Apps, search for your app, and open its details to see the published description. Use a plain URL for links in the description and check how it appears in Teams.To update the custom app, edit it in Developer Portal, increase the app package Version, validate, and download a fresh ZIP. In Teams Admin Center → Teams apps → Manage apps → your app, use New version → Upload file. Keep the existing app identity when updating.

Uploaded the package, but @mentioning Serval in a channel finds nothing

Check Teams Admin Center → Teams apps → Manage apps first. Confirm the app is unblocked, available to the testing user, and added to the target team.If those are correct, compare Teams web and desktop using the same account and organization. Availability changes can take up to 24 hours, or longer in some cases. A working web client lets you continue testing while the desktop client refreshes. Keep the pilot scoped; enabling everyone doesn’t make propagation faster.Follow Verify the custom app from installation to response for the ordered checks.

Custom app: connected in Serval, but the bot never receives messages

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:

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.
Teams channel. On the Azure Bot → Settings → Channels, Microsoft Teams must show a healthy status in the Channels list.
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.
App package installed. The botId field inside the manifest’s bots section 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.

Custom app: sends fail with an 'is not installed' error

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.

Switching between Serval's Teams app and a custom application

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.

Channel mapping breaks silently without Team.ReadBasic.All / Channel.ReadBasic.All

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.

Catalog queries need AppCatalog.Read.All

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

The app package is environment- and install-specific - don't reuse a ZIP across orgs

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.

Setup Policies require an Admin Center upload

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.

Channel messages need a copied Teams link, and private channels are not supported

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

Cross-tenant / external group chats can't be auto-installed

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.

Separate from the Microsoft Graph integration

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.

Serval's Teams app has no credential fields - and a custom app has no package download

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.

Message size limits are not pre-validated

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.

Serval reports	Cause and fix
”Instance name is required. Enter a name that identifies this connection, such as your organization’s name.”	The Instance Name field was left empty.
”Directory (tenant) ID must be a GUID, like 00000000-0000-0000-0000-000000000000. Copy it from your app registration’s Overview page in the Azure portal.”	The tenant ID isn’t a GUID - you may have pasted a domain name or a label.
”Application (client) ID must be a GUID, like 00000000-0000-0000-0000-000000000000. Copy it from your app registration’s Overview page in the Azure portal.”	The client ID isn’t a GUID.
”Client secret is required. Create one under Certificates & secrets in your app registration in the Azure portal.”	The secret field was left empty on a new connection.
”Your app registration was not found in the directory ‘[name]’. Verify the application (client) ID on this connection matches an app registration in that directory.”	Microsoft answered AADSTS700016: the client ID doesn’t exist in that tenant - wrong client ID, or wrong tenant ID.
”The client secret for your app registration is invalid or expired. Create a new client secret in the Azure portal and update this connection.”	Microsoft answered AADSTS7000215. Create a new secret under Certificates & secrets, copy its Value, and update the connection.
”Admin consent has not been granted for your app registration. An administrator must grant admin consent to your app registration in the Azure portal.”	Microsoft answered AADSTS65001. Open the app registration’s API permissions page and click Grant admin consent.
”Your app registration is not authorized for tenant ‘[name]’. Verify the app registration exists in that tenant and has admin consent granted.”	Microsoft answered `unauthorized_client` - usually a single-tenant app addressed through the wrong tenant, or missing consent.
”Failed to authenticate with Microsoft Teams for tenant ‘[name]’. Please try reconnecting the integration.”	Any other authentication failure; the original Microsoft error detail follows the message.
”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.”	A workflow direct message reached a user who doesn’t have your app. Serval never installs a custom app - pre-install it via an app setup policy or have the user add it.
”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.”	A workflow channel message targeted a team without your app. Add the app to that team.
”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.”	A workflow group chat message targeted a chat without your app. Add the app to the chat.
”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.”	Not an error: the Bot App Catalog Presence health check reporting that catalog presence isn’t a health signal for an app Serval doesn’t manage.

Need help? Contact support@serval.com for assistance with your Microsoft Teams integration.

Configure existing helpdesk channels through the API

The connected-channel API and workflow pattern also supports Microsoft Teams. List the Serval workspace’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_. Workspace only, workspace 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.

​About Microsoft Teams

​What the Microsoft Teams integration enables

​Get your credentials

​Connect in Serval

​Verifying the connection

​Verify the custom app from installation to response

​Gotchas and troubleshooting

​Custom application errors

​Configure existing helpdesk channels through the API

About Microsoft Teams

What the Microsoft Teams integration enables

Get your credentials

Connect in Serval

Verifying the connection

Verify the custom app from installation to response

Gotchas and troubleshooting

Custom application errors

Configure existing helpdesk channels through the API