Microsoft Graph

​

About Microsoft Graph

Microsoft Graph is a unified API that provides access to Microsoft 365 and Enterprise Mobility + Security (EMS) services. This integration uses OAuth 2.0 Client Credentials flow for server-to-server authentication, enabling workflows to access Microsoft Graph APIs without user interaction.

​

What the Microsoft Graph integration enables

Anything defined in the Microsoft Graph API can be accessed through Serval.

---

​

Serval Configuration

1. In Serval, navigate to Apps → Available → Microsoft Graph
2. Click Connect to bring up the “Connect” dialog.
3. Start the Azure steps below, and fill in the following information as you go:
   • Instance Name: Descriptive name for this integration
   • Tenant ID: Your Azure AD tenant ID (from Azure step 1)
   • Client ID: Your application client ID (from Azure step 1)
   • Client Secret: The secret value (from Azure step 2)
4. Once all fields are filled, click Connect to establish the integration
5. You should land on the application configuration page for your new Microsoft Graph integration. Click on the “API integration” tab
6. Click Run on the health checks to confirm permissions are set up properly.

Your Microsoft Graph integration is now ready to use in workflows! Continue reading to use Serval with Microsoft Teams.

---

​

Azure AD Configuration

​

1. Create App Registration

1. In a separate tab or window, go to the Azure Portal and sign in with admin privileges
2. In the app selector, navigate to Microsoft Entra with this link
3. Navigate to App registrations in the left sidebar
4. Click New registration
5. Configure the application:
   • Name: “Serval Microsoft Graph Integration” (or similar)
   • Supported account types: “Accounts in this organizational directory only”
   • Redirect URI: Leave blank
6. Click Register
7. Copy these values from the Overview page into the Serval “Connect” dialog:
   • Application (client) ID - This is your Client ID
   • Directory (tenant) ID - This is your Tenant ID

​

2. Create Client Secret

1. Navigate to Certificates & secrets → New client secret
2. Add description: “Serval Integration Secret”
3. Choose expiration period and click Add
4. ⚠️ Important: Copy the secret Value immediately - this is your Client Secret
5. Paste the secret into the Serval “Connect” dialog.
6. At this point, the Serval “Connect” dialog should be complete.

​

3. Configure API Permissions

1. Navigate to API permissions → Add a permission → Microsoft Graph → Application permissions
2. Add required scopes based on your needs. Common permissions include: Applications & App Catalog:
   • Application.Read.All - Read applications
   • Application.ReadWrite.All - Read and write applications
   • Application.ReadWrite.OwnedBy - Read and write applications owned by the current user
   • AppCatalog.Read.All - Read app catalog
   • AppCatalog.ReadWrite.All - Read and write app catalog
   Directory & Users:
   • Directory.Read.All - Read directory data
   • User.Read.All - Read user profiles
   • User.ReadWrite.All - Read and write user profiles
   • Group.Read.All - Read groups
   • Group.ReadWrite.All - Read and write groups
   Communication:
   • Mail.Read - Read mail in all mailboxes
   • Calendars.Read - Read calendars
   • Contacts.Read - Read contacts
   Files & Content:
   • Files.Read.All - Read files in all sites
   • Sites.Read.All - Read SharePoint items
   Teams:
   • Team.ReadBasic.All - Read team names/descriptions
   • TeamMember.Read.All - Read team members
   Device Management:
   • DeviceManagementManagedDevices.Read.All - Read managed devices
   Reports & Security:
   • Reports.Read.All - Read usage reports
   • SecurityEvents.Read.All - Read security events
   For write operations, use the corresponding .ReadWrite.All permissions. For Microsoft Teams, the following permissions are required:
   • ChannelMessage.Read.All - Allows the app to read all channel messages in Microsoft Teams
   • Directory.Read.All - Allows the app to read data in your organization’s directory, such as users, groups and apps.
   • Group.Read.All
   • Team.ReadBasic.All - Get a list of all teams.
   • Teamwork.Migrate.All
   • User.Read.All - Allows the app to read user profiles without a signed in user.
3. Grant admin consent: Click Grant admin consent for [Your Organization] → Yes.
4. Verify all permissions show Granted for [Your Organization]

Note: Granting admin consent requires certain permissions. The “Privileged Role Administrator” role should grant the minimum permissions needed. Note: The integration uses the https://graph.microsoft.com/.default scope, which grants access to all application permissions configured above. For detailed permission information, see the Microsoft Graph permissions reference.

---

​

Serval and Microsoft Teams

Serval can provide powerful help desk ticket automation in Microsoft Teams channels. Users can create messages in a help desk channel, and Serval will respond in thread using guidance and workflows you define. There are additional setup steps to use Serval with Microsoft Teams. You can use your existing Microsoft Graph integration with Teams; the following steps will assume you’ve already set up an integration using the steps earlier in this document.

​

1. Add permissions to your Serval application in Microsoft Entra

You need to add permissions to your Microsoft Entra application for Teams support.

