Microsoft Teams integration setup

Integrating ThoughtFarmer with Microsoft Teams allows users to:

• Search the intranet directly from Teams.
• See intranet link previews within Teams conversations.
• Receive notifications about intranet activity in Teams channels.

Setup overview

To enable Microsoft Teams integration, complete the following steps:

1. Create a Microsoft Teams app
2. Publish the app to your organization
3. Configure Microsoft Teams settings in ThoughtFarmer
4. Add the ThoughtFarmer app to individual Teams

Create a Microsoft Teams App for ThoughtFarmer

Create the App

1. Go to the Microsoft Teams Developer Portal and login.
2. Navigate to Apps.
3. Click New app.
4. Enter a name for the app 
5. Click Create.

Configure basic information

1. On the new Dashboard screen, under Basic information, fill in the required fields. If any required fields are missing, the app validation process will fail.
   • Short name
   • Short and long description
   • Developer or company name
   • Website
   • Privacy policy
   • Terms of use.
2. Click Save.
3. (Optional) Under Branding you can:
   • Upload custom icons
   • Choose an accent color.

Create a Bot for ThoughtFarmer in Microsoft Teams

Create the Bot

1. In the Microsoft Teams Developer Portal, select Tools (pencil icon) on the left
2. Open Bot Management.
3. Click New bot.
4. Enter a name for your bot 
5. Click Add.
   
   

Configure the Bot

1. Under Configure, set the Endpoint address as

   1. https://your-thoughtfarmer-url.com/msteams/bot

      • Replace your-thoughtfarmer-url.com with your ThoughtFarmer site URL.
        
        
         
2. Click Save and wait for the confirmation message.

Generate and store a client secret

1. Select Client secrets.
2. Click Create your first client secret.
3. Copy the generated client secret and store it securely. This secret will later be required in the ThoughtFarmer Microsoft Teams integration settings.
4. Click Done.

Link the bot to your app

1. Select Apps on the left-hand menu and select the app you created earlier.
2. Navigate to Configure > App features > Bot.
3. Select your newly created bot from the Select an existing bot dropdown menu.
4. Under Select the scopes where people can use your bot, select:
   1. Personal
   2. Teams
5. Click Save.

Enable link unfurls and search in Microsoft Teams

These steps will enable intranet search within Microsoft Teams and allow links pasted into a Microsoft Teams channel to unfurl, displaying details about the linked ThoughtFarmer page.

Enable message extension

1. Navigate to Configure > App Features.
2. Select Messaging extension.
3. When prompted, select your newly created bot from the Select an existing bot dropdown menu.

Enable link unfurling

1. Under Link unfurling, click Add domain.
2. In the Add domain window, enter your ThoughtFarmer intranet's URL. (eg. myintranet.thoughtfarmer.com)
3. Click Add.
4. Click Save.

Add required domains

1. Navigate to Configure > Domains.
2. Click Add a domain.
3. Add the URL: token.botframeworks.com.
4. Add your ThoughtFarmer intranet's URL. 
5. Click Save.

Manifest configurations 

Enable Message Handlers

1. Navigate to Configure > App package editor.
2. Click on the manifest.json file. This will open the file in a JSON editor.
3. Add a comma after the validDomains[] node.
4. Add the following value: "supportsChannelFeatures": "tier1".
5. Under the composeExtensions > messageHandlers node, set the type value to link.

Enable search functionality

To enable searching, find the section composeExtensions > commands which has a default value of [], and insert this value:

{
  "id": "search",
  "type": "query",
  "title": "Search",
  "description": "Search ThoughtFarmer",
  "initialRun": true,
  "fetchTask": false,
  "context": [
    "commandBox",
    "compose"
  ],
  "parameters": [
    {
      "name": "query",
      "title": "Query",
      "description": "Your search query",
      "inputType": "text"
    }
  ]
}

Click Save.

In the App package editor page, an information message will appear to update the app package. Click Update, and click Confirm.

Once these steps are complete, Microsoft Teams users will be able to search the ThoughtFarmer intranet directly from Teams and see previews of links when they are pasted in a channel.

