How to set up Microsoft Teams in Skyone Studio

Esta documentação descreve o processo completo para configurar a integração do Microsoft Teams no Skyone Studio. O objetivo é permitir que agentes inteligentes criados no Skyone Studio se comuniquem diretamente com usuários através de chats e canais no no ambiente Microsoft (Azure e Teams).

This documentation describes the complete process for configuring the Microsoft Teams integration in Skyone Studio. The goal is to allow intelligent agents created in Skyone Studio to communicate directly with users through chats and channels within the Microsoft environment (Azure and Teams).

Benefits:

• Centralizes communication with AI agents within the Teams corporate environment.

• Allows for proactive messaging and response automation.

• Ensures secure integration using Microsoft authentication protocols.

Prerequisites and Permissions

1. Administrative and System Permissions

• Administrative permissions in Azure.

• Microsoft Teams Administrator profile.

• AI Admin permission no Azure (to manage Resource Groups).

• Azure Bot Service Contributor Role (mandatory for Bot creation).

• Access to Bot Framework / Bot Service / Azure Bot.

2. Microsoft Graph Permissions (Configured in Azure):

During the application registration in Azure, you must provide the following permissions:

• AppCatalog.ReadWrite.All: Allows publishing the bot to the Microsoft Teams app catalog.

• TeamsAppInstallation.ReadWriteSelfForUser.All: Allows the installation of the bot for specific users.

• Chat.ReadWrite.All: Ensures the bot can send and receive proactive messages in chats and channels.

• User.Read.All: Allows reading profile information and bot usage logs.

3. Settings in Teams Admin Center:

It is necessary to allow the upload of custom apps (sideloading) by following this path:

• Access Teams Admin Center → Teams apps → Setup policies.

• Enable the Upload custom apps option.

• Ensure the Apps menu is visible by enabling the Show app bar option.

Important Notes:

• Accounts: You must use a corporate account with a .com.br domain. Custom domains or personal accounts are not accepted and may prevent bot validation.

• Azure Providers: The Microsoft.BotService resource provider must be enabled in the Azure subscription used to avoid failures in bot creation. deve estar habilitado na assinatura Azure utilizada para evitar falhas na criação do bot.

---

Configuration Steps

To configure Microsoft Teams, you will need to switch between the Azure Portal, the Teams Admin Center, and Skyone Studio.

Steps:

• [Step 01] Register the application in Azure: Register the new application and generate credentials.

• [Step 02] Configure the Application: Configure and generate data for the next steps.

• [Step 03] Create an Agent Flow: Create an agent flow to interact with the bot.

• [Step 04] Create the publication in Studio: Create a new Microsoft Teams publication in Studio.

• [Step 05] Configure the Webhook URL in Azure: Set the Webhook URL in the authentication flow.

• [Step 06] Configure API permissions: Define the Microsoft Graph access scopes.

• [Step 07] Create the Azure Bot: Establish the bot service resource in Azure.

• [Step 08] Configure the Azure Bot: Link the bot to the Studio messaging URL.

• [Step 09] Enable the Microsoft Teams channel: Activate Teams-specific communication.

• [Step 10] Prepare the Manifest: Create the app installation package.

• [Step 11] Upload: Publish the bot to the organizational environment.

• [Step 12] Validate the integration: Test the final communication between endpoints.

---

Step 01: Register the application in Azure

1. Access the Azure Portal and go to App Registrations > New Registration.

2. In the Name field, enter an identification (e.g., Microsoft_Teams_Integration).

3. Under Supported account types, select Accounts in this organizational directory only (Single Tenant).

4. Click Register.

Step 02: Configure the Application

1. Still in the Azure Portal, go to App Registrations > Owned Applications.

2. Go to Certificates & Secrets > New client secret.

3. Define a description and the expiration time (maximum 6 months).

Important: Copy the Secret Value immediately, as it will be displayed only once and will be required in Skyone Studio.

Copy and save the Application (client) ID and the Directory (tenant) ID; we will use them in the next step.

Step 03: Create an Agent Flow

1. Access Skyone Studio and go to Agent Flow.

2. Click Create flow.

3. Add components as needed, ensuring an agent is configured in the

Step 04: Create a Microsoft Teams publication in Studio

1. Access Skyone Studio and go to Agent Flow.

2. Click Publish in the upper right corner.

3. Click Microsoft Teams.

4. Select a previously created Agent Flow.

5. Click Manage Accounts.

6. Click Create Account.

7. Enter the following data:

   1. Name: Account name

   2. Client ID: Application (client) ID

   3. Client Secret: Secret generated in Step 2

   4. Tenant ID: Directory (tenant) ID

8. Click Create.

9. Click Save Publication.

10. Copy and save the generated Webhook URL.

Step 05: Configure the Webhook URL in Azure

