diff --git a/integrations/integration-guides/assets/microsoft-teams-admin-center.png b/integrations/integration-guides/assets/microsoft-teams-admin-center.png deleted file mode 100644 index cd5af35..0000000 Binary files a/integrations/integration-guides/assets/microsoft-teams-admin-center.png and /dev/null differ diff --git a/integrations/integration-guides/assets/microsoft-teams-app-features.png b/integrations/integration-guides/assets/microsoft-teams-app-features.png deleted file mode 100644 index 54dc122..0000000 Binary files a/integrations/integration-guides/assets/microsoft-teams-app-features.png and /dev/null differ diff --git a/integrations/integration-guides/assets/microsoft-teams-app-info.png b/integrations/integration-guides/assets/microsoft-teams-app-info.png deleted file mode 100644 index 629947c..0000000 Binary files a/integrations/integration-guides/assets/microsoft-teams-app-info.png and /dev/null differ diff --git a/integrations/integration-guides/assets/microsoft-teams-apps.png b/integrations/integration-guides/assets/microsoft-teams-apps.png deleted file mode 100644 index 36aec18..0000000 Binary files a/integrations/integration-guides/assets/microsoft-teams-apps.png and /dev/null differ diff --git a/integrations/integration-guides/assets/microsoft-teams-botpress-app.png b/integrations/integration-guides/assets/microsoft-teams-botpress-app.png deleted file mode 100644 index 22af761..0000000 Binary files a/integrations/integration-guides/assets/microsoft-teams-botpress-app.png and /dev/null differ diff --git a/integrations/integration-guides/assets/microsoft-teams-dev-portal.png b/integrations/integration-guides/assets/microsoft-teams-dev-portal.png deleted file mode 100644 index 3a5291a..0000000 Binary files a/integrations/integration-guides/assets/microsoft-teams-dev-portal.png and /dev/null differ diff --git a/integrations/integration-guides/assets/microsoft-teams-publish.png b/integrations/integration-guides/assets/microsoft-teams-publish.png deleted file mode 100644 index e59a4ca..0000000 Binary files a/integrations/integration-guides/assets/microsoft-teams-publish.png and /dev/null differ diff --git a/integrations/integration-guides/assets/microsoft-teams-scopes.png b/integrations/integration-guides/assets/microsoft-teams-scopes.png deleted file mode 100644 index 4fd6b3a..0000000 Binary files a/integrations/integration-guides/assets/microsoft-teams-scopes.png and /dev/null differ diff --git a/integrations/integration-guides/assets/microsoft-teams.png b/integrations/integration-guides/assets/microsoft-teams.png deleted file mode 100644 index bea4fd2..0000000 Binary files a/integrations/integration-guides/assets/microsoft-teams.png and /dev/null differ diff --git a/integrations/integration-guides/teams.mdx b/integrations/integration-guides/teams.mdx index b439fbd..558b284 100644 --- a/integrations/integration-guides/teams.mdx +++ b/integrations/integration-guides/teams.mdx @@ -1,5 +1,6 @@ --- title: Microsoft Teams +description: Add your bot to Teams using the official integration. icon: '/integrations/integration-guides/assets/icons/teams.svg' --- @@ -13,116 +14,236 @@ import Cards from '/snippets/integrations/cards/botpress/teams.mdx' +The Microsoft Teams integration allows your bot to chat with members of your Teams workspace. +## Setup - - -## Prerequisites - -* A [Microsoft 365 Business account](https://www.microsoft.com/en-us/microsoft-365/business/) -* A [Botpress Cloud account](https://sso.botpress.cloud) and a [Botpress bot](/learn/get-started/quick-start) - -## Setup in Botpress - -1. Go to the [Integration Hub](https://app.botpress.cloud/hub) in Botpress Cloud (if you don't have the integration installed yet). -2. Find and open the Microsoft Teams integration then click on the "Install to Bot" button, now go back to your bot settings. - -The Microsoft Teams integration has the following settings: - -* **Enabled**: Whether Botpress will communicate with Microsoft Teams -* **Webhook URL**: The URL for receiving data in Botpress. -* **App ID**: The App ID of your bot in Azure -* **App Password**: The App Secret of your bot in Azure - -## Setup in Microsoft Teams - -### Register App - -1. In the Azure portal, open the [App registrations](https://portal.azure.com#blade/Microsoft_AAD_RegisteredApps/ApplicationsListBlade) page -2. Click **New registration**, then choose a name for your application -3. In the section **Supported account types**, choose the type that's most appropriate for your use case. We support Single and Multi Tenant accounts. Check out [this article](https://learn.microsoft.com/en-us/security/zero-trust/develop/identity-supported-account-types) to learn more (in short, Single Tenant means the app will be available for your org only, and Multi Tenant will make it public). After selecting, click **Register** -4. Copy/paste the value of `Application (client) ID` to the **App ID** channel configuration in Botpress - -### App Password - -5. Find the **Certificates & secrets** page in the sidebar, click **New client secret**, then fill in the required fields -6. Copy the value from the **Value** column and paste it in the **App Secret** channel configuration in Botpress -7. Save the settings by clicking the "Save configuration" button - -### Create Your Microsoft Bot - -1. Navigate to the [Bot Framework Creation page](https://dev.botframework.com/bots/new) -2. Fill the **Display name** and **Bot handle** fields with whatever value -3. Copy/paste your app ID to the **App ID** field -4. Copy the Webhook URL provided in Botpress to the **Messaging endpoint** field -5. Choose a tenant for the **App type**. Follow the same type you chose in the **Register App** section -6. Paste the App ID from the Azure bot in the **Microsoft App ID** field -7. Read and agree to the terms then click **Register** -8. On the next page (**Connect to channels**), under the section, **Add a featured channel**, click **Configure Microsoft Teams Channel**, then click **Save** - -### Accessing the Bot in MS Teams + + You will need: -1. Navigate to the [My Bots page](https://dev.botframework.com/bots/) -2. Click on your bot's name -3. Under the **Connect to channels** section, click on **Microsoft Teams** -4. The bot should open in your MS Teams + - A [published bot](/learn/get-started/quick-start) + - A [Microsoft 365](https://www.office.com/) business account + - A [Microsoft Azure](https://azure.microsoft.com/en-ca) account that uses the same email address as your Microsoft 365 account + -That's it, you may now start chatting with your bot on Microsoft Teams! +### Step 1: Create an Azure app registration + +First, create an Azure app registration: + +1. Log in to your [Azure portal](https://portal.azure.com/). +2. Using the search bar, go to the [App registrations](https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade) page. +3. Select **New registration** and fill in the required fields. + + + In the **Supported account types** section, choose the account type that's most appropriate for your use case—we support both [single tenant](https://learn.microsoft.com/en-us/security/zero-trust/develop/identity-supported-account-types#accounts-in-this-organizational-directory-only---single-tenant) (app available for your organization only) and [multitenant](https://learn.microsoft.com/en-us/security/zero-trust/develop/identity-supported-account-types#accounts-in-any-organizational-directory-only---multitenant) (public app) accounts. + + +4. When you're done filling in the fields, select **Register**. + +### Step 2: Setup in Botpress + +Next, setup the integration in Botpress: + + + + + 1. In Botpress Studio, select ** Explore Hub** in the upper-right corner. + 2. Search for the **Microsoft Teams** integration, then select **Install Integration**. + + + To configure the integration, you need to create a webhook endpoint for the Teams integration. To do this, fill in the integration's **Configuration** fields using information from your Azure app: + + + + In the **Overview** section of your Azure app, copy the **Application (client) ID**. Then, paste it in the **App ID** field in Botpress. + + + 1. In your Azure app's left sidebar, go to **Manage > Certificates & secrets**. + 2. Select **New client secret**. + 3. Set a description and expiry date for your secret. + 4. Copy the **Value** of the generated secret. + 5. Paste it in the **App Password** field in Botpress. + + + In the **Overview** section of your Azure app, copy the **Directory (tenant) ID**. Then, paste it in the **Tenant ID** field in Botpress. + + + + When you’ve filled in all the fields, select **Save Configuration**. This will automatically enable your integration. + + + +### Step 3: Create a Microsoft bot + + + + Now, you need to create a Microsoft bot. This bot communicates with your Botpress webhook URL to chat with members of your Teams workspace. + + 1. In your Azure portal homepage, select **Create a resource**. + 2. Search for **Azure Bot**, then select **Create**. + 3. Scroll to the **Creation type** section, then select **Use existing app registration**. + 4. Fill in the **App ID** and **App tenant ID** fields with the same app ID and tenant ID you used to configure the integration in Botpress. + 5. Fill in the other required fields as necessary. + 6. Select **Review + Create**, then **Create**. + + + Now that you've created a Microsoft bot, you can use the integration's webhook to connect it to your Botpress bot: + + 1. Wait for the bot's deployment to complete, then select **Go to resource**. + 2. In the left sidebar, go to **Settings > Configuration**. + 3. Paste the Botpress webhook URL (starting with `https://webhook.botpress.cloud/`) into the **Messaging endpoint** field. You can find the webhook URL in the integration's configuration menu. + 4. Select **Apply**. + 5. In the left sidebar, go to **Settings > Channels**. + 6. Scroll down and select **Microsoft Teams**. + + + Make sure you actually select the **Microsoft Teams** text, or the channel configuration menu won't open. + + + 7. Agree to the terms of service, then select **Apply**. + + + While you're still in the **Settings > Configuration** menu, copy your **Microsoft App ID**—you'll need it for the next steps. + + + +### Step 4: Create a Teams app + +Finally, create an app in your Teams developer portal: + + + + First, create a new app: + + 1. Log in to the [Teams developer portal](https://dev.teams.microsoft.com/home) + 2. Select **Create a new app** and enter a name for the app. + 3. In the left sidebar, go to the **Basic information** section. + 4. Fill in the required fields: + + - **Short name** + - **Long name** + - **Short description** + - **Long description** + - **Developer or company name** + - **Website** + - **Privacy policy** + + + This information will be shown to members of your Teams workspace that chat with your bot. + + + 5. In the **Application (client ID)** field, paste the **Microsoft App ID** you copied earlier. + 6. At the bottom of the screen, select **Save**. + + + Next, add your Azure bot to the app: + + 1. In the left sidebar, go to **App features** and select **Bot**. + 2. Select **Enter a bot ID**, then paste the **Microsoft App ID** again. + 3. Select the **Personal**, **Team** and **Group** chat scopes. + 4. Select **Save**. + + + In the left sidebar, go to **Permissions**. Select the following permissions for your app: + + + + + Under **Application**: + + - `ChannelMessage.Read.Group` + - `ChannelMessage.Send.Group` + - `TeamsActivity.Send.Group` + + + Under **Application**: + + - `ChatMessage.Read.Chat` + - `ChatMessage.Send.Chat` + - `ChatMessageReadReceipt.Read.Chat` + - `TeamsActivity.Send.Chat` + - `TeamsTab.ReadWrite.Chat` + - `TeamsTab.Read.Chat` + + Under **Delegated**: + + - `LiveShareSession.ReadWrite.Chat` + + + + When you're done, select **Save**. + + + Now, the bot should be fully configured. To test it: + + 1. In the upper-right corner, select **Preview in Teams**. + 2. Once the bot has opened in Teams, select **Add**. + 3. After the bot is added, select **Open** to start chatting with it (or a channel to use it in). + + + If you get a **Manifest parsing failed** error message, make sure you filled out all the required fields in your app's **Basic Information** section. The **Short description** and **Long description** fields are required, even though they're not marked as such. + + + -The bot will only be available to you if you have a Microsoft 365 Business account and if you are logged in to MS Teams with that account. + At this point, the bot is only available for you to test. To make it available for anyone in your organization, follow the steps below. -## Making the bot available in your Organization - -1. Add the Developer Portal App to your Teams (or do it via the website) - - - -2. Click the **Developer Portal App** tab in the sidebar, then **Apps**. Now click the **New app** button +### Step 5: Publish the bot to your organization - +Finally, you can publish your bot to make it available for anyone in your organization: -3. In the left-side menu of the App, go to the **App Features** page under the **Configure** section then click "Bot" +1. Go back to your app's menu in the [Teams developer portal](https://dev.teams.microsoft.com/home). +2. In the app's left sidebar, go to **Publish > Publish to org**. +3. Select **Get started**. - +If you're an admin, your app will be approved automatically. Otherwise, your request to publish the app will need to be approved by an admin in the [Teams admin center](https://admin.teams.microsoft.com/policies/manage-apps). -4. Select your existing bot from BotFramework in the dropdown. Check the desired scopes (at least **Personal** for 1:1 conversations) + + Your Teams integration is ready. Once the app has been approved, anyone in your Teams organization can [add it](https://support.microsoft.com/en-us/office/add-an-app-to-microsoft-teams-b2217706-f7ed-4e64-8e96-c413afd02f77) and chat with your bot. + - - -5. Fill out all the required fields in the Basic Information page of the Configure section - - - -6. Click **Publish**, then **Publish to your Org** - - - -7. Go to your Team App store, search for your app, then add it - - - -8. The bot is now available in the **App** section to all members of your organization! - - -Info - -In order to update your bot's behavior, just **Publish** the new version in Botpress. The changes will then be reflected in MS Teams, there's no need to change any settings in the Microsoft apps. - - - -Note - -Botpress verifies the signature of the requests coming to the Webhook URL so that only Microsoft Teams can send data to your bot. Requests made from Postman or any other means will be rejected. - - -## Setting up policies - - +--- -If you're unable to send message to the bot (App), make sure you've enabled the policy to upload custom apps.\ -Go to Setup Policies -> Turn on **Upload custom apps** +## Troubleshooting + + + + If you get a **Manifest parsing failed** error message when trying to [preview your bot in Teams](#create-a-teams-app), make sure you filled all the required fields in your app's **Basic Information** section. + + + The **Short description** and **Long description** fields are required, even though they're not marked as such. + + + + If you're unable to [preview your bot in Teams](#create-a-teams-app), make sure you've enabled the policy to allow uploading custom apps: + + 1. Log in to the [Teams admin center](https://admin.teams.microsoft.com). + 2. In the left sidebar, go to **Teams apps > Setup policies**. + 3. Select **Global (Org-wide default)** + 4. Make sure **Upload custom apps** is turned on. + 5. Select **Save**. + + + Changes to this policy might not take effect immediately. If you still can't access the preview in Teams even after updating, wait a while and try again. + + + ---