1. Go to the Azure Portal and sign in with admin privileges
   • The administrator must have the following roles to complete the setup (or permissions within):
     • “Application Administrator”
     • “Privileged Role Administrator”
     • “Teams Administrator”
2. In the app selector, navigate to Microsoft Entra with this link
3. Navigate to App registrations in the left sidebar
4. Choose the Serval application you created earlier
5. Navigate to API permissions → Add a permission → Microsoft Graph → Application permissions
6. Add the following permissions:
   • ChannelMessage.Read.All - Allows the app to read all channel messages in Microsoft Teams
   • Directory.Read.All - Allows the app to read data in your organization’s directory, such as users, groups and apps.
   • Group.Read.All - Allow the app to read a list of groups in Entra
   • Team.ReadBasic.All - Get a list of all teams.
   • Teamwork.Migrate.All - Allow the app to manage Microsoft Teams. This allows Serval to forward messages.
   • User.Read.All - Allows the app to read user profiles without a signed in user.
7. Grant admin consent for these permissions.

​

2. Create an Azure Bot

You will need the application (client) ID and tenant ID of the application you created earlier.

1. Go to the Azure Portal and sign in with admin privileges
2. In the search box at the top of the screen, search for “Azure Bot”.
3. You should see an “Azure Bot” Marketplace result. Click on this result.
4. On the Azure Bot page, click “Create”.
5. On the Create an Azure Bot page, fill in the following fields:
   • Bot handle: must be globally unique, not shown to users. We recommend {yourcompanyname}servalbot.
   • Select or create a new Resource Group to hold the bot. If creating a new group, the name can be “Serval”.
   • Creation type: choose “Use existing app registration”
   • App ID: the application (client) id of the application you created earlier
   • App tenant ID: the tenant id of the application you created earlier
6. Click “Review and Create” and wait for the deployment to complete

​

3. Configure your new Azure Bot

1. In the sidebar, click Settings > “Configuration”, then fill in the following fields:
   • Messaging endpoint: https://svwebhook.api.serval.com/teams
   • Leave “Enable Streaming endpoint” unchecked
   • Click Apply
2. In the sidebar, click “Channels”
   • Under “Available Channels”, click the “Microsoft Teams” text
   • Agree to the terms of service
   • Choose “Microsoft Teams Commercial”, then click “Apply”

​

4. Create a new Teams app

Your Serval point of contact will provide you with a Teams app package (.zip file)

1. Go to the Microsoft Teams developer portal
2. Click “Import an app” and select the provided Serval Template.zip file.
3. In the sidebar, click “Basic information”
   • “Application (client) ID”: the application (client) ID of your Serval application in Microsoft Entra
   • Click save
4. In the sidebar, click “App Features”
   • Click “Bot”
   • “Enter a bot ID”: fill in the same application (client) ID as above
   • Click save
5. In the upper right corner, click “Publish”, then “Download the app package”. You’ll get a zip file specific to your org.

​

5. Upload your Teams app

1. Go to Microsoft Teams as a Teams admin.
2. In the Teams sidebar, click “Apps”
3. In the Apps sidebar, click “Manage your apps” at the bottom left
4. You’ll see a list of apps in your org. Click “Upload an app” at the top of the app list, then “Upload a custom app”.
5. Choose the zip file you just generated. You should see the App info for the Serval app.
6. Click “Add”
7. Choose a channel to start using Serval in. This selection isn’t important; you can @mention Serval in any channel.

​

6. Configure connected channels

1. In Teams, @mention Serval to make Serval aware of the help desk channel.
2. In Serval, navigate to your Microsoft Graph integration. You should see the channel appear in the Help Desk page in a disabled mode.
3. Choose the way you want Serval to behave.

​

Recommended: Start with Silent Mode

When first setting up your Teams help desk, we recommend enabling Silent Mode:

• This allows you to test the integration without immediately notifying users
• You can observe how tickets are created and routed
• Once comfortable, switch to Help Desk Mode to fully activate Serval in the channel

​

Connect Additional Channels

You can connect more channels by mentioning Serval.

​

Channel Configuration Modes

When you connect a Teams channel to Serval, you can configure it to operate in different modes depending on your needs:

​

Disabled Mode (Default)

Serval will do nothing

• Serval will not create tickets from messages
• Serval will not respond to any messages in the channel
• This allows you to safely add Serval to a channel before activating any features

​

Silent Mode

Serval monitors the channel but operates quietly

• Creates tickets based on messages in the channel
• Does not post responses or acknowledgments in the channel
• Ideal for testing or when you want ticket creation without channel noise
• If you @Serval when making a request or at any point in a message thread, Serval will be toggled on and attempt to help resolve the ticket.

​

Help Desk Mode

Full help desk functionality

• Creates tickets from channel messages
• Responds with a link to the created ticket
• Attempts to resolve tickets using AI guidance and help desk workflows
• Provides the complete support experience for end users

Team Only and Team Inbox modes are in development for Microsoft Teams.