1. In the Azure Portal, go to App Registrations > Owned Applications.

2. Acesse Manage → Authentication (Preview).

3. Add the redirect URI:

   1. Platform Web

   2. Paste the Webhook URL collected from Skyone Studio

Step 06: Configure API permissions

1. In the side menu of the created application, access API Permissions > Add a permission.

2. Select Microsoft Graph and add the following application permissions:

   • AppCatalog.ReadWrite.All.

   • Chat.ReadWrite.All.

   • TeamsAppInstallation.ReadWriteSelfForUser.All.

   • User.Read.All.

3. Click Grant admin consent to activate permissions or wait for administrator approval.

Step 07: Create the Azure Bot

1. In the Portal Azure, access Bot Services

2. Click Create and then Azure Bot.

3. Fill in the fields according to the table below:

• Bot handle: Ex.: teams-integration-bot.

• Data residency: Global.

• Pricing: Standard.

• Microsoft App ID: Single Tenant.

• Creation type: Use existing app registration.

• App ID: The Application (client) ID from Step 02.

• App tenant ID: The Directory (tenant) ID from Step 02.

4. Click Create to finish.

Step 08: Configure the Azure Bot

1. Access the created bot.

2. Access Configuration.

3. n the Messaging endpoint field, paste the Webhook URL generated in Skyone Studio (Step 04).

4. Click Save.

Step 09: Enable the Microsoft Teams channel

To enable the bot specifically for Teams:

1. Go to Channels.

2. Under Messaging, choose Microsoft Teams Commercial

3. Click Apply.

Step 10: Prepare the Manifest

Sideloading allows you to test the bot internally before its official release to the entire organization.

• Sideload = local/individual test

• Catalog Publication = official/organizational test

1. Create a file named manifest.json using the Microsoft standard template, inserting your Client ID in the id e botId fields.

{
  "$schema": "https://developer.microsoft.com/en-us/json-schemas/teams/v1.17/MicrosoftTeams.schema.json",
  "manifestVersion": "1.17",
  "version": "1.0.1",
  "id": [Application ID (client)],
  "developer": {
    "name": "[Company name]",
    "websiteUrl": "[Website URL]",
    "privacyUrl": "[Privacy URL]",
    "termsOfUseUrl": "[Terms of Use URL]"
  },
  "name": {
    "short": "[Bot name - short]",
    "full": "[Bot name - full]"
  },
  "description": {
    "short": "[Description - Short]",
    "full": "[Description - Full]"
  },
  "icons": {
    "outline": "outline.jpg",
    "color": "color.jpg"
  },
  "accentColor": "#FFFFFF",
  "bots": [
    {
      "botId": "[APP ID (client)]",
      "scopes": ["personal", "team", "groupChat"],
      "supportsFiles": true,
      "isNotificationOnly": false
    }
  ],
  "composeExtensions": [],
  "permissions": [
    "identity",
    "messageTeamMembers"
  ],
  "validDomains": [
    "[Studio domain URL]"
  ]
}

Every upload requires a version increment.

The manifest.json file defines how the application will be displayed in Microsoft Teams and what permissions it will use.

1. Prepare two icon images: color.png ($192\times192$ px) and outline.png ($32\times32$ px).

2. Select the three files (manifest.json, color.png e outline.png) and compress them into a .zip.

Compress the files directly, not the folder where they are located, to avoid read errors.

Step 11: Upload

1. As an admin, access the Microsoft Teams Admin Center.

2. Go to Teams apps > Setup policies

3. Select Global (Org-wide Default).

4. Enable Upload custom apps.

Without this activation, it will not be possible to load external applications in the environment.

1. Log in to Microsoft Teams (Web ou Desktop) using your Azure user account that has an active license.

2. Click the Applications icon, located in the left sidebar menu.

3. Select the Manage Your Applications option.

4. Click Upload an Application and then Upload a Custom Application.

5. Select the previously created .zip file (containing the manifest.json and images).

6. Confirm the information displayed on the home screen and click Add.

Step 12: Validate the integration

1. Open the chat with the bot and send a message like "Hello".

2. Please confirm that the message was correctly received by the flow configured in Skyone Studio via the registered webhook.

Receiving the response confirms that the integration between Microsoft Teams and Skyone Studio was completed successfully.

---

FAQ - Microsoft Teams Integrations

Can I use a personal account to set up Teams?

No. You need to use a corporate account with a domain (e.g., .com.br) linked to the organizational environment.

Why did my custom app upload fail?

Check if the "Upload custom apps" option is enabled in the Teams Admin Center under Setup policies. Also, make sure you only compressed the files, not the folder.

What to do if the bot doesn't respond in Teams?

Check if the Webhook URL generated in Skyone Studio was pasted correctly into the Messaging endpoint field of the Azure Bot. Also, check if the API permissions in Azure have received administrator consent.