Command title and description fields: Show in command menu when you @mention the intranet bot.

Parameter description field: Shows in the search field when you open the intranet app from ... menu

Publish the App to your organization

Once you've configured your ThoughtFarmer integration in Microsoft Teams, the final step is to publish the app so that your organization can access it.

Validate the app

1. Navigate to Publish > App validation.
2. Click Get Started.
3. Select all of the Validation Acknowledgement checkboxes.
4. Click Start Validation.
5. Review the validation results and ensure there are no errors in your app configuration.

Prepare and submit the app for approval

1. Navigate to the Publish > Publish to org.
2. Click Publish to submit the app for approval.
3. The app will now require approval from a Teams administrator within your organization.

Approve the app (admin action required)

An organization admin must complete the following steps to approve the app:

1. In the Microsoft Teams Admin Center, go to Teams apps > Manage apps.
2. Locate the Pending approval section.
3. Find the submitted app in the list and click on it.
4. Click Allow the app, then Publish it to make it available to the entire organization.

Once published, users in your organization will be able to find and install the app in Microsoft Teams.

Register app with Entra ID

Following these instructions allows admins to log in to their Microsoft Teams accounts within ThoughtFarmer, so that they can select teams and channels when setting up activity messages.

1. Go to Entra ID > App registrations.
2. Select the Bot you created (An auto-registration will have been created for the Bot you created).
3. Open the Authentication tab.
4. Click Add Redirect URI.
5. Under Configure platforms, click Single-page application.
6. Add the Redirect URI:  https://your-thoughtfarmer-url.com/msteams/auth/complete/graphapi 
7. Select the checkboxes:
   • Access tokens (used for implicit flows)
   • ID tokens (used for implicit and hybrid flows)
8. Click Save.
   

Configure API Permissions

1. Open the API permissions tab.
2. Click Add a permission.
3. Select Microsoft Graph.
4. Click Delegated permissions.
5. Add the following permissions:
   • Under User > User.Read
   • Under Channel > Channel.ReadBasic.All
   • Under Team > Team.ReadBasic.All
6. Click Add permissions. 
7. Click Grant Admin consent.

Configure Microsoft Teams Settings in ThoughtFarmer

1. Navigate to Admin panel: Integrations section > Microsoft Teams page.
2. Under the App configuration tab, enter:
3. Microsoft Tenant ID.
   • The Tenant ID is your organization's ID in Microsoft Entra ID. One way to find this is to click this URL: https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/Properties
     This will take you to your Microsoft Entra ID, where you can see and copy your Microsoft Tenant ID.
4. Enter your Bot ID.
   • To find your Bot ID, go to the Microsoft Developer Portal, Tools section. Click on Bot management. Copy the Bot ID beside the Microsoft Teams App Bot you created. (If you haven't generated a bot secret for the bot already, see the Create a bot heading.) Paste the Bot ID into ThoughtFarmer.
5. Enter your Bot secret.
   • This is the Bot secret that you created and saved during the steps under the Create a bot heading.
6. Enter your Client ID. (For more information, see Client ID heading below.)
7. Click Save.
8. Under the Link previews and search tab, enter Search. (This is the command ID that you entered when you were enabling search for the Microsoft Teams app in the Microsoft Developer Portal).
9. Click Save.

Client ID

The client ID is the ID for an Azure app that is configured to allow users to log in and ask for information about teams and channels. It can be the same as your Bot ID, your existing Microsoft Cloud Drive client ID, or a new client ID that you create. The easiest setup is generally to have the Client ID be the same as the Bot ID. Client ID is the value that makes it possible to log in to your Microsoft Teams account and select a Team and Channel when setting up an activity message.

Enable the Microsoft Teams integration

Once you have set up the Microsoft Teams integration, you may wish to set up activity messages or add security groups for link unfurls and search results before you enable the integration on your intranet. To learn more about these configuration options, see Microsoft Teams integration configuration.

Once you are ready to enable the integration, go to the ThoughtFarmer Admin panel: Integrations section > Microsoft Teams page, and turn the Enable toggle to ON.